def search_catalog_objects(self, body):
"""Does a POST request to /v2/catalog/search.
Queries the targeted catalog using a variety of query types:
[CatalogQuerySortedAttribute](#type-catalogquerysortedattribute),
[CatalogQueryExact](#type-catalogqueryexact),
[CatalogQueryRange](#type-catalogqueryrange),
[CatalogQueryText](#type-catalogquerytext),
[CatalogQueryItemsForTax](#type-catalogqueryitemsfortax), and
[CatalogQueryItemsForModifierList](#type-catalogqueryitemsformodifierli
st).
Args:
body (SearchCatalogObjectsRequest): An object containing the
fields to POST for the request. See the corresponding object
definition for field details.
Returns:
SearchCatalogObjectsResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/catalog/search'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(
_query_url,
headers=_headers,
parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def create_loyalty_reward(self,
body):
"""Does a POST request to /v2/loyalty/rewards.
Creates a loyalty reward. In the process, the endpoint does
following:
- Uses the `reward_tier_id` in the request to determine the number of
points
to lock for this reward.
- If the request includes `order_id`, it adds the reward and related
discount to the order.
After a reward is created, the points are locked and
not available for the buyer to redeem another reward.
Args:
body (CreateLoyaltyRewardRequest): An object containing the fields
to POST for the request. See the corresponding object
definition for field details.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/loyalty/rewards'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def create_customer(self,
body):
"""Does a POST request to /v2/customers.
Creates a new customer for a business, which can have associated cards
on file.
You must provide __at least one__ of the following values in your
request to this
endpoint:
- `given_name`
- `family_name`
- `company_name`
- `email_address`
- `phone_number`
Args:
body (CreateCustomerRequest): An object containing the fields to
POST for the request. See the corresponding object definition
for field details.
Returns:
CreateCustomerResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/customers'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def retrieve_order(self, location_id, order_id):
"""Does a GET request to /v1/{location_id}/orders/{order_id}.
Provides comprehensive information for a single online store order,
including the order's history.
Args:
location_id (string): The ID of the order's associated location.
order_id (string): The order's Square-issued ID. You obtain this
value from Order objects returned by the List Orders endpoint
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v1/{location_id}/orders/{order_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {
'location_id': {
'value': location_id,
'encode': True
},
'order_id': {
'value': order_id,
'encode': True
}
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.get(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def update_subscription(self,
subscription_id,
body):
"""Does a PUT request to /v2/subscriptions/{subscription_id}.
Updates a subscription. You can set, modify, and clear the
`subscription` field values. For more information and examples, see
[Update
subscriptions](https://developer.squareup.com/docs/docs/subscriptions-a
pi/overview#update-subscriptions).
Args:
subscription_id (string): The ID for the subscription to update.
body (UpdateSubscriptionRequest): An object containing the fields
to POST for the request. See the corresponding object
definition for field details.
Returns:
UpdateSubscriptionResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/subscriptions/{subscription_id}'
_url_path = APIHelper.append_url_with_template_parameters(_url_path, {
'subscription_id': subscription_id
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.put(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def batch_retrieve_inventory_changes(self, body):
"""Does a POST request to /v2/inventory/batch-retrieve-changes.
Returns historical physical counts and adjustments based on the
provided filter criteria.
Results are paginated and sorted in ascending order according their
`occurred_at` timestamp (oldest first).
BatchRetrieveInventoryChanges is a catch-all query endpoint for
queries
that cannot be handled by other, simpler endpoints.
Args:
body (BatchRetrieveInventoryChangesRequest): An object containing
the fields to POST for the request. See the corresponding
object definition for field details.
Returns:
BatchRetrieveInventoryChangesResponse: 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/batch-retrieve-changes'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(
_query_url,
headers=_headers,
parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def 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.
Employee entities cannot be deleted. To disable employee profiles,
set the employee's status to <code>INACTIVE</code>
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 update_team_member(self, team_member_id, body):
"""Does a PUT request to /v2/team-members/{team_member_id}.
Updates a single `TeamMember` object. The `TeamMember` will be
returned on successful updates.
Learn about [Troubleshooting the Teams
API](https://developer.squareup.com/docs/docs/team/troubleshooting#upda
teteammember).
Args:
team_member_id (string): The ID of the team member to update.
body (UpdateTeamMemberRequest): An object containing the fields to
POST for the request. See the corresponding object definition
for field details.
Returns:
UpdateTeamMemberResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/team-members/{team_member_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'team_member_id': team_member_id})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.put(
_query_url,
headers=_headers,
parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def list_workweek_configs(self,
limit=None,
cursor=None):
"""Does a GET request to /v2/labor/workweek-configs.
Returns a list of `WorkweekConfig` instances for a business.
Args:
limit (int, optional): Maximum number of Workweek Configs to
return per page.
cursor (string, optional): Pointer to the next page of Workweek
Config results to fetch.
Returns:
ListWorkweekConfigsResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/labor/workweek-configs'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {
'limit': limit,
'cursor': cursor
}
_query_builder = APIHelper.append_url_with_query_parameters(
_query_builder,
_query_parameters
)
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json'
}
# Prepare and execute request
_request = self.config.http_client.get(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def update_workweek_config(self, id, body):
"""Does a PUT request to /v2/labor/workweek-configs/{id}.
Updates a `WorkweekConfig`.
Args:
id (string): UUID for the `WorkweekConfig` object being updated.
body (UpdateWorkweekConfigRequest): 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/labor/workweek-configs/{id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'id': {
'value': 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 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:
CancelInvoiceResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/invoices/{invoice_id}/cancel'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'invoice_id': invoice_id})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(
_query_url,
headers=_headers,
parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def delete_catalog_object(self, object_id):
"""Does a DELETE request to /v2/catalog/object/{object_id}.
Deletes a single [CatalogObject](#type-catalogobject) based on the
provided ID and returns the set of successfully deleted IDs in the
response.
Deletion is a cascading event such that all children of the targeted
object
are also deleted. For example, deleting a
[CatalogItem](#type-catalogitem)
will also delete all of its
[CatalogItemVariation](#type-catalogitemvariation) children.
Args:
object_id (string): The ID of the
[CatalogObject](#type-catalogobject) to be deleted. When an
object is deleted, other objects in the graph that depend on
that object will be deleted as well (for example, deleting a
[CatalogItem](#type-catalogitem) will delete its
[CatalogItemVariation](#type-catalogitemvariation)s).
Returns:
DeleteCatalogObjectResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/catalog/object/{object_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'object_id': object_id})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.delete(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def delete_loyalty_reward(self,
reward_id):
"""Does a DELETE request to /v2/loyalty/rewards/{reward_id}.
Deletes a loyalty reward by doing the following:
- Returns the loyalty points back to the loyalty account.
- If an order ID was specified when the reward was created
(see [CreateLoyaltyReward](#endpoint-Loyalty-CreateLoyaltyReward)),
it updates the order by removing the reward and related
discounts.
You cannot delete a reward that has reached the terminal state
(REDEEMED).
Args:
reward_id (string): The ID of the [loyalty
reward](#type-LoyaltyReward) to delete.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/loyalty/rewards/{reward_id}'
_url_path = APIHelper.append_url_with_template_parameters(_url_path, {
'reward_id': {'value': reward_id, 'encode': True}
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json'
}
# Prepare and execute request
_request = self.config.http_client.delete(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def complete_payment(self,
payment_id):
"""Does a POST request to /v2/payments/{payment_id}/complete.
Completes (captures) a payment.
By default, payments are set to complete immediately after they are
created.
If you set autocomplete to false when creating a payment, you can
complete (capture)
the payment using this endpoint. For more information, see
[Delayed
Payments](https://developer.squareup.com/docs/payments-api/take-payment
s#delayed-payments).
Args:
payment_id (string): Unique ID identifying the payment to be
completed.
Returns:
CompletePaymentResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/payments/{payment_id}/complete'
_url_path = APIHelper.append_url_with_template_parameters(_url_path, {
'payment_id': payment_id
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json'
}
# Prepare and execute request
_request = self.config.http_client.post(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def refund_payment(self, body):
"""Does a POST request to /v2/refunds.
Refunds a payment. You can refund the entire payment amount or a
portion of it. You can use this endpoint to refund a card payment or
record a
refund of a cash or external payment. For more information, see
[Refund
Payment](https://developer.squareup.com/docs/payments-api/refund-paymen
ts).
Args:
body (RefundPaymentRequest): An object containing the fields to
POST for the request. See the corresponding object definition
for field details.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/refunds'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(
_query_url,
headers=_headers,
parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def 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. For more information, see
[Challenge a
Dispute](https://developer.squareup.com/docs/docs/disputes-api/process-
disputes#challenge-a-dispute).
Args:
dispute_id (string): The ID of the dispute you want to submit
evidence for.
Returns:
SubmitEvidenceResponse: 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/disputes/{dispute_id}/submit-evidence'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'dispute_id': dispute_id})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.post(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def retrieve_cash_drawer_shift(self, location_id, shift_id):
"""Does a GET request to /v1/{location_id}/cash-drawer-shifts/{shift_id}.
Provides the details for a single cash drawer shift, including all
events that occurred during the shift.
Args:
location_id (string): The ID of the location to list cash drawer
shifts for.
shift_id (string): The shift's ID.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v1/{location_id}/cash-drawer-shifts/{shift_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {
'location_id': {
'value': location_id,
'encode': True
},
'shift_id': {
'value': shift_id,
'encode': True
}
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.get(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def list_employee_wages(self, employee_id=None, limit=None, cursor=None):
"""Does a GET request to /v2/labor/employee-wages.
Returns a paginated list of `EmployeeWage` instances for a business.
Args:
employee_id (string, optional): Filter wages returned to only
those that are associated with the specified employee.
limit (int, optional): Maximum number of Employee Wages to return
per page. Can range between 1 and 200. The default is the
maximum at 200.
cursor (string, optional): Pointer to the next page of Employee
Wage results to fetch.
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/labor/employee-wages'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {
'employee_id': employee_id,
'limit': limit,
'cursor': cursor
}
_query_builder = APIHelper.append_url_with_query_parameters(
_query_builder, _query_parameters)
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.get(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def 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]($e/Loyalty/RetrieveLoyaltyReward) endpoint.
Search results are sorted by `updated_at` in descending order.
Args:
body (SearchLoyaltyRewardsRequest): 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/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 get_bank_account_by_v1_id(self, v1_bank_account_id):
"""Does a GET request to /v2/bank-accounts/by-v1-id/{v1_bank_account_id}.
Returns details of a [BankAccount](#type-bankaccount) identified by V1
bank account ID.
Args:
v1_bank_account_id (string): Connect V1 ID of the desired
`BankAccount`. For more information, see [Retrieve a bank
account by using an ID issued by V1 Bank Accounts
API](https://developer.squareup.com/docs/docs/bank-accounts-api
#retrieve-a-bank-account-by-using-an-id-issued-by-v1-bank-accou
nts-api).
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/bank-accounts/by-v1-id/{v1_bank_account_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {
'v1_bank_account_id': {
'value': v1_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 delete_timecard(self,
timecard_id):
"""Does a DELETE request to /v1/me/timecards/{timecard_id}.
Deletes a timecard. Timecards can also be deleted through the
Square Dashboard. Deleted timecards are still accessible through
Connect API endpoints, but cannot be modified. The `deleted` field of
the `Timecard` object indicates whether the timecard has been
deleted.
__Note__: By default, deleted timecards appear alongside valid
timecards in
results returned by the
[ListTimecards](#endpoint-v1employees-listtimecards)
endpoint. To filter deleted timecards, include the `deleted` query
parameter in the list request.
Only approved accounts can manage their employees with Square.
Unapproved accounts cannot use employee management features with the
API.
Args:
timecard_id (string): The ID of the timecard to delete.
Returns:
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 create_invoice(self, body):
"""Does a POST request to /v2/invoices.
Creates a draft [invoice](#type-invoice)
for an order created using the Orders API.
A draft invoice remains in your account and no action is taken.
You must publish the invoice before Square can process it (send it to
the customer's email address or charge the customer’s card on file).
For more information, see [Manage Invoices Using the Invoices
API](https://developer.squareup.com/docs/docs/invoices-api/overview).
Args:
body (CreateInvoiceRequest): An object containing the fields to
POST for the request. See the corresponding object definition
for field details.
Returns:
CreateInvoiceResponse: 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'
_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_loyalty_program(self, program_id):
"""Does a GET request to /v2/loyalty/programs/{program_id}.
Retrieves the loyalty program in a seller's account, specified by the
program ID or the keyword `main`.
Loyalty programs define how buyers can earn points and redeem points
for rewards. Square sellers can have only one loyalty program, which
is created and managed from the Seller Dashboard. For more
information, see [Loyalty Program
Overview](https://developer.squareup.com/docs/loyalty/overview).
Args:
program_id (string): The ID of the loyalty program or the keyword
`main`. Either value can be used to retrieve the single
loyalty program that belongs to the seller.
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/programs/{program_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'program_id': {
'value': program_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_customer_card(self, customer_id, card_id):
"""Does a DELETE request to /v2/customers/{customer_id}/cards/{card_id}.
Removes a card on file from a customer.
Args:
customer_id (string): The ID of the customer that the card on file
belongs to.
card_id (string): The ID of the card on file to delete.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/customers/{customer_id}/cards/{card_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {
'customer_id': {
'value': customer_id,
'encode': True
},
'card_id': {
'value': card_id,
'encode': True
}
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.delete(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def list_customer_segments(self,
cursor=None):
"""Does a GET request to /v2/customers/segments.
Retrieves the list of customer segments of a business.
Args:
cursor (string, optional): A pagination cursor returned by
previous calls to __ListCustomerSegments__. Used to retrieve
the next set of query results. See the [Pagination
guide](https://developer.squareup.com/docs/docs/working-with-ap
is/pagination) for more information.
Returns:
ListCustomerSegmentsResponse: 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/segments'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {
'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 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:
DeleteInvoiceResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/invoices/{invoice_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'invoice_id': invoice_id})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_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:
CreateCheckoutResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/locations/{location_id}/checkouts'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'location_id': location_id})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'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_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:
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',
'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 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.
Args:
body (SearchLoyaltyEventsRequest): An object containing the fields
to POST for the request. See the corresponding object
definition for field details.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/loyalty/events/search'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def delete_snippet(self, site_id):
"""Does a DELETE request to /v2/sites/{site_id}/snippet.
Removes your snippet from a Square Online site.
You can call [ListSites]($e/Sites/ListSites) to get the IDs of the
sites that belong to a seller.
__Note:__ Square Online APIs are publicly available as part of an
early access program. For more information, see [Early access program
for Square Online
APIs](https://developer.squareup.com/docs/online-api#early-access-progr
am-for-square-online-apis).
Args:
site_id (string): The ID of the site that contains the snippet.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/sites/{site_id}/snippet'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'site_id': {
'value': site_id,
'encode': True
}})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.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
