def test_create_customer(self):
# Parameters for the API call
body = APIHelper.json_deserialize(
'{"given_name":"Amelia","family_name":"Earhart","email_address":"Amelia.Ear'
'*****@*****.**","address":{"address_line_1":"500 Electric Ave","address_l'
'ine_2":"Suite 600","locality":"New York"},"phone_number":"1-212-555-4240","'
'reference_id":"YOUR_REFERENCE_ID","note":"a customer"}')
# Perform the API call through the SDK function
result = self.controller.create_customer(body)
# Test response code
self.assertEquals(self.response_catcher.response.status_code, 200)
def catalog_info(self):
"""Does a GET request to /v2/catalog/info.
Retrieves information about the Square Catalog API, such as batch
size
limits that can be used by the `BatchUpsertCatalogObjects` endpoint.
Returns:
CatalogInfoResponse: 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/info'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {'accept': 'application/json'}
# Prepare and execute request
_request = self.config.http_client.get(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def retrieve_business(self):
"""Does a GET request to /v1/me.
Get the general information for a business.
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'
_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_locations(self):
"""Does a GET request to /v1/me/locations.
Provides details for all business locations associated with a Square
account, including the Square-assigned object ID for the location.
Returns:
list of V1Merchant: 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/locations'
_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 get_base_uri(self, server='default'):
"""Generates the appropriate base URI for the environment and the
server.
Args:
server (Configuration.Server): The server enum for which the base
URI is required.
Returns:
String: The base URI.
"""
parameters = {
"custom_url": {
'value': self.custom_url,
'encode': False
},
}
return APIHelper.append_url_with_template_parameters(
self.environments[self.environment][server], parameters)
def create_mobile_authorization_code(self, body):
"""Does a POST request to /mobile/authorization-code.
Generates code to authorize a mobile application to connect to a
Square card reader
Authorization codes are one-time-use and expire __60 minutes__ after
being issued.
__Important:__ The `Authorization` header you provide to this endpoint
must have the following format:
```
Authorization: Bearer ACCESS_TOKEN
```
Replace `ACCESS_TOKEN` with a
[valid production authorization
credential](https://developer.squareup.com/docs/docs/build-basics/acces
s-tokens).
Args:
body (CreateMobileAuthorizationCodeRequest): An object containing
the fields to POST for the request. See the corresponding
object definition for field details.
Returns:
CreateMobileAuthorizationCodeResponse: 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 = '/mobile/authorization-code'
_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 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` to compute the points. For more information,
see [Loyalty Program
Overview](https://developer.squareup.com/docs/docs/loyalty/overview).
You then provide the points in a request to this endpoint.
For more information, see [Accumulate
points](https://developer.squareup.com/docs/docs/loyalty-api/overview/#
accumulate-points).
Args:
account_id (string): The [loyalty account](#type-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:
AccumulateLoyaltyPointsResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/loyalty/accounts/{account_id}/accumulate'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'account_id': account_id})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'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=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 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 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 a
[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.
Args:
request (CreateCatalogImageRequest, optional): TODO: type
description here.
image_file (typing.BinaryIO, optional): TODO: type description
here.
Returns:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/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 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:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/catalog/batch-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_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 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:
ListInvoicesResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/invoices'
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_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 delete_invoice(self,
invoice_id,
version=None):
"""Does a DELETE request to /v2/invoices/{invoice_id}.
Deletes the specified invoice. When an invoice is deleted, the
associated Order status changes to CANCELED. You can only delete a
draft
invoice (you cannot delete an invoice scheduled for publication, or a
published invoice).
Args:
invoice_id (string): The ID of the invoice to delete.
version (int, optional): The version of the
[invoice](#type-invoice) to delete. If you do not know the
version, you can call
[GetInvoice](#endpoint-Invoices-GetInvoice) or
[ListInvoices](#endpoint-Invoices-ListInvoices).
Returns:
DeleteInvoiceResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/invoices/{invoice_id}'
_url_path = APIHelper.append_url_with_template_parameters(_url_path, {
'invoice_id': invoice_id
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_parameters = {
'version': version
}
_query_builder = APIHelper.append_url_with_query_parameters(
_query_builder,
_query_parameters
)
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json'
}
# Prepare and execute request
_request = self.config.http_client.delete(_query_url, headers=_headers)
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def 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:
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/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 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 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](#type-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:
CalculateLoyaltyPointsResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/loyalty/programs/{program_id}/calculate'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'program_id': program_id})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(
_query_url,
headers=_headers,
parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def create_refund(self,
location_id,
transaction_id,
body):
"""Does a POST request to /v2/locations/{location_id}/transactions/{transaction_id}/refund.
Initiates a refund for a previously charged tender.
You must issue a refund within 120 days of the associated payment.
See
[this article](https://squareup.com/help/us/en/article/5060) for more
information
on refund behavior.
NOTE: Card-present transactions with Interac credit cards **cannot be
refunded using the Connect API**. Interac transactions must refunded
in-person (e.g., dipping the card using POS app).
Args:
location_id (string): The ID of the original transaction's
associated location.
transaction_id (string): The ID of the original transaction that
includes the tender to refund.
body (CreateRefundRequest): An object containing the fields to
POST for the request. See the corresponding object definition
for field details.
Returns:
CreateRefundResponse: 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}/transactions/{transaction_id}/refund'
_url_path = APIHelper.append_url_with_template_parameters(_url_path, {
'location_id': location_id,
'transaction_id': transaction_id
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def 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 terminal state (`REDEEMED`).
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.
For more information, see
[Loyalty
rewards](https://developer.squareup.com/docs/docs/loyalty-api/overview/
#loyalty-overview-loyalty-rewards).
Args:
reward_id (string): The ID of the [loyalty
reward](#type-LoyaltyReward) to redeem.
body (RedeemLoyaltyRewardRequest): An object containing the fields
to POST for the request. See the corresponding object
definition for field details.
Returns:
RedeemLoyaltyRewardResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/loyalty/rewards/{reward_id}/redeem'
_url_path = APIHelper.append_url_with_template_parameters(
_url_path, {'reward_id': reward_id})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'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_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 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:
PublishInvoiceResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/invoices/{invoice_id}/publish'
_url_path = APIHelper.append_url_with_template_parameters(_url_path, {
'invoice_id': invoice_id
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def 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:
ApiResponse: An object with the response value as well as other
useful information such as status codes and headers. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/catalog/batch-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 charge(self,
location_id,
body):
"""Does a POST request to /v2/locations/{location_id}/transactions.
Charges a card represented by a card nonce or a customer's card on
file.
Your request to this endpoint must include _either_:
- A value for the `card_nonce` parameter (to charge a card nonce
generated
with the `SqPaymentForm`)
- Values for the `customer_card_id` and `customer_id` parameters (to
charge
a customer's card on file)
In order for an eCommerce payment to potentially qualify for
[Square chargeback
protection](https://squareup.com/help/article/5394), you
_must_ provide values for the following parameters in your request:
- `buyer_email_address`
- At least one of `billing_address` or `shipping_address`
When this response is returned, the amount of Square's processing fee
might not yet be
calculated. To obtain the processing fee, wait about ten seconds and
call
[RetrieveTransaction](#endpoint-retrievetransaction). See the
`processing_fee_money`
field of each [Tender included](#type-tender) in the transaction.
Args:
location_id (string): The ID of the location to associate the
created transaction with.
body (ChargeRequest): An object containing the fields to POST for
the request. See the corresponding object definition for
field details.
Returns:
ChargeResponse: 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}/transactions'
_url_path = APIHelper.append_url_with_template_parameters(_url_path, {
'location_id': location_id
})
_query_builder = self.config.get_base_uri()
_query_builder += _url_path
_query_url = APIHelper.clean_url(_query_builder)
# Prepare headers
_headers = {
'accept': 'application/json',
'content-type': 'application/json; charset=utf-8'
}
# Prepare and execute request
_request = self.config.http_client.post(_query_url, headers=_headers, parameters=APIHelper.json_serialize(body))
OAuth2.apply(self.config, _request)
_response = self.execute_request(_request)
decoded = APIHelper.json_deserialize(_response.text)
if type(decoded) is dict:
_errors = decoded.get('errors')
else:
_errors = None
_result = ApiResponse(_response, body=decoded, errors=_errors)
return _result
def create_shift(self, body):
"""Does a POST request to /v2/labor/shifts.
Creates a new `Shift`.
A `Shift` represents a complete work day for a single employee.
You must provide the following values in your request to this
endpoint:
- `location_id`
- `employee_id`
- `start_at`
An attempt to create a new `Shift` can result in a `BAD_REQUEST` error
when:
- The `status` of the new `Shift` is `OPEN` and the employee has
another
shift with an `OPEN` status.
- The `start_at` date is in the future
- the `start_at` or `end_at` overlaps another shift for the same
employee
- If `Break`s are set in the request, a break `start_at`
must not be before the `Shift.start_at`. A break `end_at` must not be
after
the `Shift.end_at`
Args:
body (CreateShiftRequest): An object containing the fields to POST
for the request. See the corresponding object definition for
field details.
Returns:
CreateShiftResponse: Response from the API. Success
Raises:
APIException: When an error occurs while fetching the data from
the remote API. This exception includes the HTTP Response
code, an error message, and the HTTP body that was received in
the request.
"""
# Prepare query URL
_url_path = '/v2/labor/shifts'
_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 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, espeically during
network incidents and outages.
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:
list of V1EmployeeRole: 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/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_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 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:
V1EmployeeRole: 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/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
