def retrieve_inventory_count(self,
catalog_object_id,
location_ids=None,
cursor=None):
"""Does a GET request to /v2/inventory/{catalog_object_id}.
Retrieves the current calculated stock count for a given
[CatalogObject](#type-catalogobject) at a given set of
[Location](#type-location)s. Responses are paginated and unsorted.
For more sophisticated queries, use a batch endpoint.
Args:
catalog_object_id (string): ID of the
[CatalogObject](#type-catalogobject) to retrieve.
location_ids (string, optional): The [Location](#type-location)
IDs to look up as a comma-separated list. An empty list
queries all locations.
cursor (string, optional): A pagination cursor returned by a
previous call to this endpoint. Provide this to retrieve the
next set of results for the original query. See the
[Pagination](https://developer.squareup.com/docs/docs/working-w
ith-apis/pagination) guide for more information.
Returns:
RetrieveInventoryCountResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/inventory/{catalog_object_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'catalog_object_id': catalog_object_id})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {'location_ids': location_ids, 'cursor': cursor}
_query_builder = APIHelper.append_url_with_query_parameters(
_query_builder, _query_parameters)
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.get(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def 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/docs/working-w
ith-apis/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 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:
ListEmployeeWagesResponse: 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/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 retrieve_cash_drawer_shift(self,
location_id,
shift_id):
"""Does a GET request to /v2/cash-drawers/shifts/{shift_id}.
Provides the summary details for a single cash drawer shift. See
[ListCashDrawerShiftEvents]($e/CashDrawers/ListCashDrawerShiftEvents)
for a list of cash drawer shift events.
Args:
location_id (string): The ID of the location to retrieve cash
drawer shifts from.
shift_id (string): The shift ID.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/cash-drawers/shifts/{shift_id}'
_url_path = APIHelper.append_url_with_template_parameters(_url_path, {
'shift_id': {'value': shift_id, 'encode': True}
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {
'location_id': location_id
}
_query_builder = APIHelper.append_url_with_query_parameters(
_query_builder,
_query_parameters
)
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json'
}
# Prepare and execute request
_request = self.config.http_client.get(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def list_device_codes(self,
cursor=None,
location_id=None,
product_type=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](#paginatingresults) 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.
Returns:
ListDeviceCodesResponse: 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/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
}
_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_employees(self,
location_id=None,
status=None,
limit=None,
cursor=None):
"""Does a GET request to /v2/employees.
ListEmployees
Args:
location_id (string, optional): Filter employees returned to only
those that are associated with the specified location.
status (EmployeeStatus, optional): Specifies the EmployeeStatus to
filter the employee by.
limit (int, optional): The number of employees to be returned on
each page.
cursor (string, optional): The token required to retrieve the
specified page of results.
Returns:
ListEmployeesResponse: 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/employees'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {
'location_id': location_id,
'status': status,
'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 list_merchants(self,
cursor=None):
"""Does a GET request to /v2/merchants.
Returns `Merchant` information for a given access token.
If you don't know a `Merchant` ID, you can use this endpoint to
retrieve the merchant ID for an access token.
You can specify your personal access token to get your own merchant
information or specify an OAuth token
to get the information for the merchant that granted you access.
If you know the merchant ID, you can also use the
[RetrieveMerchant](#endpoint-merchants-retrievemerchant)
endpoint to get the merchant information.
Args:
cursor (int, optional): The cursor generated by the previous
response.
Returns:
ListMerchantsResponse: 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/merchants'
_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:
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_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 list_employee_roles(self, order=None, limit=None, batch_token=None):
"""Does a GET request to /v1/me/roles.
Provides summary information for all of a business's employee roles.
Args:
order (SortOrder, optional): The order in which employees are
listed in the response, based on their created_at
field.Default value: ASC
limit (int, optional): The maximum integer number of employee
entities to return in a single response. Default 100, maximum
200.
batch_token (string, optional): A pagination cursor to retrieve
the next set of results for your original query to the
endpoint.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v1/me/roles'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {
'order': order,
'limit': limit,
'batch_token': batch_token
}
_query_builder = APIHelper.append_url_with_query_parameters(
_query_builder, _query_parameters)
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.get(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def list_customer_groups(self,
cursor=None):
"""Does a GET request to /v2/customers/groups.
Retrieves the list of customer groups of a business.
Args:
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).
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/groups'
_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 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 add_query_parameter(self, name, value):
""" Add a query parameter to the HttpRequest.
Args:
name (string): The name of the query parameter.
value (string): The value of the query parameter.
"""
self.query_url = APIHelper.append_url_with_query_parameters(
self.query_url, {name: value})
self.query_url = APIHelper.clean_url(self.query_url)
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 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:
list of V1CashDrawerShift: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v1/{location_id}/cash-drawer-shifts'
_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_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 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=None,
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:
list of 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'
_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 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`, `CatalogImage` and
`CatalogModifierList` objects 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:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/catalog/object/{object_id}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'object_id': {
'value': object_id,
'encode': True
}})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_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_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:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/catalog/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_disputes(self, cursor=None, states=None, location_id=None):
"""Does a GET request to /v2/disputes.
Returns a list of disputes associated with a particular account.
Args:
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 the original query. For
more information, see
[Pagination](https://developer.squareup.com/docs/basics/api101/
pagination).
states (DisputeState, optional): The dispute states to filter the
result. If not specified, the endpoint returns all open
disputes (the dispute status is not `INQUIRY_CLOSED`, `WON`,
or `LOST`).
location_id (string, optional): The ID of the location for which
to return a list of disputes. If not specified, the endpoint
returns all open disputes (the dispute status is not
`INQUIRY_CLOSED`, `WON`, or `LOST`) associated with all
locations.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/disputes'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {
'cursor': cursor,
'states': states,
'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_customers(self, cursor=None, sort_field=None, sort_order=None):
"""Does a GET request to /v2/customers.
Lists customer profiles associated with a Square account.
Under normal operating conditions, newly created or updated customer
profiles become available
for the listing operation in well under 30 seconds. Occasionally,
propagation of the new or updated
profiles can take closer to one minute or longer, especially during
network incidents and outages.
Args:
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).
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:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/customers'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_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 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:
list of V1Settlement: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v1/{location_id}/settlements'
_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_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 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): TThe 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:
list of V1Refund: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v1/{location_id}/refunds'
_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_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 list_refunds(self,
location_id,
begin_time=None,
end_time=None,
sort_order=None,
cursor=None):
"""Does a GET request to /v2/locations/{location_id}/refunds.
Lists refunds for one of a business's locations.
In addition to full or partial tender refunds processed through Square
APIs,
refunds may result from itemized returns or exchanges through
Square's
Point of Sale applications.
Refunds with a `status` of `PENDING` are not currently included in
this
endpoint's response.
Max results per [page](#paginatingresults): 50
Args:
location_id (string): The ID of the location to list refunds for.
begin_time (string, optional): The beginning of the requested
reporting period, in RFC 3339 format. See [Date
ranges](#dateranges) for details on date
inclusivity/exclusivity. Default value: The current time
minus one year.
end_time (string, optional): The end of the requested reporting
period, in RFC 3339 format. See [Date ranges](#dateranges)
for details on date inclusivity/exclusivity. Default value:
The current time.
sort_order (SortOrder, optional): The order in which results are
listed in the response (`ASC` for oldest first, `DESC` for
newest first). Default value: `DESC`
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](#paginatingresults) for more information.
Returns:
ListRefundsResponse: 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}/refunds'
_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_parameters = {
'begin_time': begin_time,
'end_time': end_time,
'sort_order': sort_order,
'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 retrieve_inventory_changes(self,
catalog_object_id,
location_ids=None,
cursor=None):
"""Does a GET request to /v2/inventory/{catalog_object_id}/changes.
Returns a set of physical counts and inventory adjustments for the
provided [CatalogObject](#type-catalogobject) at the requested
[Location](#type-location)s.
Results are paginated and sorted in descending order according to
their
`occurred_at` timestamp (newest first).
There are no limits on how far back the caller can page. This endpoint
can be
used to display recent changes for a specific item. For more
sophisticated queries, use a batch endpoint.
Args:
catalog_object_id (string): ID of the
[CatalogObject](#type-catalogobject) to retrieve.
location_ids (string, optional): The [Location](#type-location)
IDs to look up as a comma-separated list. An empty list
queries all locations.
cursor (string, optional): A pagination cursor returned by a
previous call to this endpoint. Provide this to retrieve the
next set of results for the original query. See the
[Pagination](https://developer.squareup.com/docs/working-with-a
pis/pagination) guide for more information.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/inventory/{catalog_object_id}/changes'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {
'catalog_object_id': {
'value': catalog_object_id,
'encode': True
}
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {'location_ids': location_ids, 'cursor': cursor}
_query_builder = APIHelper.append_url_with_query_parameters(
_query_builder, _query_parameters)
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.get(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def delete_customer(self, customer_id, version=None):
"""Does a DELETE request to /v2/customers/{customer_id}.
Deletes a customer profile from a business, including any linked cards
on file.
As a best practice, you should include the `version` field in the
request to enable [optimistic
concurrency](https://developer.squareup.com/docs/working-with-apis/opti
mistic-concurrency) control. The value must be set to the current
version of the customer profile.
To delete a customer profile that was created by merging existing
profiles, you must use the ID of the newly created profile.
Args:
customer_id (string): The ID of the customer to delete.
version (long|int, optional): The current version of the customer
profile. As a best practice, you should include this
parameter to enable [optimistic
concurrency](https://developer.squareup.com/docs/working-with-a
pis/optimistic-concurrency) control. For more information,
see [Delete a customer
profile](https://developer.squareup.com/docs/customers-api/use-
the-api/keep-records#delete-customer-profile).
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}'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'customer_id': {
'value': customer_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_payments(self,
begin_time=None,
end_time=None,
sort_order=None,
cursor=None,
location_id=None,
total=None,
last_4=None,
card_brand=None):
"""Does a GET request to /v2/payments.
Retrieves a list of payments taken by the account making the request.
Max results per page: 100
Args:
begin_time (string, optional): Timestamp for the beginning of the
reporting period, in RFC 3339 format. Inclusive. 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
total (long|int, optional): The exact amount in the total_money
for a `Payment`.
last_4 (string, optional): The last 4 digits of `Payment` card.
card_brand (string, optional): The brand of `Payment` card. For
example, `VISA`
Returns:
ListPaymentsResponse: 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'
_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,
'total': total,
'last_4': last_4,
'card_brand': card_brand
}
_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_orders(self,
location_id,
order=None,
limit=None,
batch_token=None):
"""Does a GET request to /v1/{location_id}/orders.
Provides summary information for a merchant's online store orders.
Args:
location_id (string): The ID of the location to list online store
orders for.
order (SortOrder, optional): TThe order in which payments are
listed in the response.
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.
Returns:
list of V1Order: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v1/{location_id}/orders'
_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_parameters = {
'order': order,
'limit': limit,
'batch_token': batch_token
}
_query_builder = APIHelper.append_url_with_query_parameters(
_query_builder, _query_parameters)
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.get(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def 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:
list of V1Payment: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v1/{location_id}/payments'
_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_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
def list_payment_refunds(self,
begin_time=None,
end_time=None,
sort_order=None,
cursor=None,
location_id=None,
status=None,
source_type=None,
limit=None):
"""Does a GET request to /v2/refunds.
Retrieves a list of refunds for the account making the request.
The maximum results per page is 100.
Args:
begin_time (string, optional): The timestamp for the beginning of
the requested reporting period, in RFC 3339 format. Default:
The current time minus one year.
end_time (string, optional): The 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 cursor to
retrieve the next set of results for the original query. For
more information, see
[Pagination](https://developer.squareup.com/docs/basics/api101/
pagination).
location_id (string, optional): Limit results to the location
supplied. By default, results are returned for all locations
associated with the seller.
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 their 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 the payment source.
Default: If omitted, refunds are returned regardless of the
source type.
limit (int, optional): The maximum number of results to be
returned in a single page. It is possible to receive fewer
results than the specified limit on a given page. If the
supplied value is greater than 100, no more than 100 results
are returned. Default: 100
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_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,
'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 list_transactions(self,
location_id,
begin_time=None,
end_time=None,
sort_order=None,
cursor=None):
"""Does a GET request to /v2/locations/{location_id}/transactions.
Lists transactions for a particular location.
Transactions include payment information from sales and exchanges and
refund
information from returns and exchanges.
Max results per
[page](https://developer.squareup.com/docs/working-with-apis/pagination
): 50
Args:
location_id (string): The ID of the location to list transactions
for.
begin_time (string, optional): The beginning of the requested
reporting period, in RFC 3339 format. See [Date
ranges](https://developer.squareup.com/docs/build-basics/workin
g-with-dates) for details on date inclusivity/exclusivity.
Default value: The current time minus one year.
end_time (string, optional): The end of the requested reporting
period, in RFC 3339 format. See [Date
ranges](https://developer.squareup.com/docs/build-basics/workin
g-with-dates) for details on date inclusivity/exclusivity.
Default value: The current time.
sort_order (SortOrder, optional): The order in which results are
listed in the response (`ASC` for oldest first, `DESC` for
newest first). Default value: `DESC`
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.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/locations/{location_id}/transactions'
_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 = {
'begin_time': begin_time,
'end_time': end_time,
'sort_order': sort_order,
'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
