Square Python SDK

https://github.com/square/square-python-sdk
Admin
The Square Python library provides convenient access to the Square API from Python, supporting both...
Tokens:335,996
Snippets:2,208
Trust Score:9.4
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Run the example with poetry

Source: https://github.com/square/square-python-sdk/blob/master/examples/README.md

Commands to install dependencies and run the example. Execute from the 'example' directory.

```sh
cd example
poetry install
poetry run run-example
```

--------------------------------

### Create a customer example

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/customers.md

Example usage of the create method, creating a customer with an idempotency key, name, email, and address, then printing the customer id or errors.

```python
response = client.customers.create(
    idempotency_key="b993ebc6-436d-4eeb-a9d8-3f0f8b7b9b9b",
    given_name="Amelia",
    family_name="Earhart",
    email_address="amelia.earhart@example.com",
    address={"address_line_1": "77 Massachusetts Ave", "locality": "Cambridge", "administrative_district_level_1": "MA", "country": "US"},
)
print(response.customer.id if response.customer else response.errors)
```

--------------------------------

### Instantiate Square client with token

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/square-client.md

Example from the class docstring showing how to create a Square client with a token.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
```

--------------------------------

### PKCE flow example for obtain_token

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/o-auth.md

Example of the PKCE flow for obtaining an OAuth token. Requires client_id, grant_type, code, and code_verifier. No client_secret is needed.

```python
resp = client.o_auth.obtain_token(
    client_id="CLIENT_ID",
    grant_type="authorization_code",
    code="AUTHORIZATION_CODE",
    code_verifier="VERIFIER_STRING_42",
)
```

--------------------------------

### AsyncSquare usage example

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/square-client.md

Shows how to instantiate AsyncSquare with a token from the SQUARE_TOKEN environment variable and create a payment asynchronously. The example uses asyncio.run() to execute the main coroutine, which calls client.payments.create() with a source_id, idempotency_key, and amount_money.

```python
import asyncio
from square import AsyncSquare

async def main() -> None:
    client = AsyncSquare(token=os.environ.get("SQUARE_TOKEN"))
    await client.payments.create(
        source_id="ccof:GaJGNaZa8x4OgDJn4GB",
        idempotency_key="7b0f3ec5-086a-4871-8f13-3c81b3875218",
        amount_money={"amount": 1000, "currency": "USD"},
    )

asyncio.run(main())
```

--------------------------------

### Install Square Python SDK with pip

Source: https://github.com/square/square-python-sdk/blob/master/README.md

Install the Square Python library using pip. Requires Python 3.8 or later.

```sh
pip install squareup
```

--------------------------------

### List webhook subscriptions with pagination

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/webhooks.md

Lists webhook subscriptions using the GET v2/webhooks/subscriptions endpoint. The example iterates over results with a limit of 50 and includes disabled subscriptions, printing each subscription's ID and event types.

```python
for sub in client.webhooks.subscriptions.list(limit=50, include_disabled=True):
    print(sub.id, sub.event_types)
```

--------------------------------

### Example usage of list method

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/webhooks.md

Example of calling the list method on the webhooks client and iterating over the returned event types. Prints each event type.

```python
resp = client.webhooks.event_types.list()
for event_type in resp.event_types or []:
    print(event_type)
```

--------------------------------

### Search events example

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/events.md

Calls search_events with a limit and query filter for payment events, then iterates over the returned events to print their details.

```python
response = client.events.search_events(
    limit=100,
    query={
        "filter": {"event_types": ["payment.created", "payment.updated"]},
        "sort": {"field": "CREATED_AT", "order": "DESC"},
    },
)
for event in response.events or []:
    print(event.event_id, event.type, event.created_at)
```

--------------------------------

### Code flow example for obtain_token

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/o-auth.md

Example of the code flow for obtaining an OAuth token. Requires client_id, grant_type, client_secret, code, and redirect_uri. The response contains access_token, refresh_token, and expires_at.

```python
resp = client.o_auth.obtain_token(
    client_id="CLIENT_ID",
    grant_type="authorization_code",
    client_secret="CLIENT_SECRET",
    code="AUTHORIZATION_CODE",
    redirect_uri="https://example.com/oauth/callback",
    scopes=["PAYMENTS_READ", "CUSTOMERS_READ"],
)
print(resp.access_token, resp.refresh_token, resp.expires_at)
```

--------------------------------

### Authorize Usage

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Usage example for the authorize endpoint. Creates a Square client with a token and calls the method.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.o_auth.authorize()
```

--------------------------------

