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