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