### Update location with client.locations.update()

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Updates an existing location. The example sets business hours and a description for a location.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.update(
    location_id="location_id",
    location={
        "business_hours": {
            "periods": [
                {
                    "day_of_week": "FRI",
                    "start_local_time": "07:00",
                    "end_local_time": "18:00",
                },
                {
                    "day_of_week": "SAT",
                    "start_local_time": "07:00",
                    "end_local_time": "18:00",
                },
                {
                    "day_of_week": "SUN",
                    "start_local_time": "09:00",
                    "end_local_time": "15:00",
                },
            ]
        },
        "description": "Midtown Atlanta store - Open weekends",
    },
)

```

--------------------------------

### Get Device Code

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Retrieves a DeviceCode with the associated ID. The example shows how to call the get method with the device code ID.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.devices.codes.get(
    id="id",
)

```

--------------------------------

### Error handling for constructor resolution

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/square-client.md

Example showing how to handle errors when constructing a Square client, such as a missing SQUARE_TOKEN environment variable.

```python
from square import Square
from square.environment import SquareEnvironment

try:
    client = Square(environment=SquareEnvironment.SANDBOX, token=os.environ["SQUARE_TOKEN"])
except Exception as e:
    # e.g. KeyError if SQUARE_TOKEN is unset and no token is passed
    ...
```

--------------------------------

### Create a subscription using client.subscriptions.create

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Call client.subscriptions.create to enroll a customer in a subscription. Provide ...

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.subscriptions.create(
    idempotency_key="8193148c-9586-11e6-99f9-28cfe92138cf",
    location_id="S8GWD5R9QB376",
    plan_variation_id="6JHXF3B2CW3YKHDV4XEM674H",
    customer_id="CHFGVKYY8RSV93M5KCYTG4PN0G",
    start_date="2023-06-20",
    card_id="ccof:qy5x8hHGYsgLrp4Q4GB",
    timezone="America/Los_Angeles",
    source={"name": "My Application"},
    phases=[
        {"ordinal": 0, "order_template_id": "U2NaowWxzXwpsZU697x7ZHOAnCNZY"}
    ],
)

```

--------------------------------

### Get dispute details

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Returns details about a specific dispute. The example shows how to call the get method with a dispute_id. The response is an AsyncHttpResponse[GetDisputeResponse].

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.disputes.get(
    dispute_id="dispute_id",
)
```

--------------------------------

### Initialize EventsClient with Square client

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/events.md

Creates a Square client with a token and accesses the events property to get an EventsClient instance.

```python
from square import Square

client = Square(token="YOUR_TOKEN")
events = client.events
```

--------------------------------

### Get a single TeamMemberWage by ID

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Returns a single TeamMemberWage specified by id. The example shows how to call the get method with the required id parameter.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.labor.team_member_wages.get(
    id="id",
)

```

--------------------------------

### Get break type by ID

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Returns a single BreakType specified by id. The example shows how to call the get method with the required id parameter.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.labor.break_types.get(
    id="id",
)

```

--------------------------------

### Create customer using client.customers.create() with required fields

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Create a new customer; must provide at least one of `given_name`, `family_name`, `company_name`, `email_address`, or `phone_number`. The example includes optional address, phone, reference, and note fields.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.create(
    given_name="Amelia",
    family_name="Earhart",
    email_address="Amelia.Earhart@example.com",
    address={
        "address_line1": "500 Electric Ave",
        "address_line2": "Suite 600",
        "locality": "New York",
        "administrative_district_level1": "NY",
        "postal_code": "10003",
        "country": "US",
    },
    phone_number="+1-212-555-4240",
    reference_id="YOUR_REFERENCE_ID",
    note="a customer",
)

```

--------------------------------

### List bookings with pagination using client.bookings.list

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Lists bookings with pagination support via client.bookings.list. The example shows both item-by-item iteration and page-by-page pagination, and the endpoint returns an AsyncPager[Booking, ListBookingsResponse].

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.bookings.list(
    limit=1,
    cursor="cursor",
    customer_id="customer_id",
    team_member_id="team_member_id",
    location_id="location_id",
    start_at_min="start_at_min",
    start_at_max="start_at_max",
)
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

```

--------------------------------

### Get a custom attribute

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Retrieves a custom attribute associated with a customer profile. The example shows calling get with customer_id, key, with_definition, and version parameters.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.custom_attributes.get(
    customer_id="customer_id",
    key="key",
    with_definition=True,
    version=1,
)

```

--------------------------------

### Use legacy SDK alongside new SDK in Python

Source: https://github.com/square/square-python-sdk/blob/master/examples/README.md

Shows how to instantiate both the new and legacy Square clients in one file. Requires the 'squareup_legacy' package. Replace '<YOUR_API_KEY>' with your actual API key.

```python
from square import Square
from square_legacy.client import Client as LegacySquare


