def adjust_loyalty_points(self, account_id, body):
"""Does a POST request to /v2/loyalty/accounts/{account_id}/adjust.
Adds points to or subtracts points from a buyer's account.
Use this endpoint only when you need to manually adjust points.
Otherwise, in your application flow, you call
[AccumulateLoyaltyPoints]($e/Loyalty/AccumulateLoyaltyPoints)
to add points when a buyer pays for the purchase.
Args:
account_id (string): The ID of the [loyalty
account]($m/LoyaltyAccount) in which to adjust the points.
body (AdjustLoyaltyPointsRequest): 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/accounts/{account_id}/adjust'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'account_id': {
'value': account_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 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.
---
- __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-cashdrawershifts)
---
Args:
location_id (string): The ID of the location to list cash drawer
shifts for.
shift_id (string): The shift's ID.
Returns:
V1CashDrawerShift: 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}/cash-drawer-shifts/{shift_id}'
_url_path = APIHelper.append_url_with_template_parameters(_url_path, {
'location_id': location_id,
'shift_id': shift_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 retrieve_timecard(self,
timecard_id):
"""Does a GET request to /v1/me/timecards/{timecard_id}.
Provides the details for a single timecard.
---
- __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-timecards)
---
<aside>
Only approved accounts can manage their employees with Square.
Unapproved accounts cannot use employee management features with the
API.
</aside>
Args:
timecard_id (string): The timecard's ID.
Returns:
V1Timecard: 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/timecards/{timecard_id}'
_url_path = APIHelper.append_url_with_template_parameters(_url_path, {
'timecard_id': timecard_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 create_customer_card(self, customer_id, body):
"""Does a POST request to /v2/customers/{customer_id}/cards.
Adds a card on file to an existing customer.
As with charges, calls to `CreateCustomerCard` are idempotent.
Multiple
calls with the same card nonce return the same card record that was
created
with the provided nonce during the _first_ call.
Cards on file are automatically updated on a monthly basis to confirm
they
are still valid and can be charged.
Args:
customer_id (string): The Square ID of the customer profile the
card is linked to.
body (CreateCustomerCardRequest): An object containing the fields
to POST for the request. See the corresponding object
definition for field details.
Returns:
CreateCustomerCardResponse: 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/{customer_id}/cards'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'customer_id': customer_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.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_bank_account(self, location_id, bank_account_id):
"""Does a GET request to /v1/{location_id}/bank-accounts/{bank_account_id}.
Provides non-confidential details for a merchant's associated bank
account. 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 bank account's associated
location.
bank_account_id (string): The bank account's Square-issued ID. You
obtain this value from Settlement objects returned.
Returns:
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/{bank_account_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {
'location_id': location_id,
'bank_account_id': bank_account_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 retrieve_inventory_count(self,
catalog_object_id,
location_ids=None,
cursor=None):
"""Does a GET request to /v2/inventory/{catalog_object_id}.
Retrieves the current calculated stock count for a given
[CatalogObject](#type-catalogobject) at a given set of
[Location](#type-location)s. Responses are paginated and unsorted.
For more sophisticated queries, use a batch endpoint.
Args:
catalog_object_id (string): ID of the
[CatalogObject](#type-catalogobject) to retrieve.
location_ids (string, optional): The [Location](#type-location)
IDs to look up as a comma-separated list. An empty list
queries all locations.
cursor (string, optional): A pagination cursor returned by a
previous call to this endpoint. Provide this to retrieve the
next set of results for the original query. See the
[Pagination](https://developer.squareup.com/docs/docs/working-w
ith-apis/pagination) guide for more information.
Returns:
RetrieveInventoryCountResponse: 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/inventory/{catalog_object_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'catalog_object_id': catalog_object_id})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {'location_ids': location_ids, '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 redeem_loyalty_reward(self,
reward_id,
body):
"""Does a POST request to /v2/loyalty/rewards/{reward_id}/redeem.
Redeems a loyalty reward.
The endpoint sets the reward to the `REDEEMED` terminal state.
If you are using your own order processing system (not using the
Orders API), you call this endpoint after the buyer paid for the
purchase.
After the reward reaches the terminal state, it cannot be deleted.
In other words, points used for the reward cannot be returned
to the account.
Args:
reward_id (string): The ID of the [loyalty
reward](#type-LoyaltyReward) to redeem.
body (RedeemLoyaltyRewardRequest): 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/{reward_id}/redeem'
_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',
'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_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/team/troubleshooting#update-a-
team-member).
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:
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/team-members/{team_member_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path,
{'team_member_id': {
'value': team_member_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 remove_dispute_evidence(self, dispute_id, evidence_id):
"""Does a DELETE request to /v2/disputes/{dispute_id}/evidence/{evidence_id}.
Removes specified evidence from a dispute.
Square does not send the bank any evidence that is removed. Also, you
cannot remove evidence after
submitting it to the bank using
[SubmitEvidence](https://developer.squareup.com/docs/reference/square/d
isputes-api/submit-evidence).
Args:
dispute_id (string): The ID of the dispute you want to remove
evidence from.
evidence_id (string): The ID of the evidence you want to remove.
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/{evidence_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {
'dispute_id': {
'value': dispute_id,
'encode': True
},
'evidence_id': {
'value': evidence_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 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 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 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:
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}'
_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.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 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]($e/Transactions/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:
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/locations/{location_id}/transactions/{transaction_id}/void'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {
'location_id': {
'value': location_id,
'encode': True
},
'transaction_id': {
'value': transaction_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 update_wage_setting(self, team_member_id, body):
"""Does a PUT request to /v2/team-members/{team_member_id}/wage-setting.
Creates or updates a `WageSetting` object. The object is created if a
`WageSetting` with the specified `team_member_id` does not exist.
Otherwise,
it fully replaces the `WageSetting` object for the team member.
The `WageSetting` will be returned upon successful update.
Learn about [Troubleshooting the Teams
API](https://developer.squareup.com/docs/docs/team/troubleshooting#upda
tewagesetting).
Args:
team_member_id (string): The ID of the team member to update the
`WageSetting` object for.
body (UpdateWageSettingRequest): An object containing the fields
to POST for the request. See the corresponding object
definition for field details.
Returns:
UpdateWageSettingResponse: 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}/wage-setting'
_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 retrieve_cash_drawer_shift(self,
location_id,
shift_id):
"""Does a GET request to /v2/cash-drawers/shifts/{shift_id}.
Provides the summary details for a single cash drawer shift. See
[ListCashDrawerShiftEvents]($e/CashDrawers/ListCashDrawerShiftEvents)
for a list of cash drawer shift events.
Args:
location_id (string): The ID of the location to retrieve cash
drawer shifts from.
shift_id (string): The shift 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 = '/v2/cash-drawers/shifts/{shift_id}'
_url_path = APIHelper.append_url_with_template_parameters(_url_path, {
'shift_id': {'value': shift_id, 'encode': True}
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {
'location_id': location_id
}
_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 update_invoice(self,
invoice_id,
body):
"""Does a PUT request to /v2/invoices/{invoice_id}.
Updates an invoice by modifying fields, clearing fields, or both. For
most updates, you can use a sparse
`Invoice` object to add fields or change values, and use the
`fields_to_clear` field to specify fields to clear.
However, some restrictions apply. For example, you cannot change the
`order_id` or `location_id` field, and you
must provide the complete `custom_fields` list to update a custom
field. Published invoices have additional restrictions.
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:
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}'
_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.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 retrieve_bank_account(self, location_id, bank_account_id):
"""Does a GET request to /v1/{location_id}/bank-accounts/{bank_account_id}.
Provides non-confidential details for a merchant's associated bank
account. 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.
Args:
location_id (string): The ID of the bank account's associated
location.
bank_account_id (string): The bank account's Square-issued ID. You
obtain this value from Settlement objects returned.
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}/bank-accounts/{bank_account_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {
'location_id': {
'value': location_id,
'encode': True
},
'bank_account_id': {
'value': bank_account_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_payment(self, location_id, payment_id):
"""Does a GET request to /v1/{location_id}/payments/{payment_id}.
Provides comprehensive information for a single payment.
Args:
location_id (string): The ID of the payment's associated
location.
payment_id (string): The Square-issued payment ID. payment_id
comes from Payment objects returned by the List Payments
endpoint, Settlement objects returned by the List Settlements
endpoint, or Refund objects returned by the List Refunds
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}/payments/{payment_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {
'location_id': {
'value': location_id,
'encode': True
},
'payment_id': {
'value': payment_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 delete_invoice(self, invoice_id, version=None):
"""Does a DELETE request to /v2/invoices/{invoice_id}.
Deletes the specified invoice. When an invoice is deleted, the
associated Order status changes to CANCELED. You can only delete a
draft
invoice (you cannot delete an invoice scheduled for publication, or a
published invoice).
Args:
invoice_id (string): The ID of the invoice to delete.
version (int, optional): The version of the
[invoice](#type-invoice) to delete. If you do not know the
version, you can call
[GetInvoice](#endpoint-Invoices-GetInvoice) or
[ListInvoices](#endpoint-Invoices-ListInvoices).
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}'
_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_parameters = {'version': version}
_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.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 create_checkout(self, location_id, body):
"""Does a POST request to /v2/locations/{location_id}/checkouts.
Links a `checkoutId` to a `checkout_page_url` that customers will
be directed to in order to provide their payment information using a
payment processing workflow hosted on connect.squareup.com.
Args:
location_id (string): The ID of the business location to associate
the checkout with.
body (CreateCheckoutRequest): 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/locations/{location_id}/checkouts'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'location_id': {
'value': location_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 retrieve_dispute_evidence(self, dispute_id, evidence_id):
"""Does a GET request to /v2/disputes/{dispute_id}/evidence/{evidence_id}.
Returns the specific evidence metadata associated with a specific
dispute.
You must maintain a copy of the evidence you upload if you want to
reference it later. You cannot
download the evidence after you upload it.
Args:
dispute_id (string): The ID of the dispute that you want to
retrieve evidence from.
evidence_id (string): The ID of the evidence to retrieve.
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/{evidence_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {
'dispute_id': {
'value': dispute_id,
'encode': True
},
'evidence_id': {
'value': evidence_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 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 catalog object 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 catalog item will delete its catalog item
variations).
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/catalog/object/{object_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'object_id': {
'value': object_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 update_shift(self, id, body):
"""Does a PUT request to /v2/labor/shifts/{id}.
Updates an existing `Shift`.
When adding a `Break` to a `Shift`, any earlier `Breaks` in the
`Shift` have
the `end_at` property set to a valid RFC-3339 datetime string.
When closing a `Shift`, all `Break` instances in the shift must be
complete with `end_at`
set on each `Break`.
Args:
id (string): ID of the object being updated.
body (UpdateShiftRequest): An object containing the fields to POST
for the request. See the corresponding object definition for
field details.
Returns:
UpdateShiftResponse: 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/shifts/{id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'id': 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_payment(self, payment_id, body):
"""Does a PUT request to /v2/payments/{payment_id}.
Updates a payment with the APPROVED status.
You can update the `amount_money` and `tip_money` using this
endpoint.
Args:
payment_id (string): The ID of the payment to update.
body (UpdatePaymentRequest): 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/{payment_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'payment_id': {
'value': payment_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 update_timecard(self, timecard_id, body):
"""Does a PUT request to /v1/me/timecards/{timecard_id}.
Modifies the details of a timecard with an `API_EDIT` event for
the timecard. Updating an active timecard with a `clockout_time`
clocks the employee out.
Args:
timecard_id (string): TThe ID of the timecard to modify.
body (V1Timecard): 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 = '/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 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_order(self, location_id, order_id, body):
"""Does a PUT request to /v1/{location_id}/orders/{order_id}.
Updates the details of an online store order. Every update you perform
on an order corresponds to one of three actions:
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
body (V1UpdateOrderRequest): An object containing the fields to
POST for the request. See the corresponding object definition
for field details.
Returns:
V1Order: 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}/orders/{order_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {
'location_id': location_id,
'order_id': order_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 remove_group_from_customer(self, customer_id, group_id):
"""Does a DELETE request to /v2/customers/{customer_id}/groups/{group_id}.
Removes a group membership from 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 remove from the
group.
group_id (string): The ID of the customer group to remove the
customer from.
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.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 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 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.
<aside>
Only approved accounts can manage their employees with Square.
Unapproved accounts cannot use employee management features with the
API.
</aside>
Args:
timecard_id (string): The ID of the timecard to delete.
Returns:
object: 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/timecards/{timecard_id}'
_url_path = APIHelper.append_url_with_template_parameters(_url_path, {
'timecard_id': timecard_id
})
_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 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](https://developer.squareup.com/docs/reference/squ
are/loyalty-api/create-loyalty-reward)),
it updates the order by removing the reward and related
discounts.
You cannot delete a reward that has reached the terminal state
(REDEEMED).
For more information, see
[Loyalty
rewards](https://developer.squareup.com/docs/docs/loyalty-api/overview/
#loyalty-overview-loyalty-rewards).
Args:
reward_id (string): The ID of the [loyalty
reward](#type-LoyaltyReward) to delete.
Returns:
DeleteLoyaltyRewardResponse: 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/loyalty/rewards/{reward_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'reward_id': reward_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 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
