Learn about the Square Python SDK features.
Use the import
statement to load the Square Python SDK and make it available to your application:
from square.client import Client
To use the Square SDK, instantiate a Client
object and initialize it with the appropriate environment and corresponding access token, as shown:
For testing, Square provides a Sandbox environment as shown in the following code fragment:
client = Client( bearer_auth_credentials=BearerAuthCredentials( access_token=os.environ['SQUARE_ACCESS_TOKEN'] ), environment='sandbox')To access production resources, set the environment to
production
as shown:client = Client( bearer_auth_credentials=BearerAuthCredentials( access_token=os.environ['SQUARE_ACCESS_TOKEN'] ), environment='production')To set a custom environment, provide a
custom_url
and set the environment tocustom
, as shown:client = Client( bearer_auth_credentials=BearerAuthCredentials( access_token=os.environ['SQUARE_ACCESS_TOKEN'] ), environment='custom', custom_url='https://your.customdomain.com')
The following example shows how to call a Square API:
from square.http.auth.o_auth_2 import BearerAuthCredentials
from square.client import Client
import os
client = Client(
bearer_auth_credentials=BearerAuthCredentials(
access_token=os.environ['SQUARE_ACCESS_TOKEN']
),
environment='sandbox')
result = client.locations.list_locations()
if result.is_success():
for location in result.body['locations']:
print(f"{location['id']}: ", end="")
print(f"{location['name']}, ", end="")
print(f"{location['address']['address_line_1']}, ", end="")
print(f"{location['address']['locality']}")
elif result.is_error():
for error in result.errors:
print(error['category'])
print(error['code'])
print(error['detail'])
The Client
object instantiates every API class and exposes them as properties. You work with an API by calling methods on an instance of an API class. Most of these methods require you to provide a dictionary that contains the request body.
Some API classes accept nested data (for example, address
, customer
, and order
). For these, you can embed hashes containing the data within the body
dictionary.
The following creates a new customer, with a nested dictionary for address
:
import uuid
address = {
"address_line_1": '1455 Market St',
"address_line_2": 'San Francisco, CA 94103'
}
body = {
"idempotency_key": str(uuid.uuid4()),
"given_name": 'given-vs1',
"family_name": 'family-vs1',
"address": address
}
result = client.customers.create_customer(body)
if result.is_success():
print(
"New customer created with customer ID ",
result.body['customer']['id']
)
elif result.is_error():
for error in result.errors:
print(error['category'])
print(error['code'])
print(error['detail'])
The Square API endpoints can have path parameters, query parameters, and a request body. When you make corresponding method calls using the Square Python SDK, you provide the values as follows:
Request body - In the Square Python SDK, a request body is represented by a dictionary. Depending on the method being called, the parameter values are represented as scalars or as embedded dictionaries.
result = client.customers.create_customer({ "given_name": 'Mary', "family_name": 'Smith', "address": { "address_line_1": "1455 Market St", "address_line_2": "San Francisco, CA 94103" }, "idempotency_key": str(uuid.uuid4()) }) if result.is_success(): print(result.body) elif result.is_error(): for error in result.errors: print(error['category']) print(error['code']) print(error['detail'])Path and query parameters - For example:
- The RetrieveCustomer endpoint has a
customer_id
path parameter (GET /v2/customers/{customer_id}
). - The ListCustomers endpoint has several query parameters such as
cursor
andlimit
.
You provide these as parameters to the method calls. The following example passes the
customer_id
path parameter as a parameter to theupdate_customer
method.result = client.customers.update_customer( customer_id = "GZ48C4P2CWVXV7F7K2ZH795RSG", body = { "given_name": "Fred", "family_name": "Jones", "address": { "address_line_1": "1455 Market St", "address_line_2": "San Francisco, CA 94103" }, "version": 0 }) if result.is_success(): print(result.body) elif result.is_error(): for error in result.errors: print(error['category']) print(error['code']) print(error['detail'])For an example of query parameters, see Pagination.
- The RetrieveCustomer endpoint has a
You can configure the number of retries and the timeout values for HTTP requests when using the Square Python SDK:
Retries - By default, the Square SDK doesn't retry a failed request. When your application starts, the Square SDK sets the number of retries to 0. You have the option to configure a different value when you create a client. Retries can help improve application stability by allowing applications to handle momentary failures in connecting to a service by transparently retrying a failed request.
Timeout - Timeout is the time period that a client waits for a server response. The Square SDK sets the default timeout to 60 seconds. On timeout, the SDK throws an exception. You have the option to configure a timeout value at the client level.
The following code creates a client and sets the number of retries to 2 and the timeout to 60 seconds:
client = Client(
bearer_auth_credentials=BearerAuthCredentials(
access_token=os.environ['SQUARE_ACCESS_TOKEN']
),
environment='sandbox',
max_retries=2,
timeout=60
)
Configuring a client with long timeout values and a high number of retries can cause some SDK operations to appear unresponsive. There are several considerations that apply when configuring the timeout and retries. These include:
- For network issues (decrease in network connectivity and response speed), how should the application respond? Do you want the call to fail fast, or do you want the application to retry the failed call?
- Buyer-facing applications might need to be responsive compared to a background job that can tolerate increased latency due increased timeout values and retries.
The response object contains information about both the request and the response. You can use the response object's is_success
and is_error
methods to determine whether the API call succeeded or failed:
If an API call succeeds, the response object contains the data returned from that call.
If an API call fails, the response object contains any errors that were encountered during processing.
result = client.locations.list_locations()
if result.is_success():
print("Successfully called List Locations")
# Your business logic here
elif result.is_error():
print("Successfully called List Locations")
for error in result.errors:
print(error['category'])
print(error['code'])
print(error['detail'])
# Your error-handling code here
For more information, see Square API errors.