def main():
    client = Square(token="<YOUR_API_KEY>")
    legacy_client = LegacySquare(access_token="<YOUR_API_KEY>")

    ...
```

--------------------------------

### Get Order Custom Attribute Definition

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Retrieves an order-related custom attribute definition. The example uses the Square client with a token and calls the get method with a key and version.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.orders.custom_attribute_definitions.get(
    key="key",
    version=1,
)

```

--------------------------------

### Initialize ReportingClient

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/reporting.md

Create a Square client and access the reporting sub-client. Requires a valid Square access token.

```python
from square import Square

client = Square(token="YOUR_TOKEN")
reporting = client.reporting
```

--------------------------------

### Update WorkweekConfig

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Updates a WorkweekConfig. The example shows calling the get method with an id and a workweek_config object containing start_of_week, start_of_day_local_time, and version.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.labor.workweek_configs.get(
    id="id",
    workweek_config={
        "start_of_week": "MON",
        "start_of_day_local_time": "10:00",
        "version": 10,
    },
)
```

--------------------------------

### Create a booking with client.bookings.create

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Creates a booking using client.bookings.create. The booking parameter is passed as an empty dictionary; required input includes location_id, start_at, and team_member_id/service_variation fields on the booking object.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.create(
    booking={},
)

```

--------------------------------

### Create a payment with client.payments.create

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Creates a payment using the provided source. Use this endpoint to charge a card or record a payment received outside of Square. The example sets source_id, idempotency_key, amount_money, app_fee_money, autocomplete, customer_id, location_id, reference_id, and note.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.payments.create(
    source_id="ccof:GaJGNaZa8x4OgDJn4GB",
    idempotency_key="7b0f3ec5-086a-4871-8f13-3c81b3875218",
    amount_money={"amount": 1000, "currency": "USD"},
    app_fee_money={"amount": 10, "currency": "USD"},
    autocomplete=True,
    customer_id="W92WH6P11H4Z77CTET0RNTGFW8",
    location_id="L88917AVBK2S5",
    reference_id="123456",
    note="Brief description",
)
```

--------------------------------

### GET reporting/v1/meta

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/endpoints.md

Gets metadata for reporting.

```APIDOC
## GET reporting/v1/meta

### Description
Gets metadata for reporting.

### Method
GET

### Endpoint
reporting/v1/meta

### Response
#### Success Response (200)
- **errors** (array) - Optional - Errors.
```

--------------------------------

### retrieve_token_status usage example

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/o-auth.md

Example of retrieving the status of an OAuth token. The response contains scopes and expires_at.

```python
resp = client.o_auth.retrieve_token_status(access_token="ACCESS_TOKEN")
print(resp.scopes, resp.expires_at)
```

--------------------------------

### Create an order with client.orders.create

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Creates a new order with line items, taxes, discounts, and an idempotency key. The order can include catalog objects and modifiers. Use this to create orders for purchase and settings.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.orders.create(
    order={
        "location_id": "057P5VYJ4A5X1",
        "reference_id": "my-order-001",
        "line_items": [
            {
                "name": "New York Strip Steak",
                "quantity": "1",
                "base_price_money": {"amount": 1599, "currency": "USD"},
            },
            {
                "quantity": "2",
                "catalog_object_id": "BEMYCSMIJL46OCDV4KYIKXIB",
                "modifiers": [
                    {"catalog_object_id": "CHQX7Y4KY6N5KINJKZCFURPZ"}
                ],
                "applied_discounts": [{"discount_uid": "one-dollar-off"}],
            },
        ],
        "taxes": [
            {
                "uid": "state-sales-tax",
                "name": "State Sales Tax",
                "percentage": "9",
                "scope": "ORDER",
            }
        ],
        "discounts": [
            {
                "uid": "labor-day-sale",
                "name": "Labor Day Sale",
                "percentage": "5",
                "scope": "ORDER",
            },
            {
                "uid": "membership-discount",
                "catalog_object_id": "DB7L55ZH2BGWI4H23ULIWOQ7",
                "scope": "ORDER",
            },
            {
                "uid": "one-dollar-off",
                "name": "Sale - $1.00 off",
                "amount_money": {"amount": 100, "currency": "USD"},
                "scope": "LINE_ITEM",
            },
        ],
    },
    idempotency_key="8193148c-9586-11e6-99f9-28cfe92138cf",
)
```

--------------------------------

### serialize_datetime usage example

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/core-utilities.md

