def create_dispute_evidence_text(self, dispute_id, body):
"""Does a POST request to /v2/disputes/{dispute_id}/evidence_text.
Uploads text to use as evidence for a dispute challenge.
Args:
dispute_id (string): The ID of the dispute you want to upload
evidence for.
body (CreateDisputeEvidenceTextRequest): An object containing the
fields to POST for the request. See the corresponding object
definition for field details.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/disputes/{dispute_id}/evidence_text'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'dispute_id': {
'value': dispute_id,
'encode': True
}})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(
_query_url,
headers=_headers,
parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def submit_evidence(self, dispute_id):
"""Does a POST request to /v2/disputes/{dispute_id}/submit-evidence.
Submits evidence to the cardholder's bank.
Before submitting evidence, Square compiles all available evidence.
This includes
evidence uploaded using the
[CreateDisputeEvidenceFile](https://developer.squareup.com/docs/referen
ce/square/disputes-api/create-dispute-evidence-file) and
[CreateDisputeEvidenceText](https://developer.squareup.com/docs/referen
ce/square/disputes-api/create-dispute-evidence-text) endpoints,
and evidence automatically provided by Square, when
available.
Args:
dispute_id (string): The ID of the dispute you want to submit
evidence for.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/disputes/{dispute_id}/submit-evidence'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'dispute_id': {
'value': dispute_id,
'encode': True
}})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.post(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def add_group_to_customer(self, customer_id, group_id):
"""Does a PUT request to /v2/customers/{customer_id}/groups/{group_id}.
Adds a group membership to a customer.
The customer is identified by the `customer_id` value
and the customer group is identified by the `group_id` value.
Args:
customer_id (string): The ID of the customer to add to a group.
group_id (string): The ID of the customer group to add the
customer to.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/customers/{customer_id}/groups/{group_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {
'customer_id': {
'value': customer_id,
'encode': True
},
'group_id': {
'value': group_id,
'encode': True
}
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.put(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def update_booking(self, booking_id, body):
"""Does a PUT request to /v2/bookings/{booking_id}.
Updates a booking.
Args:
booking_id (string): The ID of the [Booking](#type-booking) object
representing the to-be-updated booking.
body (UpdateBookingRequest): An object containing the fields to
POST for the request. See the corresponding object definition
for field details.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/bookings/{booking_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'booking_id': {
'value': booking_id,
'encode': True
}})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.put(
_query_url,
headers=_headers,
parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def create_payment(self, body):
"""Does a POST request to /v2/payments.
Creates a payment using the provided source. You can use this endpoint
to charge a card (credit/debit card or
Square gift card) or record a payment that the seller received outside
of Square
(cash payment from a buyer or a payment that an external entity
procesed on behalf of the seller).
The endpoint creates a
`Payment` object and returns it in the response.
Args:
body (CreatePaymentRequest): An object containing the fields to
POST for the request. See the corresponding object definition
for field details.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/payments'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(
_query_url,
headers=_headers,
parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def list_employee_roles(self, order=None, limit=None, batch_token=None):
"""Does a GET request to /v1/me/roles.
Provides summary information for all of a business's employee roles.
Args:
order (SortOrder, optional): The order in which employees are
listed in the response, based on their created_at
field.Default value: ASC
limit (int, optional): The maximum integer number of employee
entities to return in a single response. Default 100, maximum
200.
batch_token (string, optional): A pagination cursor to retrieve
the next set of results for your original query to the
endpoint.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v1/me/roles'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {
'order': order,
'limit': limit,
'batch_token': batch_token
}
_query_builder = APIHelper.append_url_with_query_parameters(
_query_builder, _query_parameters)
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.get(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def create_employee(self,
body):
"""Does a POST request to /v1/me/employees.
Use the CreateEmployee endpoint to add an employee to a Square
account. Employees created with the Connect API have an initial
status
of `INACTIVE`. Inactive employees cannot sign in to Square Point of
Sale
until they are activated from the Square Dashboard. Employee status
cannot be changed with the Connect API.
<aside class="important">
Employee entities cannot be deleted. To disable employee profiles,
set the employee's status to <code>INACTIVE</code>
</aside>
Args:
body (V1Employee): An object containing the fields to POST for the
request. See the corresponding object definition for field
details.
Returns:
V1Employee: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v1/me/employees'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def create_subscription(self, body):
"""Does a POST request to /v2/subscriptions.
Creates a subscription for a customer to a subscription plan.
If you provide a card on file in the request, Square charges the card
for
the subscription. Otherwise, Square bills an invoice to the customer's
email
address. The subscription starts immediately, unless the request
includes
the optional `start_date`. Each individual subscription is associated
with a particular location.
Args:
body (CreateSubscriptionRequest): An object containing the fields
to POST for the request. See the corresponding object
definition for field details.
Returns:
CreateSubscriptionResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/subscriptions'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(
_query_url,
headers=_headers,
parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def delete_timecard(self, timecard_id):
"""Does a DELETE request to /v1/me/timecards/{timecard_id}.
Deletes a timecard. Timecards can also be deleted through the
Square Dashboard. Deleted timecards are still accessible through
Connect API endpoints, but cannot be modified. The `deleted` field of
the `Timecard` object indicates whether the timecard has been
deleted.
__Note__: By default, deleted timecards appear alongside valid
timecards in
results returned by the
[ListTimecards](#endpoint-v1employees-listtimecards)
endpoint. To filter deleted timecards, include the `deleted` query
parameter in the list request.
Only approved accounts can manage their employees with Square.
Unapproved accounts cannot use employee management features with the
API.
Args:
timecard_id (string): The ID of the timecard to delete.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v1/me/timecards/{timecard_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'timecard_id': {
'value': timecard_id,
'encode': True
}})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare and execute request
_request = self.config.http_client.delete(_query_url)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = _response.text
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def cancel_invoice(self,
invoice_id,
body):
"""Does a POST request to /v2/invoices/{invoice_id}/cancel.
Cancels an invoice. The seller cannot collect payments for
the canceled invoice.
You cannot cancel an invoice in the `DRAFT` state or in a terminal
state: `PAID`, `REFUNDED`, `CANCELED`, or `FAILED`.
Args:
invoice_id (string): The ID of the [invoice](#type-invoice) to
cancel.
body (CancelInvoiceRequest): An object containing the fields to
POST for the request. See the corresponding object definition
for field details.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/invoices/{invoice_id}/cancel'
_url_path = APIHelper.append_url_with_template_parameters(_url_path, {
'invoice_id': {'value': invoice_id, 'encode': True}
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def search_invoices(self,
body):
"""Does a POST request to /v2/invoices/search.
Searches for invoices from a location specified in
the filter. You can optionally specify customers in the filter for
whom to
retrieve invoices. In the current implementation, you can only specify
one location and
optionally one customer.
The response is paginated. If truncated, the response includes a
`cursor`
that you use in a subsequent request to fetch the next set of
invoices.
Args:
body (SearchInvoicesRequest): An object containing the fields to
POST for the request. See the corresponding object definition
for field details.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/invoices/search'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def search_loyalty_events(self, body):
"""Does a POST request to /v2/loyalty/events/search.
Searches for loyalty events.
A Square loyalty program maintains a ledger of events that occur
during the lifetime of a
buyer's loyalty account. Each change in the point balance
(for example, points earned, points redeemed, and points expired) is
recorded in the ledger. Using this endpoint, you can search the ledger
for events.
Search results are sorted by `created_at` in descending order.
Args:
body (SearchLoyaltyEventsRequest): An object containing the fields
to POST for the request. See the corresponding object
definition for field details.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/loyalty/events/search'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(
_query_url,
headers=_headers,
parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def create_order(self, body):
"""Does a POST request to /v2/orders.
Creates a new [order]($m/Order) that can include information about
products for
purchase and settings to apply to the purchase.
To pay for a created order, see
[Pay for
Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders).
You can modify open orders using the
[UpdateOrder]($e/Orders/UpdateOrder) endpoint.
Args:
body (CreateOrderRequest): An object containing the fields to POST
for the request. See the corresponding object definition for
field details.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/orders'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(
_query_url,
headers=_headers,
parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def void_transaction(self,
location_id,
transaction_id):
"""Does a POST request to /v2/locations/{location_id}/transactions/{transaction_id}/void.
Cancels a transaction that was created with the
[Charge](#endpoint-charge)
endpoint with a `delay_capture` value of `true`.
See [Delayed capture
transactions](https://developer.squareup.com/docs/payments/transactions
/overview#delayed-capture)
for more information.
Args:
location_id (string): TODO: type description here.
transaction_id (string): TODO: type description here.
Returns:
VoidTransactionResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/locations/{location_id}/transactions/{transaction_id}/void'
_url_path = APIHelper.append_url_with_template_parameters(_url_path, {
'location_id': location_id,
'transaction_id': transaction_id
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json'
}
# Prepare and execute request
_request = self.config.http_client.post(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def create_customer(self,
body):
"""Does a POST request to /v2/customers.
Creates a new customer for a business, which can have associated cards
on file.
You must provide __at least one__ of the following values in your
request to this
endpoint:
- `given_name`
- `family_name`
- `company_name`
- `email_address`
- `phone_number`
Args:
body (CreateCustomerRequest): An object containing the fields to
POST for the request. See the corresponding object definition
for field details.
Returns:
CreateCustomerResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/customers'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def retrieve_snippet(self, site_id):
"""Does a GET request to /v2/sites/{site_id}/snippet.
Retrieves your snippet from a Square Online site. A site can contain
snippets from multiple snippet applications, but you can retrieve only
the snippet that was added by your application.
You can call [ListSites]($e/Sites/ListSites) to get the IDs of the
sites that belong to a seller.
__Note:__ Square Online APIs are publicly available as part of an
early access program. For more information, see [Early access program
for Square Online
APIs](https://developer.squareup.com/docs/online-api#early-access-progr
am-for-square-online-apis).
Args:
site_id (string): The ID of the site that contains the snippet.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/sites/{site_id}/snippet'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'site_id': {
'value': site_id,
'encode': True
}})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.get(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def retrieve_order(self, location_id, order_id):
"""Does a GET request to /v1/{location_id}/orders/{order_id}.
Provides comprehensive information for a single online store order,
including the order's history.
Args:
location_id (string): The ID of the order's associated location.
order_id (string): The order's Square-issued ID. You obtain this
value from Order objects returned by the List Orders endpoint
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v1/{location_id}/orders/{order_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {
'location_id': {
'value': location_id,
'encode': True
},
'order_id': {
'value': order_id,
'encode': True
}
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.get(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def retrieve_cash_drawer_shift(self, location_id, shift_id):
"""Does a GET request to /v1/{location_id}/cash-drawer-shifts/{shift_id}.
Provides the details for a single cash drawer shift, including all
events that occurred during the shift.
Args:
location_id (string): The ID of the location to list cash drawer
shifts for.
shift_id (string): The shift's ID.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v1/{location_id}/cash-drawer-shifts/{shift_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {
'location_id': {
'value': location_id,
'encode': True
},
'shift_id': {
'value': shift_id,
'encode': True
}
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.get(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def update_team_member(self, team_member_id, body):
"""Does a PUT request to /v2/team-members/{team_member_id}.
Updates a single `TeamMember` object. The `TeamMember` will be
returned on successful updates.
Learn about [Troubleshooting the Teams
API](https://developer.squareup.com/docs/docs/team/troubleshooting#upda
teteammember).
Args:
team_member_id (string): The ID of the team member to update.
body (UpdateTeamMemberRequest): An object containing the fields to
POST for the request. See the corresponding object definition
for field details.
Returns:
UpdateTeamMemberResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/team-members/{team_member_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'team_member_id': team_member_id})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.put(
_query_url,
headers=_headers,
parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def update_invoice(self,
invoice_id,
body):
"""Does a PUT request to /v2/invoices/{invoice_id}.
Updates an invoice by modifying field values, clearing field values,
or both
as specified in the request.
There are no restrictions to updating an invoice in a draft state.
However, there are guidelines for updating a published invoice.
Args:
invoice_id (string): The id of the invoice to update.
body (UpdateInvoiceRequest): An object containing the fields to
POST for the request. See the corresponding object definition
for field details.
Returns:
UpdateInvoiceResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/invoices/{invoice_id}'
_url_path = APIHelper.append_url_with_template_parameters(_url_path, {
'invoice_id': invoice_id
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.put(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def complete_payment(self,
payment_id):
"""Does a POST request to /v2/payments/{payment_id}/complete.
Completes (captures) a payment.
By default, payments are set to complete immediately after they are
created.
If you set autocomplete to false when creating a payment, you can
complete (capture)
the payment using this endpoint. For more information, see
[Delayed
Payments](https://developer.squareup.com/docs/payments-api/take-payment
s#delayed-payments).
Args:
payment_id (string): Unique ID identifying the payment to be
completed.
Returns:
CompletePaymentResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/payments/{payment_id}/complete'
_url_path = APIHelper.append_url_with_template_parameters(_url_path, {
'payment_id': payment_id
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json'
}
# Prepare and execute request
_request = self.config.http_client.post(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def delete_loyalty_reward(self,
reward_id):
"""Does a DELETE request to /v2/loyalty/rewards/{reward_id}.
Deletes a loyalty reward by doing the following:
- Returns the loyalty points back to the loyalty account.
- If an order ID was specified when the reward was created
(see [CreateLoyaltyReward](#endpoint-Loyalty-CreateLoyaltyReward)),
it updates the order by removing the reward and related
discounts.
You cannot delete a reward that has reached the terminal state
(REDEEMED).
Args:
reward_id (string): The ID of the [loyalty
reward](#type-LoyaltyReward) to delete.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/loyalty/rewards/{reward_id}'
_url_path = APIHelper.append_url_with_template_parameters(_url_path, {
'reward_id': {'value': reward_id, 'encode': True}
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json'
}
# Prepare and execute request
_request = self.config.http_client.delete(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def list_bank_accounts(self, location_id):
"""Does a GET request to /v1/{location_id}/bank-accounts.
Provides non-confidential details for all of a location's associated
bank accounts. This endpoint does not provide full bank account
numbers, and there is no way to obtain a full bank account number with
the Connect API.
---
- __Deprecation date__: 2020-02-26
- [__Retirement
date__](https://developer.squareup.com/docs/docs/build-basics/api-lifec
ycle#deprecated): 2021-02-26
- [Migration
guide](https://developer.squareup.com/docs/docs/migrate-from-v1/guides/
v1-bankaccounts)
---
Args:
location_id (string): The ID of the location to list bank accounts
for.
Returns:
list of V1BankAccount: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v1/{location_id}/bank-accounts'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'location_id': location_id})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.get(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def list_workweek_configs(self,
limit=None,
cursor=None):
"""Does a GET request to /v2/labor/workweek-configs.
Returns a list of `WorkweekConfig` instances for a business.
Args:
limit (int, optional): Maximum number of Workweek Configs to
return per page.
cursor (string, optional): Pointer to the next page of Workweek
Config results to fetch.
Returns:
ListWorkweekConfigsResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/labor/workweek-configs'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {
'limit': limit,
'cursor': cursor
}
_query_builder = APIHelper.append_url_with_query_parameters(
_query_builder,
_query_parameters
)
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json'
}
# Prepare and execute request
_request = self.config.http_client.get(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def create_loyalty_reward(self,
body):
"""Does a POST request to /v2/loyalty/rewards.
Creates a loyalty reward. In the process, the endpoint does
following:
- Uses the `reward_tier_id` in the request to determine the number of
points
to lock for this reward.
- If the request includes `order_id`, it adds the reward and related
discount to the order.
After a reward is created, the points are locked and
not available for the buyer to redeem another reward.
Args:
body (CreateLoyaltyRewardRequest): An object containing the fields
to POST for the request. See the corresponding object
definition for field details.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/loyalty/rewards'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def delete_catalog_object(self, object_id):
"""Does a DELETE request to /v2/catalog/object/{object_id}.
Deletes a single [CatalogObject](#type-catalogobject) based on the
provided ID and returns the set of successfully deleted IDs in the
response.
Deletion is a cascading event such that all children of the targeted
object
are also deleted. For example, deleting a
[CatalogItem](#type-catalogitem)
will also delete all of its
[CatalogItemVariation](#type-catalogitemvariation) children.
Args:
object_id (string): The ID of the
[CatalogObject](#type-catalogobject) to be deleted. When an
object is deleted, other objects in the graph that depend on
that object will be deleted as well (for example, deleting a
[CatalogItem](#type-catalogitem) will delete its
[CatalogItemVariation](#type-catalogitemvariation)s).
Returns:
DeleteCatalogObjectResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/catalog/object/{object_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'object_id': object_id})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.delete(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def batch_retrieve_inventory_changes(self, body):
"""Does a POST request to /v2/inventory/batch-retrieve-changes.
Returns historical physical counts and adjustments based on the
provided filter criteria.
Results are paginated and sorted in ascending order according their
`occurred_at` timestamp (oldest first).
BatchRetrieveInventoryChanges is a catch-all query endpoint for
queries
that cannot be handled by other, simpler endpoints.
Args:
body (BatchRetrieveInventoryChangesRequest): An object containing
the fields to POST for the request. See the corresponding
object definition for field details.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/inventory/batch-retrieve-changes'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(
_query_url,
headers=_headers,
parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def search_catalog_objects(self, body):
"""Does a POST request to /v2/catalog/search.
Queries the targeted catalog using a variety of query types:
[CatalogQuerySortedAttribute](#type-catalogquerysortedattribute),
[CatalogQueryExact](#type-catalogqueryexact),
[CatalogQueryRange](#type-catalogqueryrange),
[CatalogQueryText](#type-catalogquerytext),
[CatalogQueryItemsForTax](#type-catalogqueryitemsfortax), and
[CatalogQueryItemsForModifierList](#type-catalogqueryitemsformodifierli
st).
Args:
body (SearchCatalogObjectsRequest): An object containing the
fields to POST for the request. See the corresponding object
definition for field details.
Returns:
SearchCatalogObjectsResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/catalog/search'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(
_query_url,
headers=_headers,
parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def refund_payment(self, body):
"""Does a POST request to /v2/refunds.
Refunds a payment. You can refund the entire payment amount or a
portion of it. You can use this endpoint to refund a card payment or
record a
refund of a cash or external payment. For more information, see
[Refund
Payment](https://developer.squareup.com/docs/payments-api/refund-paymen
ts).
Args:
body (RefundPaymentRequest): An object containing the fields to
POST for the request. See the corresponding object definition
for field details.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/refunds'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(
_query_url,
headers=_headers,
parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def update_subscription(self,
subscription_id,
body):
"""Does a PUT request to /v2/subscriptions/{subscription_id}.
Updates a subscription. You can set, modify, and clear the
`subscription` field values. For more information and examples, see
[Update
subscriptions](https://developer.squareup.com/docs/docs/subscriptions-a
pi/overview#update-subscriptions).
Args:
subscription_id (string): The ID for the subscription to update.
body (UpdateSubscriptionRequest): An object containing the fields
to POST for the request. See the corresponding object
definition for field details.
Returns:
UpdateSubscriptionResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/subscriptions/{subscription_id}'
_url_path = APIHelper.append_url_with_template_parameters(_url_path, {
'subscription_id': subscription_id
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.put(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
