def list_refunds(self,
location_id,
order=None,
begin_time=None,
end_time=None,
limit=None,
batch_token=None):
"""Does a GET request to /v1/{location_id}/refunds.
Provides the details for all refunds initiated by a merchant or any of
the merchant's mobile staff during a date range. Date ranges cannot
exceed one year in length.
Args:
location_id (string): The ID of the location to list refunds for.
order (SortOrder, optional): The order in which payments are
listed in the response.
begin_time (string, optional): The beginning of the requested
reporting period, in ISO 8601 format. If this value is before
January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns
an error. Default value: The current time minus one year.
end_time (string, optional): The end of the requested reporting
period, in ISO 8601 format. If this value is more than one
year greater than begin_time, this endpoint returns an error.
Default value: The current time.
limit (int, optional): The approximate number of refunds to return
in a single response. Default: 100. Max: 200. Response may
contain more results than the prescribed limit when refunds
are made simultaneously to multiple tenders in a payment or
when refunds are generated in an exchange to account for the
value of returned goods.
batch_token (string, optional): A pagination cursor to retrieve
the next set of results for your original query to the
endpoint.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v1/{location_id}/refunds'
_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_parameters = {
'order': order,
'begin_time': begin_time,
'end_time': end_time,
'limit': limit,
'batch_token': batch_token
}
_query_builder = APIHelper.append_url_with_query_parameters(
_query_builder, _query_parameters)
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.get(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def create_timecard(self, body):
"""Does a POST request to /v1/me/timecards.
Creates a timecard for an employee and clocks them in with an
`API_CREATE` event and a `clockin_time` set to the current time
unless
the request provides a different value.
To import timecards from another
system (rather than clocking someone in). Specify the `clockin_time`
and* `clockout_time` in the request.
Timecards correspond to exactly one shift for a given employee,
bounded
by the `clockin_time` and `clockout_time` fields. An employee is
considered clocked in if they have a timecard that doesn't have a
`clockout_time` set. An employee that is currently clocked in cannot
be clocked in a second time.
Args:
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'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(
_query_url,
headers=_headers,
parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def list_team_member_booking_profiles(self,
bookable_only=False,
limit=None,
cursor=None,
location_id=None):
"""Does a GET request to /v2/bookings/team-member-booking-profiles.
Lists booking profiles for team members.
Args:
bookable_only (bool, optional): Indicates whether to include only
bookable team members in the returned result (`true`) or not
(`false`).
limit (int, optional): The maximum number of results to return.
cursor (string, optional): The cursor for paginating through the
results.
location_id (string, optional): Indicates whether to include only
team members enabled at the given location in the returned
result.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/bookings/team-member-booking-profiles'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {
'bookable_only': bookable_only,
'limit': limit,
'cursor': cursor,
'location_id': location_id
}
_query_builder = APIHelper.append_url_with_query_parameters(
_query_builder, _query_parameters)
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.get(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def search_subscriptions(self, body):
"""Does a POST request to /v2/subscriptions/search.
Searches for subscriptions.
Results are ordered chronologically by subscription creation date. If
the request specifies more than one location ID,
the endpoint orders the result
by location ID, and then by creation date within each location. If no
locations are given
in the query, all locations are searched.
You can also optionally specify `customer_ids` to search by customer.
If left unset, all customers
associated with the specified locations are returned.
If the request specifies customer IDs, the endpoint orders results
first by location, within location by customer ID, and within
customer by subscription creation date.
For more information, see
[Retrieve
subscriptions](https://developer.squareup.com/docs/docs/subscriptions-a
pi/overview#retrieve-subscriptions).
Args:
body (SearchSubscriptionsRequest): An object containing the fields
to POST for the request. See the corresponding object
definition for field details.
Returns:
SearchSubscriptionsResponse: 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/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_employee_role(self, body):
"""Does a POST request to /v1/me/roles.
Creates an employee role you can then assign to employees.
Square accounts can include any number of roles that can be assigned
to
employees. These roles define the actions and permissions granted to
an
employee with that role. For example, an employee with a "Shift
Manager"
role might be able to issue refunds in Square Point of Sale, whereas
an
employee with a "Clerk" role might not.
Roles are assigned with the
[V1UpdateEmployee](#endpoint-v1updateemployee)
endpoint. An employee can have only one role at a time.
If an employee has no role, they have none of the permissions
associated
with roles. All employees can accept payments with Square Point of
Sale.
Args:
body (V1EmployeeRole): An EmployeeRole object with a name and
permissions, and an optional owner flag.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v1/me/roles'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(
_query_url,
headers=_headers,
parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def list_invoices(self,
location_id,
cursor=None,
limit=None):
"""Does a GET request to /v2/invoices.
Returns a list of invoices for a given location. The response
is paginated. If truncated, the response includes a `cursor` that you
use in a subsequent request to fetch the next set of invoices.
Args:
location_id (string): The ID of the location for which to list
invoices.
cursor (string, optional): A pagination cursor returned by a
previous call to this endpoint. Provide this cursor to
retrieve the next set of results for your original query. For
more information, see
[Pagination](https://developer.squareup.com/docs/working-with-a
pis/pagination).
limit (int, optional): The maximum number of invoices to return
(200 is the maximum `limit`). If not provided, the server
uses a default limit of 100 invoices.
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'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {
'location_id': location_id,
'cursor': cursor,
'limit': limit
}
_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 publish_invoice(self,
invoice_id,
body):
"""Does a POST request to /v2/invoices/{invoice_id}/publish.
Publishes the specified draft invoice.
After an invoice is published, Square
follows up based on the invoice configuration. For example, Square
sends the invoice to the customer's email address, charges the
customer's card on file, or does
nothing. Square also makes the invoice available on a Square-hosted
invoice page.
The invoice `status` also changes from `DRAFT` to a status
based on the invoice configuration. For example, the status changes to
`UNPAID` if
Square emails the invoice or `PARTIALLY_PAID` if Square charge a card
on file for a portion of the
invoice amount).
Args:
invoice_id (string): The id of the invoice to publish.
body (PublishInvoiceRequest): 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}/publish'
_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 list_payment_refunds(self,
begin_time=None,
end_time=None,
sort_order=None,
cursor=None,
location_id=None,
status=None,
source_type=None):
"""Does a GET request to /v2/refunds.
Retrieves a list of refunds for the account making the request.
Max results per page: 100
Args:
begin_time (string, optional): Timestamp for the beginning of the
requested reporting period, in RFC 3339 format. Default: The
current time minus one year.
end_time (string, optional): Timestamp for the end of the
requested reporting period, in RFC 3339 format. Default: The
current time.
sort_order (string, optional): The order in which results are
listed. - `ASC` - oldest to newest - `DESC` - newest to oldest
(default).
cursor (string, optional): A pagination cursor returned by a
previous call to this endpoint. Provide this to retrieve the
next set of results for the original query. See
[Pagination](https://developer.squareup.com/docs/basics/api101/
pagination) for more information.
location_id (string, optional): ID of location associated with
payment.
status (string, optional): If provided, only refunds with the
given status are returned. For a list of refund status
values, see [PaymentRefund](#type-paymentrefund). Default: If
omitted refunds are returned regardless of status.
source_type (string, optional): If provided, only refunds with the
given source type are returned. - `CARD` - List refunds only
for payments where card was specified as payment source.
Default: If omitted refunds are returned regardless of source
type.
Returns:
ListPaymentRefundsResponse: 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/refunds'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {
'begin_time': begin_time,
'end_time': end_time,
'sort_order': sort_order,
'cursor': cursor,
'location_id': location_id,
'status': status,
'source_type': source_type
}
_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 batch_upsert_catalog_objects(self, body):
"""Does a POST request to /v2/catalog/batch-upsert.
Creates or updates up to 10,000 target objects based on the provided
list of objects. The target objects are grouped into batches and each
batch is
inserted/updated in an all-or-nothing manner. If an object within a
batch is
malformed in some way, or violates a database constraint, the entire
batch
containing that item will be disregarded. However, other batches in
the same
request may still succeed. Each batch may contain up to 1,000 objects,
and
batches will be processed in order as long as the total object count
for the
request (items, variations, modifier lists, discounts, and taxes) is
no more
than 10,000.
Args:
body (BatchUpsertCatalogObjectsRequest): An object containing the
fields to POST for the request. See the corresponding object
definition for field details.
Returns:
BatchUpsertCatalogObjectsResponse: 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/batch-upsert'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(
_query_url,
headers=_headers,
parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def list_customers(self,
cursor=None,
sort_field=None,
sort_order=None):
"""Does a GET request to /v2/customers.
Lists a business's customers.
Args:
cursor (string, optional): A pagination cursor returned by a
previous call to this endpoint. Provide this to retrieve the
next set of results for your original query. See the
[Pagination
guide](https://developer.squareup.com/docs/working-with-apis/pa
gination) for more information.
sort_field (CustomerSortField, optional): Indicates how Customers
should be sorted. Default: `DEFAULT`.
sort_order (SortOrder, optional): Indicates whether Customers
should be sorted in ascending (`ASC`) or descending (`DESC`)
order. Default: `ASC`.
Returns:
ListCustomersResponse: 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_parameters = {
'cursor': cursor,
'sort_field': sort_field,
'sort_order': sort_order
}
_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_customer(self,
customer_id,
body):
"""Does a PUT request to /v2/customers/{customer_id}.
Updates the details of an existing customer. When two profiles are
merged
into a single profile, that profile is assigned a new `customer_id`.
You must use
the new `customer_id` to update merged profiles.
You cannot edit a customer's cards on file with this endpoint. To make
changes
to a card on file, you must delete the existing card on file with the
[DeleteCustomerCard](#endpoint-deletecustomercard) endpoint, then
create a new one with the
[CreateCustomerCard](#endpoint-createcustomercard) endpoint.
Args:
customer_id (string): The ID of the customer to update.
body (UpdateCustomerRequest): An object containing the fields to
POST for the request. See the corresponding object definition
for field details.
Returns:
UpdateCustomerResponse: 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}'
_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.put(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def retrieve_settlement(self, location_id, settlement_id):
"""Does a GET request to /v1/{location_id}/settlements/{settlement_id}.
Provides comprehensive information for a single settlement.
The returned `Settlement` objects include an `entries` field that
lists
the transactions that contribute to the settlement total. Most
settlement entries correspond to a payment payout, but settlement
entries are also generated for less common events, like refunds,
manual
adjustments, or chargeback holds.
Square initiates its regular deposits as indicated in the
[Deposit Options with
Square](https://squareup.com/help/us/en/article/3807)
help article. Details for a regular deposit are usually not available
from Connect API endpoints before 10 p.m. PST the same day.
Square does not know when an initiated settlement **completes**, only
whether it has failed. A completed settlement is typically reflected
in
a bank account within 3 business days, but in exceptional cases it
may
take longer.
Args:
location_id (string): The ID of the settlements's associated
location.
settlement_id (string): The settlement's Square-issued ID. You
obtain this value from Settlement objects returned by the List
Settlements 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}/settlements/{settlement_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {
'location_id': {
'value': location_id,
'encode': True
},
'settlement_id': {
'value': settlement_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_settlements(self,
location_id,
order=None,
begin_time=None,
end_time=None,
limit=None,
status=None,
batch_token=None):
"""Does a GET request to /v1/{location_id}/settlements.
Provides summary information for all deposits and withdrawals
initiated by Square to a linked bank account during a date range.
Date
ranges cannot exceed one year in length.
*Note**: the ListSettlements endpoint does not provide entry
information.
Args:
location_id (string): The ID of the location to list settlements
for. If you specify me, this endpoint returns settlements
aggregated from all of the business's locations.
order (SortOrder, optional): The order in which settlements are
listed in the response.
begin_time (string, optional): The beginning of the requested
reporting period, in ISO 8601 format. If this value is before
January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns
an error. Default value: The current time minus one year.
end_time (string, optional): The end of the requested reporting
period, in ISO 8601 format. If this value is more than one
year greater than begin_time, this endpoint returns an error.
Default value: The current time.
limit (int, optional): The maximum number of settlements to return
in a single response. This value cannot exceed 200.
status (V1ListSettlementsRequestStatus, optional): Provide this
parameter to retrieve only settlements with a particular
status (SENT or FAILED).
batch_token (string, optional): A pagination cursor to retrieve
the next set of results for your original query to the
endpoint.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v1/{location_id}/settlements'
_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_parameters = {
'order': order,
'begin_time': begin_time,
'end_time': end_time,
'limit': limit,
'status': status,
'batch_token': batch_token
}
_query_builder = APIHelper.append_url_with_query_parameters(
_query_builder, _query_parameters)
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.get(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def create_refund(self, location_id, body):
"""Does a POST request to /v1/{location_id}/refunds.
Issues a refund for a previously processed payment. You must issue
a refund within 60 days of the associated payment.
You cannot issue a partial refund for a split tender payment. You
must
instead issue a full or partial refund for a particular tender, by
providing the applicable tender id to the V1CreateRefund endpoint.
Issuing a full refund for a split tender payment refunds all tenders
associated with the payment.
Issuing a refund for a card payment is not reversible. For
development
purposes, you can create fake cash payments in Square Point of Sale
and
refund them.
Args:
location_id (string): The ID of the original payment's associated
location.
body (V1CreateRefundRequest): 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/{location_id}/refunds'
_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 calculate_loyalty_points(self, program_id, body):
"""Does a POST request to /v2/loyalty/programs/{program_id}/calculate.
Calculates the points a purchase earns.
- If you are using the Orders API to manage orders, you provide
`order_id` in the request. The
endpoint calculates the points by reading the order.
- If you are not using the Orders API to manage orders, you provide
the purchase amount in
the request for the endpoint to calculate the points.
An application might call this endpoint to show the points that a
buyer can earn with the
specific purchase.
Args:
program_id (string): The [loyalty program]($m/LoyaltyProgram) ID,
which defines the rules for accruing points.
body (CalculateLoyaltyPointsRequest): 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/programs/{program_id}/calculate'
_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',
'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_delete_catalog_objects(self, body):
"""Does a POST request to /v2/catalog/batch-delete.
Deletes a set of [CatalogItem](#type-catalogitem)s based on the
provided list of target IDs and returns a 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
will
also delete all of its
[CatalogItemVariation](#type-catalogitemvariation)
children.
`BatchDeleteCatalogObjects` succeeds even if only a portion of the
targeted
IDs can be deleted. The response will only include IDs that were
actually deleted.
Args:
body (BatchDeleteCatalogObjectsRequest): An object containing the
fields to POST for the request. See the corresponding object
definition for field details.
Returns:
BatchDeleteCatalogObjectsResponse: 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/batch-delete'
_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 redeem_loyalty_reward(self, reward_id, body):
"""Does a POST request to /v2/loyalty/rewards/{reward_id}/redeem.
Redeems a loyalty reward.
The endpoint sets the reward to the `REDEEMED` terminal state.
If you are using your own order processing system (not using the
Orders API), you call this endpoint after the buyer paid for the
purchase.
After the reward reaches the terminal state, it cannot be deleted.
In other words, points used for the reward cannot be returned
to the account.
Args:
reward_id (string): The ID of the [loyalty
reward]($m/LoyaltyReward) to redeem.
body (RedeemLoyaltyRewardRequest): An object containing the fields
to POST for the request. See the corresponding object
definition for field details.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/loyalty/rewards/{reward_id}/redeem'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'reward_id': {
'value': reward_id,
'encode': True
}})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(
_query_url,
headers=_headers,
parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def create_catalog_image(self, request=None, image_file=None):
"""Does a POST request to /v2/catalog/images.
Uploads an image file to be represented by an
[CatalogImage](#type-catalogimage) object linked to an existing
[CatalogObject](#type-catalogobject) instance. A call to this endpoint
can upload an image, link an image to
a catalog object, or do both.
This `CreateCatalogImage` endpoint accepts HTTP multipart/form-data
requests with a JSON part and an image file part in
JPEG, PJPEG, PNG, or GIF format. The maximum file size is 15MB.
Additional information and an example cURL request can be found in the
[Create a Catalog Image
recipe](https://developer.squareup.com/docs/more-apis/catalog/cookbook/
create-catalog-images).
Args:
request (CreateCatalogImageRequest, optional): TODO: type
description here.
image_file (typing.BinaryIO, optional): TODO: type description
here.
Returns:
CreateCatalogImageResponse: 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/images'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
if isinstance(image_file, FileWrapper):
image_file_wrapper = image_file.file_stream
image_file_content_type = image_file.content_type
else:
image_file_wrapper = image_file
image_file_content_type = 'image/jpeg'
# Prepare files
_files = {
'request': (None, APIHelper.json_serialize(request),
'application/json; charset=utf-8'),
'image_file': (image_file_wrapper.name, image_file_wrapper,
image_file_content_type)
}
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.post(_query_url,
headers=_headers,
files=_files)
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 a published invoice, including one that is
scheduled for processing).
Args:
invoice_id (string): The ID of the invoice to delete.
version (int, optional): The version of the
[invoice](#type-invoice) to delete. If you do not know the
version, you can call
[GetInvoice](#endpoint-Invoices-GetInvoice) or
[ListInvoices](#endpoint-Invoices-ListInvoices).
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/invoices/{invoice_id}'
_url_path = APIHelper.append_url_with_template_parameters(_url_path, {
'invoice_id': {'value': invoice_id, 'encode': True}
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {
'version': version
}
_query_builder = APIHelper.append_url_with_query_parameters(
_query_builder,
_query_parameters
)
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json'
}
# Prepare and execute request
_request = self.config.http_client.delete(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def list_catalog(self, cursor=None, types=None):
"""Does a GET request to /v2/catalog/list.
Returns a list of [CatalogObject](#type-catalogobject)s that includes
all objects of a set of desired types (for example, all
[CatalogItem](#type-catalogitem)
and [CatalogTax](#type-catalogtax) objects) in the catalog. The
`types` parameter
is specified as a comma-separated list of valid
[CatalogObject](#type-catalogobject) types:
`ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, `CATEGORY`,
`DISCOUNT`, `TAX`, `IMAGE`.
__Important:__ ListCatalog does not return deleted catalog items. To
retrieve
deleted catalog items, use SearchCatalogObjects and set
`include_deleted_objects`
to `true`.
Args:
cursor (string, optional): The pagination cursor returned in the
previous response. Leave unset for an initial request. See
[Pagination](https://developer.squareup.com/docs/basics/api101/
pagination) for more information.
types (string, optional): An optional case-insensitive,
comma-separated list of object types to retrieve, for example
`ITEM,ITEM_VARIATION,CATEGORY,IMAGE`. The legal values are
taken from the CatalogObjectType enum: `ITEM`,
`ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`, `MODIFIER`,
`MODIFIER_LIST`, or `IMAGE`.
Returns:
ListCatalogResponse: 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/list'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {'cursor': cursor, 'types': types}
_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 list_subscription_events(self,
subscription_id,
cursor=None,
limit=None):
"""Does a GET request to /v2/subscriptions/{subscription_id}/events.
Lists all events for a specific subscription.
In the current implementation, only `START_SUBSCRIPTION` and
`STOP_SUBSCRIPTION` (when the subscription was canceled) events are
returned.
Args:
subscription_id (string): The ID of the subscription to retrieve
the events for.
cursor (string, optional): A pagination cursor returned by a
previous call to this endpoint. Provide this to retrieve the
next set of results for the original query. For more
information, see
[Pagination](https://developer.squareup.com/docs/docs/working-w
ith-apis/pagination).
limit (int, optional): The upper limit on the number of
subscription events to return in the response. Default:
`200`
Returns:
ListSubscriptionEventsResponse: 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}/events'
_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_parameters = {'cursor': cursor, 'limit': limit}
_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 retrieve_catalog_object(self,
object_id,
include_related_objects=False):
"""Does a GET request to /v2/catalog/object/{object_id}.
Returns a single [CatalogItem](#type-catalogitem) as a
[CatalogObject](#type-catalogobject) based on the provided ID. The
returned
object includes all of the relevant [CatalogItem](#type-catalogitem)
information including:
[CatalogItemVariation](#type-catalogitemvariation)
children, references to its
[CatalogModifierList](#type-catalogmodifierlist) objects, and the ids
of
any [CatalogTax](#type-catalogtax) objects that apply to it.
Args:
object_id (string): The object ID of any type of catalog objects
to be retrieved.
include_related_objects (bool, optional): If `true`, the response
will include additional objects that are related to the
requested object, as follows: If the `object` field of the
response contains a CatalogItem, its associated
CatalogCategory, CatalogTax objects, CatalogImages and
CatalogModifierLists will be returned in the `related_objects`
field of the response. If the `object` field of the response
contains a CatalogItemVariation, its parent CatalogItem will
be returned in the `related_objects` field of the response.
Default value: `false`
Returns:
RetrieveCatalogObjectResponse: 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_parameters = {
'include_related_objects': include_related_objects
}
_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 list_device_codes(self,
cursor=None,
location_id=None,
product_type=None,
status=None):
"""Does a GET request to /v2/devices/codes.
Lists all DeviceCodes associated with the merchant.
Args:
cursor (string, optional): A pagination cursor returned by a
previous call to this endpoint. Provide this to retrieve the
next set of results for your original query. See [Paginating
results](https://developer.squareup.com/docs/working-with-apis/
pagination) for more information.
location_id (string, optional): If specified, only returns
DeviceCodes of the specified location. Returns DeviceCodes of
all locations if empty.
product_type (ProductType, optional): If specified, only returns
DeviceCodes targeting the specified product type. Returns
DeviceCodes of all product types if empty.
status (DeviceCodeStatus, optional): If specified, returns
DeviceCodes with the specified statuses. Returns DeviceCodes
of status `PAIRED` and `UNPAIRED` if empty.
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/devices/codes'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {
'cursor': cursor,
'location_id': location_id,
'product_type': product_type,
'status': status
}
_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_catalog_items(self, body):
"""Does a POST request to /v2/catalog/search-catalog-items.
Searches for catalog items or item variations by matching supported
search attribute values, including
custom attribute values, against one or more of the specified query
expressions,
This (`SearchCatalogItems`) endpoint differs from the
[SearchCatalogObjects](#endpoint-Catalog-SearchCatalogObjects)
endpoint in the following aspects:
- `SearchCatalogItems` can only search for items or item variations,
whereas `SearchCatalogObjects` can search for any type of catalog
objects.
- `SearchCatalogItems` supports the custom attribute query filters to
return items or item variations that contain custom attribute values,
where `SearchCatalogObjects` does not.
- `SearchCatalogItems` does not support the `include_deleted_objects`
filter to search for deleted items or item variations, whereas
`SearchCatalogObjects` does.
- The both endpoints use different call conventions, including the
query filter formats.
Args:
body (SearchCatalogItemsRequest): An object containing the fields
to POST for the request. See the corresponding object
definition for field details.
Returns:
SearchCatalogItemsResponse: 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-catalog-items'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(
_query_url,
headers=_headers,
parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def list_timecards(self,
order=None,
employee_id=None,
begin_clockin_time=None,
end_clockin_time=None,
begin_clockout_time=None,
end_clockout_time=None,
begin_updated_at=None,
end_updated_at=None,
deleted=False,
limit=None,
batch_token=None):
"""Does a GET request to /v1/me/timecards.
Provides summary information for all of a business's employee
timecards.
Args:
order (SortOrder, optional): The order in which timecards are
listed in the response, based on their created_at field.
employee_id (string, optional): If provided, the endpoint returns
only timecards for the employee with the specified ID.
begin_clockin_time (string, optional): If filtering results by
their clockin_time field, the beginning of the requested
reporting period, in ISO 8601 format.
end_clockin_time (string, optional): If filtering results by their
clockin_time field, the end of the requested reporting period,
in ISO 8601 format.
begin_clockout_time (string, optional): If filtering results by
their clockout_time field, the beginning of the requested
reporting period, in ISO 8601 format.
end_clockout_time (string, optional): If filtering results by
their clockout_time field, the end of the requested reporting
period, in ISO 8601 format.
begin_updated_at (string, optional): If filtering results by their
updated_at field, the beginning of the requested reporting
period, in ISO 8601 format.
end_updated_at (string, optional): If filtering results by their
updated_at field, the end of the requested reporting period,
in ISO 8601 format.
deleted (bool, optional): If true, only deleted timecards are
returned. If false, only valid timecards are returned.If you
don't provide this parameter, both valid and deleted timecards
are returned.
limit (int, optional): The maximum integer number of employee
entities to return in a single response. Default 100, maximum
200.
batch_token (string, optional): A pagination cursor to retrieve
the next set of results for your original query to the
endpoint.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v1/me/timecards'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {
'order': order,
'employee_id': employee_id,
'begin_clockin_time': begin_clockin_time,
'end_clockin_time': end_clockin_time,
'begin_clockout_time': begin_clockout_time,
'end_clockout_time': end_clockout_time,
'begin_updated_at': begin_updated_at,
'end_updated_at': end_updated_at,
'deleted': deleted,
'limit': limit,
'batch_token': batch_token
}
_query_builder = APIHelper.append_url_with_query_parameters(
_query_builder, _query_parameters)
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.get(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def list_bank_accounts(self, cursor=None, limit=None, location_id=None):
"""Does a GET request to /v2/bank-accounts.
Returns a list of [BankAccount]($m/BankAccount) objects linked to a
Square account.
Args:
cursor (string, optional): The pagination cursor returned by a
previous call to this endpoint. Use it in the next
`ListBankAccounts` request to retrieve the next set of
results. See the
[Pagination](https://developer.squareup.com/docs/working-with-a
pis/pagination) guide for more information.
limit (int, optional): Upper limit on the number of bank accounts
to return in the response. Currently, 1000 is the largest
supported limit. You can specify a limit of up to 1000 bank
accounts. This is also the default limit.
location_id (string, optional): Location ID. You can specify this
optional filter to retrieve only the linked bank accounts
belonging to a specific location.
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'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {
'cursor': cursor,
'limit': limit,
'location_id': location_id
}
_query_builder = APIHelper.append_url_with_query_parameters(
_query_builder, _query_parameters)
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.get(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def list_cash_drawer_shifts(self,
location_id,
order=None,
begin_time=None,
end_time=None):
"""Does a GET request to /v1/{location_id}/cash-drawer-shifts.
Provides the details for all of a location's cash drawer shifts during
a date range. The date range you specify cannot exceed 90 days.
Args:
location_id (string): The ID of the location to list cash drawer
shifts for.
order (SortOrder, optional): The order in which cash drawer shifts
are listed in the response, based on their created_at field.
Default value: ASC
begin_time (string, optional): The beginning of the requested
reporting period, in ISO 8601 format. Default value: The
current time minus 90 days.
end_time (string, optional): The beginning of the requested
reporting period, in ISO 8601 format. Default value: The
current time.
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'
_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_parameters = {
'order': order,
'begin_time': begin_time,
'end_time': end_time
}
_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 accumulate_loyalty_points(self, account_id, body):
"""Does a POST request to /v2/loyalty/accounts/{account_id}/accumulate.
Adds points to a loyalty account.
- If you are using the Orders API to manage orders, you only provide
the `order_id`.
The endpoint reads the order to compute points to add to the buyer's
account.
- If you are not using the Orders API to manage orders,
you first perform a client-side computation to compute the points.
For spend-based and visit-based programs, you can call
[CalculateLoyaltyPoints]($e/Loyalty/CalculateLoyaltyPoints) to compute
the points. For more information,
see [Loyalty Program
Overview](https://developer.squareup.com/docs/loyalty/overview).
You then provide the points in a request to this endpoint.
Args:
account_id (string): The [loyalty account]($m/LoyaltyAccount) ID
to which to add the points.
body (AccumulateLoyaltyPointsRequest): 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}/accumulate'
_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 update_order(self, location_id, order_id, body):
"""Does a PUT request to /v2/locations/{location_id}/orders/{order_id}.
Updates an open [Order](#type-order) by adding, replacing, or
deleting
fields. Orders with a `COMPLETED` or `CANCELED` state cannot be
updated.
An UpdateOrder request requires the following:
- The `order_id` in the endpoint path, identifying the order to
update.
- The latest `version` of the order to update.
- The [sparse
order](https://developer.squareup.com/docs/orders-api/manage-orders#spa
rse-order-objects)
containing only the fields to update and the version the update is
being applied to.
- If deleting fields, the [dot notation
paths](https://developer.squareup.com/docs/orders-api/manage-orders#on-
dot-notation)
identifying fields to clear.
To pay for an order, please refer to the [Pay for
Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders)
guide.
To learn more about the Orders API, see the
[Orders API
Overview](https://developer.squareup.com/docs/orders-api/what-it-does).
Args:
location_id (string): The ID of the order's associated location.
order_id (string): The ID of the order to update.
body (UpdateOrderRequest): An object containing the fields to POST
for the request. See the corresponding object definition for
field details.
Returns:
UpdateOrderResponse: 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}/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 list_payments(self,
location_id,
order=None,
begin_time=None,
end_time=None,
limit=None,
batch_token=None,
include_partial=False):
"""Does a GET request to /v1/{location_id}/payments.
Provides summary information for all payments taken for a given
Square account during a date range. Date ranges cannot exceed 1 year
in
length. See Date ranges for details of inclusive and exclusive dates.
*Note**: Details for payments processed with Square Point of Sale
while
in offline mode may not be transmitted to Square for up to 72 hours.
Offline payments have a `created_at` value that reflects the time the
payment was originally processed, not the time it was subsequently
transmitted to Square. Consequently, the ListPayments endpoint might
list an offline payment chronologically between online payments that
were seen in a previous request.
Args:
location_id (string): The ID of the location to list payments for.
If you specify me, this endpoint returns payments aggregated
from all of the business's locations.
order (SortOrder, optional): The order in which payments are
listed in the response.
begin_time (string, optional): The beginning of the requested
reporting period, in ISO 8601 format. If this value is before
January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns
an error. Default value: The current time minus one year.
end_time (string, optional): The end of the requested reporting
period, in ISO 8601 format. If this value is more than one
year greater than begin_time, this endpoint returns an error.
Default value: The current time.
limit (int, optional): The maximum number of payments to return in
a single response. This value cannot exceed 200.
batch_token (string, optional): A pagination cursor to retrieve
the next set of results for your original query to the
endpoint.
include_partial (bool, optional): Indicates whether or not to
include partial payments in the response. Partial payments
will have the tenders collected so far, but the itemizations
will be empty until the payment is completed.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v1/{location_id}/payments'
_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_parameters = {
'order': order,
'begin_time': begin_time,
'end_time': end_time,
'limit': limit,
'batch_token': batch_token,
'include_partial': include_partial
}
_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