Example usage of serialize_datetime with a UTC datetime, producing the output "2026-09-16T12:00:00Z".

```python
from square.core.datetime_utils import serialize_datetime
import datetime as dt

print(serialize_datetime(dt.datetime(2026, 9, 16, 12, 0, tzinfo=dt.timezone.utc)))  # 2026-09-16T12:00:00Z
```

--------------------------------

### Create a payment with the synchronous Square client

Source: https://github.com/square/square-python-sdk/blob/master/README.md

Instantiate the Square client with a token (defaults to environment variable SQUARE_TOKEN) and create a payment with the specified parameters. The example includes amount, currency, app fee, and other optional fields.

```python
from square import Square

client = Square(
    # This is the default and can be omitted.
    token=os.environ.get("SQUARE_TOKEN"),
)
client.payments.create(
    source_id="ccof:GaJGNaZa8x4OgDJn4GB",
    idempotency_key="7b0f3ec5-086a-4871-8f13-3c81b3875218",
    amount_money={
        "amount": 1000,
        "currency": "USD"
    },
    app_fee_money={
        "amount": 10,
        "currency": "USD"
    },
    autocomplete=True,
    customer_id="W92WH6P11H4Z77CTET0RNTGFW8",
    location_id="L88917AVBK2S5",
    reference_id="123456",
    note="Brief description"
)
```

--------------------------------

### client.subscriptions.create(...) -> AsyncHttpResponse[CreateSubscriptionResponse]

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Enrolls a customer in a subscription. If a card on file is provided, Square charges the card; otherwise, an invoice is sent. The subscription starts immediately unless an optional start_date is provided.

```APIDOC
## client.subscriptions.create(...) -> AsyncHttpResponse[CreateSubscriptionResponse]

### Description
Enrolls a customer in a subscription. If you provide a card on file in the request, Square charges the card for the subscription. Otherwise, Square sends an invoice to the customer's email address. The subscription starts immediately, unless the request includes the optional `start_date`. Each individual subscription is associated with a particular location.

### Method
POST

### Endpoint
/subscriptions

### Parameters
#### Request Body
- **idempotency_key** (string) - Required - A unique identifier for the request.
- **location_id** (string) - Required - The ID of the location associated with the subscription.
- **plan_variation_id** (string) - Required - The ID of the plan variation to subscribe to.
- **customer_id** (string) - Required - The ID of the customer subscribing.
- **start_date** (string) - Optional - The start date of the subscription (format: YYYY-MM-DD).
- **card_id** (string) - Optional - The ID of the card on file to charge.
- **timezone** (string) - Optional - The timezone for the subscription.
- **source** (object) - Optional - The source of the subscription, e.g., {"name": "My Application"}.
- **phases** (array) - Optional - A list of phases, each with an ordinal and order_template_id.

### Request Example
```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.subscriptions.create(
    idempotency_key="8193148c-9586-11e6-99f9-28cfe92138cf",
    location_id="S8GWD5R9QB376",
    plan_variation_id="6JHXF3B2CW3YKHDV4XEM674H",
    customer_id="CHFGVKYY8RSV93M5KCYTG4PN0G",
    start_date="2023-06-20",
    card_id="ccof:qy5x8hHGYsgLrp4Q4GB",
    timezone="America/Los_Angeles",
    source={"name": "My Application"},
    phases=[
        {"ordinal": 0, "order_template_id": "U2NaowWxzXwpsZU697x7ZHOAnCNZY"}
    ],
)
```

### Response
#### Success Response (200)
- **CreateSubscriptionResponse** - The response object containing the created subscription details.

#### Response Example
(Not provided in source)

```

--------------------------------

### Get location with client.locations.get()

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Retrieves details of a single location. Use 'main' as the location ID to get the main location.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.get(
    location_id="location_id",
)

```

--------------------------------

### Start transfer order

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Starts a transfer order, changing its status from DRAFT to STARTED and decrementing source inventory. Requires a token, transfer order ID, idempotency key, and version for optimistic concurrency. The order must be in DRAFT status with all required fields populated.

```Python
```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.transfer_orders.start(
    transfer_order_id="transfer_order_id",
    idempotency_key="EXAMPLE_IDEMPOTENCY_KEY_789",
    version=1753109537351,
)

```
```

--------------------------------

### Create a webhook subscription

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/webhooks.md

Creates a webhook subscription via POST v2/webhooks/subscriptions. The example provides an idempotency key and a subscription dictionary with name, event types, notification URL, and API version, then prints the new subscription's ID if successful.

```python
resp = client.webhooks.subscriptions.create(
    idempotency_key="b6a9e2b5-4d7a-4d3c-9d1e-8b8f0c1a2d3e",
    subscription={
        "name": "My Payment Webhook",
        "event_types": ["payment.created", "payment.updated"],
        "notification_url": "https://example.com/webhook",
        "api_version": "2026-09-16",
    },
)
if resp.subscription:
    print(resp.subscription.id)
