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 batch_retrieve_inventory_counts(self, body):
"""Does a POST request to /v2/inventory/batch-retrieve-counts.
Returns current counts for the provided
[CatalogObject](#type-catalogobject)s at the requested
[Location](#type-location)s.
Results are paginated and sorted in descending order according to
their
`calculated_at` timestamp (newest first).
When `updated_after` is specified, only counts that have changed since
that
time (based on the server timestamp for the most recent change) are
returned. This allows clients to perform a "sync" operation, for
example
in response to receiving a Webhook notification.
Args:
body (BatchRetrieveInventoryCountsRequest): 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-counts'
_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.
For more information about retrieving invoices, see [Retrieve
invoices](https://developer.squareup.com/docs/docs/invoices-api/overvie
w#retrieve-invoices).
Args:
body (SearchInvoicesRequest): An object containing the fields to
POST for the request. See the corresponding object definition
for field details.
Returns:
SearchInvoicesResponse: 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/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_customers(self, body):
"""Does a POST request to /v2/customers/search.
Searches the customer profiles associated with a Square account using
a supported query filter.
Calling `SearchCustomers` without any explicit query filter returns
all
customer profiles ordered alphabetically based on `given_name` and
`family_name`.
Under normal operating conditions, newly created or updated customer
profiles become available
for the search operation in well under 30 seconds. Occasionally,
propagation of the new or updated
profiles can take closer to one minute or longer, especially during
network incidents and outages.
Args:
body (SearchCustomersRequest): 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/customers/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_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 create_payment(self, body):
"""Does a POST request to /v2/payments.
Charges a payment source (for example, a card
represented by customer's card on file or a card nonce). In addition
to the payment source, the request must include the
amount to accept for the payment.
There are several optional parameters that you can include in the
request
(for example, tip money, whether to autocomplete the payment, or a
reference ID
to correlate this payment with another system).
The `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission is
required
to enable application fees.
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 obtain_token(self, body):
"""Does a POST request to /oauth2/token.
Returns an OAuth access token.
The endpoint supports distinct methods of obtaining OAuth access
tokens.
Applications specify a method by adding the `grant_type` parameter
in the request and also provide relevant information.
For more information, see [OAuth access token
management](https://developer.squareup.com/docs/authz/oauth/how-it-work
s#oauth-access-token-management).
__Note:__ Regardless of the method application specified,
the endpoint always returns two items; an OAuth access token and
a refresh token in the response.
__OAuth tokens should only live on secure servers. Application
clients
should never interact directly with OAuth tokens__.
Args:
body (ObtainTokenRequest): An object containing the fields to POST
for the request. See the corresponding object definition for
field details.
Returns:
ObtainTokenResponse: 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 = '/oauth2/token'
_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))
_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_shifts(self, body):
"""Does a POST request to /v2/labor/shifts/search.
Returns a paginated list of `Shift` records for a business.
The list to be returned can be filtered by:
- Location IDs **and**
- employee IDs **and**
- shift status (`OPEN`, `CLOSED`) **and**
- shift start **and**
- shift end **and**
- work day details
The list can be sorted by:
- `start_at`
- `end_at`
- `created_at`
- `updated_at`
Args:
body (SearchShiftsRequest): An object containing the fields to
POST for the request. See the corresponding object definition
for field details.
Returns:
SearchShiftsResponse: 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/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 register_domain(self, body):
"""Does a POST request to /v2/apple-pay/domains.
Activates a domain for use with Web Apple Pay and Square. A
validation
will be performed on this domain by Apple to ensure is it properly set
up as
an Apple Pay enabled domain.
This endpoint provides an easy way for platform developers to bulk
activate
Web Apple Pay with Square for merchants using their platform.
To learn more about Apple Pay on Web see the Apple Pay section in the
[Square Payment Form
Walkthrough](https://developer.squareup.com/docs/payment-form/payment-f
orm-walkthrough).
Args:
body (RegisterDomainRequest): 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/apple-pay/domains'
_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_break_type(self, body):
"""Does a POST request to /v2/labor/break-types.
Creates a new `BreakType`.
A `BreakType` is a template for creating `Break` objects.
You must provide the following values in your request to this
endpoint:
- `location_id`
- `break_name`
- `expected_duration`
- `is_paid`
You can only have 3 `BreakType` instances per location. If you attempt
to add a 4th
`BreakType` for a location, an `INVALID_REQUEST_ERROR` "Exceeded limit
of 3 breaks per location."
is returned.
Args:
body (CreateBreakTypeRequest): An object containing the fields to
POST for the request. See the corresponding object definition
for field details.
Returns:
CreateBreakTypeResponse: 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/break-types'
_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_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.
For more information, see
[Loyalty
rewards](https://developer.squareup.com/docs/docs/loyalty-api/overview/
#loyalty-overview-loyalty-rewards).
Args:
body (CreateLoyaltyRewardRequest): An object containing the fields
to POST for the request. See the corresponding object
definition for field details.
Returns:
CreateLoyaltyRewardResponse: 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'
_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 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 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 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 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:
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/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_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:
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'
_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.
For more information, see
[Loyalty
events](https://developer.squareup.com/docs/docs/loyalty-api/overview/#
loyalty-events).
Args:
body (SearchLoyaltyEventsRequest): An object containing the fields
to POST for the request. See the corresponding object
definition for field details.
Returns:
SearchLoyaltyEventsResponse: 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/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 bulk_create_team_members(self, body):
"""Does a POST request to /v2/team-members/bulk-create.
Creates multiple `TeamMember` objects. The created `TeamMember`
objects will be returned on successful creates.
This process is non-transactional and will process as much of the
request as is possible. If one of the creates in
the request cannot be successfully processed, the request will NOT be
marked as failed, but the body of the response
will contain explicit error information for this particular create.
Learn about [Troubleshooting the Teams
API](https://developer.squareup.com/docs/team/troubleshooting#bulk-crea
te-team-members).
Args:
body (BulkCreateTeamMembersRequest): 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/bulk-create'
_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_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 create_team_member(self, body):
"""Does a POST request to /v2/team-members.
Creates a single `TeamMember` object. The `TeamMember` will be
returned on successful creates.
You must provide the following values in your request to this
endpoint:
- `given_name`
- `family_name`
Learn about [Troubleshooting the Teams
API](https://developer.squareup.com/docs/team/troubleshooting#createtea
mmember).
Args:
body (CreateTeamMemberRequest): 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'
_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_rewards(self, body):
"""Does a POST request to /v2/loyalty/rewards/search.
Searches for loyalty rewards in a loyalty account.
In the current implementation, the endpoint supports search by the
reward `status`.
If you know a reward ID, use the
[RetrieveLoyaltyReward](https://developer.squareup.com/docs/reference/s
quare/loyalty-api/retrieve-loyalty-reward) endpoint.
For more information about loyalty rewards, see
[Loyalty
Rewards](https://developer.squareup.com/docs/docs/loyalty-api/overview/
#loyalty-rewards).
Args:
body (SearchLoyaltyRewardsRequest): An object containing the
fields to POST for the request. See the corresponding object
definition for field details.
Returns:
SearchLoyaltyRewardsResponse: 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/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 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_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 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:
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/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 batch_retrieve_catalog_objects(self, body):
"""Does a POST request to /v2/catalog/batch-retrieve.
Returns a set of objects based on the provided ID.
Each [CatalogItem](#type-catalogitem) returned in the set includes all
of its
child information including: all of its
[CatalogItemVariation](#type-catalogitemvariation) objects, references
to
its [CatalogModifierList](#type-catalogmodifierlist) objects, and the
ids of
any [CatalogTax](#type-catalogtax) objects that apply to it.
Args:
body (BatchRetrieveCatalogObjectsRequest): 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/catalog/batch-retrieve'
_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_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 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 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