```

--------------------------------

### Create Payment Link with Quick Pay in Python

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Creates a Square-hosted checkout page. Requires a unique idempotency key and quick_pay parameters including name, price_money, and location_id.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.checkout.payment_links.create(
    idempotency_key="cd9e25dc-d9f2-4430-aedb-61605070e95f",
    quick_pay={
        "name": "Auto Detailing",
        "price_money": {"amount": 10000, "currency": "USD"},
        "location_id": "A9Y43N9ABXZBP",
    },
)

```

--------------------------------

### Pay for an order using client.orders.pay

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Demonstrates how to use the pay method to settle an order with specific payment IDs. The total of the provided payment IDs must match the order total.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.orders.pay(
    order_id="order_id",
    idempotency_key="c043a359-7ad9-4136-82a9-c3f1d66dcbff",
    payment_ids=["EnZdNAlWCmfh6Mt5FMNST1o7taB", "0LRiVlbXVwe8ozu4KbZxd12mvaB"],
)
```

--------------------------------

### List WorkweekConfigs with pagination

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Returns a list of WorkweekConfig instances for a business. Supports pagination via limit and cursor parameters. The example shows iterating over the response and also paginating page-by-page.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.labor.workweek_configs.list(
    limit=1,
    cursor="cursor",
)
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page
```

--------------------------------

### Create location with client.locations.create()

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Creates a new location with required name and optional address and description. The name must be unique within the seller account.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.create(
    location={
        "name": "Midtown",
        "address": {
            "address_line1": "1234 Peachtree St. NE",
            "locality": "Atlanta",
            "administrative_district_level1": "GA",
            "postal_code": "30309",
        },
        "description": "Midtown Atlanta store",
    },
)

```

--------------------------------

### List payments with pagination

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/payments.md

Example usage of the list method. It iterates over the returned pager directly or uses iter_pages() for page-by-page traversal. The example filters by location_id and limit.

```python
response = client.payments.list(location_id="L88917AVBK2S5", limit=50)
for payment in response:
    print(payment.id, payment.amount_money)
# page-by-page alternative
for page in response.iter_pages():
    for payment in page.items or []:
        ...
```

--------------------------------

### Get bank account by ID with client.bank_accounts.get()

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Retrieves details of a BankAccount linked to a Square account using the get endpoint. The bank_account_id parameter is required. Returns an AsyncHttpResponse[GetBankAccountResponse].

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bank_accounts.get(
    bank_account_id="bank_account_id",
)

```

--------------------------------

### Usage example with RequestOptions

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/request-options.md

Shows how to pass RequestOptions to a service method call, overriding timeout, retries, and adding custom headers and query parameters.

```python
from square import Square
from square.core.request_options import RequestOptions

client = Square(token="YOUR_TOKEN")

client.payments.create(
    source_id="ccof:GaJGNaZa8x4OgDJn4GB",
    idempotency_key="7b0f3ec5-086a-4871-8f13-3c81b3875218",
    amount_money={"amount": 100, "currency": "USD"},
    request_options=RequestOptions(
        timeout_in_seconds=30,
        max_retries=5,
        additional_headers={"X-Correlation-Id": "abc-123"},
        additional_query_parameters={"debug": "true"},
    ),
)
```

--------------------------------

### Create gift card activity with client.gift_cards.activities.create()

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Creates a gift card activity to manage the balance or state of a gift card. The example shows creating an ACTIVATE activity with an idempotency key and activity details including order_id and line_item_uid.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.gift_cards.activities.create(
    idempotency_key="U16kfr-kA70er-q4Rsym-7U7NnY",
    gift_card_activity={
        "type": "ACTIVATE",
        "location_id": "81FN9BNFZTKS4",
        "gift_card_id": "gftc:6d55a72470d940c6ba09c0ab8ad08d20",
        "activate_activity_details": {
            "order_id": "jJNGHm4gLI6XkFbwtiSLqK72KkAZY",
            "line_item_uid": "eIWl7X0nMuO9Ewbh0ChIx",
        },
    },
)

```

--------------------------------

### Get bookings custom attribute definition using get()

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Call the get endpoint to retrieve a bookings custom attribute definition by key and optional version. Requires a Square client with a token. If the requesting application is not the owner, use the qualified key. The version parameter enables strongly consistent reads; if the specified version is higher than the current one, Square returns a BAD_REQUEST error.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.custom_attribute_definitions.get(
    key="key",
    version=1,
)

```

--------------------------------

### Create bank account with client.bank_accounts.create_bank_account()

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Stores a bank account on file for a Square account using the create_bank_account endpoint. Requires an idempotency_key and a source_id (a payment token created by WebSDK); customer_id is optional. The response is an AsyncHttpResponse[CreateBankAccountResponse].

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bank_accounts.create_bank_account(
    idempotency_key="4e43559a-f0fd-47d3-9da2-7ea1f97d94be",
    source_id="bnon:CA4SEHsQwr0rx6DbWLD5BQaqMnoYAQ",
    customer_id="HM3B2D5JKGZ69359BTEHXM2V8M",
)

```

--------------------------------

### get

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Retrieves a payment link.

```APIDOC
## get

### Description
Retrieves a payment link.

### Method
GET

### Endpoint
/payment-links/{payment_link_id}

### Parameters
#### Path Parameters
- **payment_link_id** (string) - Required - The ID of the payment link to retrieve.

### Request Example
```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.checkout.payment_links.get(
    payment_link_id="string"
)
```

### Response
#### Success Response (200)
- **payment_link** (PaymentLink) - The retrieved payment link.

#### Response Example
```json
{
  "payment_link": {
    "id": "string",
    "url": "string"
  }
}
```
```

--------------------------------

### create

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/customers.md

Creates a new customer with the provided details. Returns the created customer or errors.

```APIDOC
## [POST] /customers

### Description
Creates a new customer with the provided details. Returns the created customer or errors.

### Method
POST

### Endpoint
/customers

### Parameters
#### Request Body
- **idempotency_key** (string) - Optional - Idempotency key for the request.
- **given_name** (string) - Optional - Customer given name.
- **family_name** (string) - Optional - Customer family name.
- **company_name** (string) - Optional - Company name.
- **nickname** (string) - Optional - Nickname.
- **email_address** (string) - Optional - Email address.
- **address** (object) - Optional - Postal address (TypedDict).
- **phone_number** (string) - Optional - Phone number.
- **reference_id** (string) - Optional - User-defined reference.
- **note** (string) - Optional - Note on the customer.
- **birthday** (string) - Optional - YYYY-MM-DD (or MM-DD) birthday.
- **tax_ids** (object) - Optional - EU VAT/IE PPS tax IDs.

### Request Example
```python
response = client.customers.create(
    idempotency_key="b993ebc6-436d-4eeb-a9d8-3f0f8b7b9b9b",
    given_name="Amelia",
    family_name="Earhart",
    email_address="amelia.earhart@example.com",
    address={"address_line_1": "77 Massachusetts Ave", "locality": "Cambridge", "administrative_district_level_1": "MA", "country": "US"},
)
print(response.customer.id if response.customer else response.errors)
```

### Response
#### Success Response (200)
- **customer** (Customer) - The created customer object.

#### Response Example
```json
{
  "customer": {
    "id": "string",
    "given_name": "string",
    "family_name": "string"
  }
}
```
```

--------------------------------

### get

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Retrieves a booking by its ID.

```APIDOC
## get

### Description
Retrieves a booking.

To call this endpoint with buyer-level permissions, set `APPOINTMENTS_READ` for the OAuth scope.
To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.

### Method
get

### Endpoint
client.bookings.get

### Parameters
#### Path Parameters
- **booking_id** (str) - Required - The ID of the [Booking](entity:Booking) object representing the to-be-retrieved booking.

#### Query Parameters
- **request_options** (typing.Optional[RequestOptions]) - Optional - Request-specific configuration.

### Request Example
```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.get(
    booking_id="booking_id",
)
```

### Response
#### Success Response (200)
- **AsyncHttpResponse[GetBookingResponse]** - The response containing the booking details.

#### Response Example
```json
{
  "booking": {}
}
```
```

--------------------------------

### Initialize Square client and access OAuth

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/o-auth.md

Creates a Square client with a token and retrieves the OAuth client for making OAuth API calls.

```python
from square import Square

client = Square(token="YOUR_TOKEN")
oauth = client.o_auth
```

--------------------------------

### GET /v2/labor/scheduled-shifts/{id}

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Retrieves a scheduled shift by its ID.

```APIDOC
## [GET] /v2/labor/scheduled-shifts/{id}

### Description
Retrieves a scheduled shift by ID.

### Method
GET

### Endpoint
/v2/labor/scheduled-shifts/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - The ID of the scheduled shift to retrieve.

#### Query Parameters
- **request_options** (RequestOptions) - Optional - Request-specific configuration.

### Request Example
```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.labor.retrieve_scheduled_shift(
    id="id",
)
```

### Response
#### Success Response (200)
- **scheduled_shift** (ScheduledShift) - The requested scheduled shift.
- **errors** (List[Error]) - Any errors that occurred during the request.

#### Response Example
```json
{
  "scheduled_shift": {
    "id": "shift_id",
    "version": 1,
    "draft_shift_details": {},
    "published_shift_details": {}
  },
  "errors": []
}
```
```

--------------------------------

### client.bookings.create

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Creates a booking with the required input fields.

```APIDOC
## [POST] /v2/bookings

### Description
Creates a booking.

The required input must include the following:
- `Booking.location_id`
- `Booking.start_at`
- `Booking.AppointmentSegment.team_member_id`
- `Booking.AppointmentSegment.service_variation_id`
- `Booking.AppointmentSegment.service_variation_version`

To call this endpoint with buyer-level permissions, set `APPOINTMENTS_WRITE` for the OAuth scope.
To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.

For calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to *Appointments Plus*
or *Appointments Premium*.

### Method
POST

### Endpoint
/v2/bookings

### Parameters
#### Request Body
- **booking** (object) - Required - The booking to create.

### Request Example
```json
{
  "booking": {}
}
```

### Response
#### Success Response (200)
- **booking** (object) - The created booking.
- **errors** (array) - Any errors that occurred during the request.

#### Response Example
```json
{
  "booking": {},
  "errors": []
}
```
```

--------------------------------

### GET /v2/invoices/{invoice_id}

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Retrieves an invoice by invoice ID.

```APIDOC
## GET /v2/invoices/{invoice_id}

### Description
Retrieves an invoice by invoice ID.

### Method
GET

### Endpoint
/v2/invoices/{invoice_id}

### Parameters
#### Path Parameters
- **invoice_id** (str) - Required - The ID of the invoice to retrieve.

#### Query Parameters
- **request_options** (typing.Optional[RequestOptions]) - Optional - Request-specific configuration.

### Request Example
```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.invoices.get(
    invoice_id="invoice_id",
)
```

### Response
#### Success Response (200)
- **invoice** (Invoice) - The retrieved invoice.

#### Response Example
```json
{
  "invoice": {}
}
```
```

--------------------------------

### GET /v2/devices/{device_id}

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Retrieves Device with the associated `device_id`.

```APIDOC
## [GET] /v2/devices/{device_id}

### Description
Retrieves Device with the associated `device_id`.

### Method
GET

### Endpoint
/v2/devices/{device_id}

### Parameters
#### Path Parameters
- **device_id** (string) - Required - The unique ID for the desired `Device`.

### Request Example
```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.devices.get(
    device_id="device_id",
)
```

### Response
#### Success Response (200)
- **device** (object) - The device with the associated ID.
- **errors** (array) - Any errors that occurred during the request.

#### Response Example
```json
{
  "device": {}
}
```
```

--------------------------------

### Refund a payment using Square Python SDK

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Shows how to create a Square client and call the refunds.refund_payment method with the required parameters. The token should be replaced with your actual OAuth token. The example uses a sample idempotency key, amount, app fee, payment ID, and reason.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.refunds.refund_payment(
    idempotency_key="9b7f2dcf-49da-4411-b23e-a2d6af21333a",
    amount_money={"amount": 1000, "currency": "USD"},
    app_fee_money={"amount": 10, "currency": "USD"},
    payment_id="R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY",
    reason="Example",
)
```

--------------------------------

### GET v2/payments/{payment_id}

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/endpoints.md

Retrieves a specific payment by its ID.

```APIDOC
## GET v2/payments/{payment_id}

### Description
Retrieves a specific payment by its ID.

### Method
GET

### Endpoint
`/v2/payments/{payment_id}`

### Parameters
#### Path Parameters
- **payment_id** (string) - Required - The ID of the payment to retrieve.

### Response
#### Success Response (200)
- **errors** (array) - List of errors, if any.
- **payment** (object) - The payment object.

#### Response Example
```json
{
  "errors": [],
  "payment": {}
}
```
```

--------------------------------

### Create a gift card with client.gift_cards.create

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Creates a digital gift card or registers a physical (plastic) gift card. The resulting gift card has a `PENDING` state. To activate it, call `CreateGiftCardActivity` with an `ACTIVATE` activity or use `RefundPayment` to refund a payment to the new gift card.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.gift_cards.create(
    idempotency_key="NC9Tm69EjbjtConu",
    location_id="81FN9BNFZTKS4",
    gift_card={"type": "DIGITAL"},
)

```

--------------------------------

### list

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/webhooks.md

Lists webhook subscriptions. Endpoint: GET v2/webhooks/subscriptions.

```APIDOC
## [GET] v2/webhooks/subscriptions

### Description
Lists webhook subscriptions.

### Method
GET

### Endpoint
v2/webhooks/subscriptions

### Parameters
#### Query Parameters
- **cursor** (string) - Optional - A pagination cursor returned by a previous call to this endpoint.
- **include_disabled** (boolean) - Optional - Indicates whether to include disabled subscriptions in the response.
- **sort_order** (string) - Optional - The order (e.g., ASC or DESC) in which to sort the results.
- **limit** (integer) - Optional - The maximum number of results to return per page.

### Request Example
```python
for sub in client.webhooks.subscriptions.list(limit=50, include_disabled=True):
    print(sub.id, sub.event_types)
```

### Response
#### Success Response (200)
- **subscriptions** (array) - List of WebhookSubscription objects.
- **cursor** (string) - Pagination cursor for the next page.

#### Response Example
```json
{
  "subscriptions": [
    {
      "id": "wbhk_1G4605aLJG4e4",
      "event_types": ["payment.created"]
    }
  ],
  "cursor": "next-page-cursor"
}
```
```

--------------------------------

### client.bookings.create

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Creates a new booking with the provided details.

```APIDOC
## [POST] /v2/bookings

### Description
Creates a new booking with the provided details.

### Method
POST

### Endpoint
/v2/bookings

### Parameters
#### Request Body
- **booking** (BookingParams) - Required - The details of the booking to be created.
- **idempotency_key** (string) - Optional - A unique key to make this request an idempotent operation.
- **request_options** (RequestOptions) - Optional - Request-specific configuration.

### Request Example
{
  "booking": {},
  "idempotency_key": "string"
}

### Response
#### Success Response (200)
- **booking** (Booking) - The created booking.

#### Response Example
{
  "booking": {}
}
```

--------------------------------

### get

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Retrieves a specific customer group as identified by the `group_id` value.

```APIDOC
## get

### Description
Retrieves a specific customer group as identified by the `group_id` value.

### Method
GET

### Endpoint
/customers/groups/{group_id}

### Parameters
#### Path Parameters
- **group_id** (string) - Required - The ID of the customer group to retrieve.

### Request Example
```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.groups.get(
    group_id="group_id",
)
```

### Response
#### Success Response (200)
- **group** (CustomerGroup) - The retrieved customer group.

#### Response Example
```json
{
  "group": {
    "id": "group_id",
    "name": "Loyal Customers"
  }
}
```
```

--------------------------------

### CustomersClient class definition

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/customers.md

Shows the CustomersClient class definition, including the constructor that initializes the raw client and lazily initialized nested resource clients, and the with_raw_response property that returns the raw client.

```python
class CustomersClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper):
        self._raw_client = RawCustomersClient(client_wrapper=client_wrapper)
        self._client_wrapper = client_wrapper
        self._custom_attribute_definitions: typing.Optional[CustomAttributeDefinitionsClient] = None
        self._groups: typing.Optional[GroupsClient] = None
        self._segments: typing.Optional[SegmentsClient] = None
        self._cards: typing.Optional[CardsClient] = None
        self._custom_attributes: typing.Optional[CustomAttributesClient] = None

    @property
    def with_raw_response(self) -> RawCustomersClient:
        ...
```

--------------------------------

### Call load with query parameters

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/reporting.md

Example of calling load with a query that includes measures, dimensions, and a time range. Handles the 'Continue wait' response by retrying.

```python
from square.requests.query import QueryParams  # TypedDict

response = client.reporting.load(
    cache="stale-while-revalidate",
    query={
        "measures": [{"name": "payment_total"}],
        "dimensions": [{"name": "payment_created_at", "format": "Day"}],
        "time_range": {"start": "2026-01-01", "end": "2026-01-31"},
    },
)
if response.data is not None:
    print(response.data)
else:
    # "Continue wait" — retry the identical request
    ...
```

--------------------------------

### Module version

Source: https://github.com/square/square-python-sdk/blob/master/_autodocs/api-reference/square-client.md

Gets the package version from importlib.metadata. The distribution version is 46.0.0.20260916.

```python
from importlib import metadata

__version__ = metadata.version("squareup")
```

--------------------------------

### Get payment details

Source: https://github.com/square/square-python-sdk/blob/master/reference.md

Retrieves details for a specific payment using its payment ID.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.payments.get(
    payment_id="payment_id",
)

```
Tokens:
Raw