### Run Legacy Compatibility Example

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

Navigate to the example directory, install dependencies using Poetry, and run the example script. Ensure you have Poetry installed.

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

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

### Create Subscription - Square Python SDK

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

Enrolls a customer in a subscription. This example shows how to create a subscription with a specified start date, card on file, and phases. Square will charge the card or send an invoice based on the request.

```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"}
    ],
)

```

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

### Install Square Python SDK

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

Install the Square Python SDK using pip. Ensure you have Python 3.8+.

```sh
pip install squareup
```

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

### Bookings API

Source: https://context7.com/square/square-python-sdk/llms.txt

Examples for searching availability, creating, listing, and canceling bookings using the Square Python SDK.

```APIDOC
## Bookings API — `client.bookings`

Create and manage appointment bookings, search staff availability, and retrieve team member booking profiles.

### Search available appointment slots
```python
availability = client.bookings.search_availability(
    query={
        "filter": {
            "start_at_range": {
                "start_at": "2024-11-01T08:00:00Z",
                "end_at":   "2024-11-01T18:00:00Z",
            },
            "location_id": "L88917AVBK2S5",
            "segment_filters": [
                {
                    "service_variation_id": "SERVICE_VARIATION_ID",
                    "team_member_id_filter": {"all": ["TEAM_MEMBER_ID"]},
                }
            ],
        }
    }
)
for slot in availability.availabilities or []:
    print(slot.start_at, slot.location_id)
```

### Create a booking
```python
if availability.availabilities:
    slot = availability.availabilities[0]
    response = client.bookings.create(
        booking={
            "start_at": slot.start_at,
            "location_id": slot.location_id,
            "customer_id": "CUSTOMER_ID_ABC",
            "appointment_segments": [
                {
                    "service_variation_id": "SERVICE_VARIATION_ID",
                    "team_member_id": "TEAM_MEMBER_ID",
                    "duration_minutes": 60,
                }
            ],
        },
        idempotency_key=str(uuid.uuid4()),
    )
    booking = response.booking
    print(f"Booking {booking.id}, status={booking.status}")
```

### List bookings for a customer
```python
for b in client.bookings.list(customer_id="CUSTOMER_ID_ABC"):
    print(b.id, b.start_at, b.status)
```

### Cancel a booking
```python
client.bookings.cancel(
    booking_id=booking.id,
    booking_version=booking.version,
)
```
```

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

### Client Initialization

Source: https://context7.com/square/square-python-sdk/llms.txt

Demonstrates how to initialize synchronous and asynchronous Square clients, including options for environment, API version, and custom timeouts.

```APIDOC
## Client Initialization

Instantiate `Square` (sync) or `AsyncSquare` (async). The access token is read from the `SQUARE_TOKEN` environment variable by default.

```python
import os
from square import Square, AsyncSquare
from square.environment import SquareEnvironment

# Sync client — production (default)
client = Square(token=os.environ.get("SQUARE_TOKEN"))

# Sync client — sandbox environment
sandbox_client = Square(
    token=os.environ.get("SQUARE_SANDBOX_TOKEN"),
    environment=SquareEnvironment.SANDBOX,
)

# Async client
async_client = AsyncSquare(token=os.environ.get("SQUARE_TOKEN"))

# Pin to a specific Square API version
versioned_client = Square(
    token=os.environ.get("SQUARE_TOKEN"),
    version="2025-03-19",
)

# Custom timeout (seconds) and max retries
from square.core.request_options import RequestOptions

client = Square(token=os.environ.get("SQUARE_TOKEN"), timeout=30.0)
```
```

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

### TeamMembers WageSetting Get

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

Retrieves a WageSetting object for a team member specified by TeamMember.id. Square recommends using RetrieveTeamMember or SearchTeamMembers to get this information directly from the TeamMember.wage_setting field.

```APIDOC
## TeamMembers WageSetting Get

### Description
Retrieves a `WageSetting` object for a team member specified by `TeamMember.id`. For more information, see [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#retrievewagesetting).

Square recommends using [RetrieveTeamMember](api-endpoint:Team-RetrieveTeamMember) or [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers) to get this information directly from the `TeamMember.wage_setting` field.

### Method
GET

### Endpoint
/team_members/wage_setting

### Parameters
#### Query Parameters
- **team_member_id** (str) - Required - The ID of the team member for which to retrieve the wage setting.
- **request_options** (Optional[RequestOptions]) - Optional - Request-specific configuration.

### Response
#### Success Response (200)
- **wage_setting** (GetWageSettingResponse) - Description of the wage setting.

### Request Example
```python
client.team_members.wage_setting.get(
    team_member_id="team_member_id",
)
```
```

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

### Create Order - Python

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

Use this to create a new order with line items, taxes, and discounts. Ensure you provide a unique idempotency key for each order creation request.

```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",
)
```

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

### client.subscriptions.create

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

Enrolls a customer in a subscription. This method can either charge a card on file or send an invoice to the customer's email address. The subscription starts immediately unless a `start_date` is specified. Each subscription is linked to a specific location.

```APIDOC
## client.subscriptions.create

### Description
Enrolls a customer in a subscription. If a card on file is provided, Square charges it. Otherwise, an invoice is sent to the customer's email. The subscription starts immediately unless `start_date` is specified. Each subscription is associated with a particular location.

### Method
POST (inferred from SDK method)

### Endpoint
/v2/subscriptions (inferred from SDK context)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **idempotency_key** (str) - Required - A unique string that identifies this `CreateSubscription` request.
- **location_id** (str) - Required - The ID of the location where the subscription is being created.
- **plan_variation_id** (str) - Required - The ID of the subscription plan variation to enroll the customer in.
- **customer_id** (str) - Required - The ID of the customer to enroll in the subscription.
- **start_date** (str) - Optional - The date when the first billing cycle should start. If not specified, the subscription starts immediately.
- **card_id** (str) - Optional - The ID of the card on file to use for charging the subscription.
- **timezone** (str) - Optional - The timezone of the location associated with the subscription (e.g., "America/Los_Angeles").
- **source** (dict) - Optional - Information about the source of the subscription request.
  - **name** (str) - Required - The name of the application or service that created the subscription.
- **phases** (list) - Optional - A list of subscription phases, defining recurring billing cycles.
  - **ordinal** (int) - Required - The order of the phase in the subscription.
  - **order_template_id** (str) - Required - The ID of the order template for this phase.

### Request Example
```python
{
  "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)
- **subscription** (object) - Details of the created subscription.

#### Response Example
```json
{
  "subscription": {
    "id": "sub_example_id",
    "name": "Example Subscription",
    "version": 1,
    "location_id": "S8GWD5R9QB376",
    "plan_variation_id": "6JHXF3B2CW3YKHDV4XEM674H",
    "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G",
    "start_date": "2023-06-20",
    "timezone": "America/Los_Angeles",
    "phases": [
      {
        "ordinal": 0,
        "order_template_id": "U2NaowWxzXwpsZU697x7ZHOAnCNZY",
        "periods": [
          {
            "start_date_time": "2023-06-20T00:00:00Z",
            "end_date_time": "2023-07-20T00:00:00Z"
          }
        ]
      }
    ],
    "created_at": "2023-06-15T10:00:00Z",
    "updated_at": "2023-06-15T10:00:00Z"
  }
}
```
```

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

### Get Location Details with Square Python SDK

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

Retrieves details for a specific location using its ID. Use 'main' to get the main location. Requires the Square SDK to be initialized with a token.

```python
from square import Square

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

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

### 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
/checkout/payment-links/{id}

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

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

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

#### Response Example
```json
{
  "payment_link": {
    "id": "plink_abc123",
    "url": "https://square.link/u/xyz789",
    "description": "Auto Detailing Service",
    "order_id": "order_12345",
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-01T12:05:00Z"
  }
}
```
```

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

### Initialize and Use Synchronous Client

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

Instantiate the synchronous Square client and make a payment. The access token is typically loaded from environment variables.

```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"
)
```

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

### Initialize Square Client

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

Instantiate the Square client with your access token. This is the primary step before making any API calls.

```python
from square import Square

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

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

### Start a Transfer Order

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

Changes a DRAFT transfer order to STARTED status, decrementing inventory at the source location. The order must be in DRAFT status and fully populated. This action creates a transfer_order.updated webhook event.

```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 Customer

Source: https://context7.com/square/square-python-sdk/llms.txt

Creates a new customer profile with contact details, address, and other optional information. Requires an idempotency key.

```python
import uuid
from square import Square

client = Square(token="YOUR_TOKEN")

response = client.customers.create(
    idempotency_key=str(uuid.uuid4()),
    given_name="Jane",
    family_name="Doe",
    email_address="jane.doe@example.com",
    phone_number="+12065551234",
    address={
        "address_line1": "500 Electric Ave",
        "locality": "New York",
        "administrative_district_level1": "NY",
        "postal_code": "10003",
        "country": "US",
    },
    reference_id="external-crm-456",
    note="VIP customer",
)
customer = response.customer
print(f"Customer {customer.id}: {customer.given_name} {customer.family_name}")
```

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

### Create Scheduled Shift

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

Creates a scheduled shift by providing draft shift details, including job ID, team member assignment, and start and end times. Requires location ID, job ID, start at, and end at.

```APIDOC
## Create Scheduled Shift

### Description
Creates a scheduled shift by providing draft shift details such as job ID, team member assignment, and start and end times. The following `draft_shift_details` fields are required: `location_id`, `job_id`, `start_at`, `end_at`.

### Method
POST

### Endpoint
/v2/labor/scheduled-shifts

### Parameters
#### Request Body
- **scheduled_shift** (ScheduledShiftParams) - Required - The scheduled shift with `draft_shift_details`. The `start_at` and `end_at` timestamps must be provided in the time zone + offset of the shift location specified in `location_id`.
- **idempotency_key** (str) - Optional - A unique identifier for the `CreateScheduledShift` request, used to ensure the idempotency of the operation.
- **request_options** (RequestOptions) - Optional - Request-specific configuration.

### Request Example
```python
client.labor.create_scheduled_shift(
    idempotency_key="HIDSNG5KS478L",
    scheduled_shift={
        "draft_shift_details": {
            "team_member_id": "ormj0jJJZ5OZIzxrZYJI",
            "location_id": "PAA1RJZZKXBFG",
            "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M",
            "start_at": "2019-01-25T03:11:00-05:00",
            "end_at": "2019-01-25T13:11:00-05:00",
            "notes": "Dont forget to prep the vegetables",
            "is_deleted": False,
        }
    },
)
```

### Response
#### Success Response (200)
- **scheduled_shift** (ScheduledShift) - The created scheduled shift.

#### Response Example
{
  "scheduled_shift": {
    "id": "ss_abcdef123",
    "version": 1,
    "draft_shift_details": {
      "team_member_id": "ormj0jJJZ5OZIzxrZYJI",
      "location_id": "PAA1RJZZKXBFG",
      "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M",
      "start_at": "2019-01-25T03:11:00-05:00",
      "end_at": "2019-01-25T13:11:00-05:00"
    }
  }
}
```

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

### get

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

Retrieves a specific webhook subscription by its ID.

```APIDOC
## get

### Description
Retrieves a webhook subscription identified by its ID.

### Method
GET

### Endpoint
/v2/webhooks/subscriptions/{subscription_id}

### Parameters
#### Path Parameters
- **subscription_id** (string) - Required - The ID of the [Subscription](entity:WebhookSubscription) to retrieve.

### Request Example
```python
client.webhooks.subscriptions.get(
    subscription_id="subscription_id",
)
```

### Response
#### Success Response (200)
- **subscription** (WebhookSubscription) - The requested webhook subscription.

#### Response Example
```json
{
  "subscription": {
    "id": "sub_id",
    "name": "Example Subscription",
    "event_types": ["payment.created"],
    "notification_url": "https://example.com/webhook",
    "api_version": "2021-12-15",
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-01T12:00:00Z",
    "status": "ACTIVE"
  }
}
```
```

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

### Create Checkout

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

Example of how to create a checkout for a given location using the Square Python SDK. This includes defining order details, taxes, discounts, and shipping information.

```APIDOC
## POST /locations/{location_id}/checkouts

### Description
Creates a checkout for a specific location, allowing customers to complete a purchase. This method supports pre-populating buyer information and shipping addresses, as well as handling taxes and discounts.

### Method
POST

### Endpoint
/locations/{location_id}/checkouts

### Parameters
#### Path Parameters
- **location_id** (string) - Required - The ID of the location where the checkout is being created.

#### Query Parameters
- **idempotency_key** (string) - Required - A unique key to ensure idempotency of the request.
- **ask_for_shipping_address** (boolean) - Optional - Whether to ask the buyer for their shipping address.
- **merchant_support_email** (string) - Optional - The email address for merchant support.
- **pre_populate_buyer_email** (string) - Optional - The buyer's email address to pre-populate.
- **pre_populate_shipping_address** (object) - Optional - Shipping address details to pre-populate.
- **redirect_url** (string) - Optional - The URL to redirect the buyer to after the order is confirmed.

#### Request Body
- **order** (object) - Required - The order details, including location, reference ID, customer ID, line items, taxes, and discounts.
  - **order.location_id** (string) - Required - The ID of the location for the order.
  - **order.reference_id** (string) - Optional - A unique ID for the order.
  - **order.customer_id** (string) - Optional - The ID of the customer associated with the order.
  - **order.line_items** (array) - Required - A list of items in the order.
    - **line_items[].name** (string) - Required - The name of the item.
    - **line_items[].quantity** (string) - Required - The quantity of the item.
    - **line_items[].applied_taxes** (array) - Optional - Taxes applied to the line item.
    - **line_items[].applied_discounts** (array) - Optional - Discounts applied to the line item.
    - **line_items[].base_price_money** (object) - Required - The base price of the item.
      - **base_price_money.amount** (integer) - Required - The monetary amount.
      - **base_price_money.currency** (string) - Required - The currency of the amount (e.g., USD).
  - **order.taxes** (array) - Optional - A list of taxes applicable to the order.
    - **taxes[].uid** (string) - Required - Unique ID for the tax.
    - **taxes[].type** (string) - Required - Type of tax (e.g., INCLUSIVE).
    - **taxes[].percentage** (string) - Optional - Tax percentage.
    - **taxes[].scope** (string) - Required - Scope of the tax (e.g., LINE_ITEM).
  - **order.discounts** (array) - Optional - A list of discounts applicable to the order.
    - **discounts[].uid** (string) - Required - Unique ID for the discount.
    - **discounts[].type** (string) - Required - Type of discount (e.g., FIXED_AMOUNT).
    - **discounts[].amount_money** (object) - Optional - The amount of the discount.
      - **amount_money.amount** (integer) - Required - The monetary amount.
      - **amount_money.currency** (string) - Required - The currency of the amount (e.g., USD).
    - **discounts[].scope** (string) - Required - Scope of the discount (e.g., LINE_ITEM).
- **idempotency_key** (string) - Required - A unique key to ensure idempotency of the request.
- **additional_recipients** (array) - Optional - A list of additional recipients for the transaction.
  - **additional_recipients[].location_id** (string) - Required - The ID of the recipient location.
  - **additional_recipients[].description** (string) - Required - Description of the additional recipient.
  - **additional_recipients[].amount_money** (object) - Required - The amount of money to be transferred.
    - **amount_money.amount** (integer) - Required - The monetary amount.
    - **amount_money.currency** (string) - Required - The currency of the amount (e.g., USD).

### Request Example
```python
{
  "order": {
    "location_id": "location_id",
    "reference_id": "reference_id",
    "customer_id": "customer_id",
    "line_items": [
      {
        "name": "Printed T Shirt",
        "quantity": "2",
        "applied_taxes": [
          {"tax_uid": "38ze1696-z1e3-5628-af6d-f1e04d947fg3"}
        ],
        "applied_discounts": [
          {"discount_uid": "56ae1696-z1e3-9328-af6d-f1e04d947gd4"}
        ],
        "base_price_money": {"amount": 1500, "currency": "USD"}
      },
      {
        "name": "Slim Jeans",
        "quantity": "1",
        "base_price_money": {"amount": 2500, "currency": "USD"}
      },
      {
        "name": "Woven Sweater",
        "quantity": "3",
        "base_price_money": {"amount": 3500, "currency": "USD"}
      }
    ],
    "taxes": [
      {
        "uid": "38ze1696-z1e3-5628-af6d-f1e04d947fg3",
        "type": "INCLUSIVE",
        "percentage": "7.75",
        "scope": "LINE_ITEM"
      }
    ],
    "discounts": [
      {
        "uid": "56ae1696-z1e3-9328-af6d-f1e04d947gd4",
        "type": "FIXED_AMOUNT",
        "amount_money": {"amount": 100, "currency": "USD"},
        "scope": "LINE_ITEM"
      }
    ]
  },
  "idempotency_key": "12ae1696-z1e3-4328-af6d-f1e04d947gd4"
}
```

### Response
#### Success Response (200)
- **checkout** (object) - The created checkout object.
  - **checkout.id** (string) - The unique ID for the checkout.
  - **checkout.order_id** (string) - The ID of the order associated with the checkout.
  - **checkout.long_url** (string) - A long-form URL for the checkout page.
  - **checkout.short_url** (string) - A short-form URL for the checkout page.
  - **checkout.expires_at** (string) - The timestamp when the checkout expires.

#### Response Example
```json
{
  "checkout": {
    "id": "ch_example123",
    "order_id": "order_example456",
    "long_url": "https://square.com/checkout/checkout_id",
    "short_url": "https://square.link/s/short_id",
    "expires_at": "2023-10-27T10:00:00Z"
  }
}
```
```

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

### get

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

Retrieves a specific loyalty account by its ID.

```APIDOC
## GET /loyalty/accounts/{account_id}

### Description
Retrieves a loyalty account.

### Method
GET

### Endpoint
/loyalty/accounts/{account_id}

### Parameters
#### Path Parameters
- **account_id** (str) - Required - The ID of the loyalty account to retrieve.

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

### Response
#### Success Response (200)
- **loyalty_account** (LoyaltyAccount) - The loyalty account details.
- **errors** (list[Error]) - Information about errors encountered during the request.
```

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

### Create Payment Link with Quick Pay - Python

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

Use this method to create a Square-hosted checkout page for an ad hoc item and price. Ensure you provide a unique idempotency key for each request. The `quick_pay` parameter requires the item's name, price, 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",
    },
)
```

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

### Create Checkout with Square Python SDK

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

Use this snippet to create a new checkout session. Ensure you replace placeholder values like YOUR_TOKEN, location_id, and reference_id with your actual credentials and identifiers. This example includes detailed order information, taxes, discounts, and pre-populates buyer and shipping details.

```python
from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.checkouts(
    location_id="location_id",
    idempotency_key="86ae1696-b1e3-4328-af6d-f1e04d947ad6",
    order={
        "order": {
            "location_id": "location_id",
            "reference_id": "reference_id",
            "customer_id": "customer_id",
            "line_items": [
                {
                    "name": "Printed T Shirt",
                    "quantity": "2",
                    "applied_taxes": [
                        {"tax_uid": "38ze1696-z1e3-5628-af6d-f1e04d947fg3"}
                    ],
                    "applied_discounts": [
                        {"discount_uid": "56ae1696-z1e3-9328-af6d-f1e04d947gd4"}
                    ],
                    "base_price_money": {"amount": 1500, "currency": "USD"},
                },
                {
                    "name": "Slim Jeans",
                    "quantity": "1",
                    "base_price_money": {"amount": 2500, "currency": "USD"},
                },
                {
                    "name": "Woven Sweater",
                    "quantity": "3",
                    "base_price_money": {"amount": 3500, "currency": "USD"},
                },
            ],
            "taxes": [
                {
                    "uid": "38ze1696-z1e3-5628-af6d-f1e04d947fg3",
                    "type": "INCLUSIVE",
                    "percentage": "7.75",
                    "scope": "LINE_ITEM",
                }
            ],
            "discounts": [
                {
                    "uid": "56ae1696-z1e3-9328-af6d-f1e04d947gd4",
                    "type": "FIXED_AMOUNT",
                    "amount_money": {"amount": 100, "currency": "USD"},
                    "scope": "LINE_ITEM",
                }
            ],
        },
        "idempotency_key": "12ae1696-z1e3-4328-af6d-f1e04d947gd4",
    },
    ask_for_shipping_address=True,
    merchant_support_email="merchant+support@website.com",
    pre_populate_buyer_email="example@email.com",
    pre_populate_shipping_address={
        "address_line1": "1455 Market St.",
        "address_line2": "Suite 600",
        "locality": "San Francisco",
        "administrative_district_level1": "CA",
        "postal_code": "94103",
        "country": "US",
        "first_name": "Jane",
        "last_name": "Doe",
    },
    redirect_url="https://merchant.website.com/order-confirm",
    additional_recipients=[
        {
            "location_id": "057P5VYJ4A5X1",
            "description": "Application fees",
            "amount_money": {"amount": 60, "currency": "USD"},
        }
    ],
)

```

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

### client.bookings.custom_attribute_definitions.list

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

Get all bookings custom attribute definitions.

```APIDOC
## GET /bookings/custom-attribute-definitions

### Description
Get all bookings custom attribute definitions.
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
/v2/bookings/custom-attribute-definitions

### Parameters
#### Query Parameters
- **limit** (int) - Optional - The maximum number of results to return in a single page.
- **cursor** (str) - 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.

### Response
#### Success Response (200)
- **custom_attribute_definitions** (list[CustomAttributeDefinition]) - A list of custom attribute definitions.
- **errors** (list[Error]) - Information about errors encountered.
```

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

### Get Device

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

Retrieves a Device with the associated `device_id`.

```APIDOC
## Get Device

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

### Method
GET

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

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

### Response
#### Success Response (200)
- **device** (Device) - The retrieved device.

#### Response Example
```json
{
  "device": {
    "id": "device_id",
    "type": "TERMINAL_API",
    "location_id": "location_id"
  }
}
```
```

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

### Create and Manage Timecards

Source: https://context7.com/square/square-python-sdk/llms.txt

Demonstrates clocking in by creating a timecard, clocking out by updating the timecard with an end time, and searching for timecards within a specified period.

```python
import uuid
from square import Square

client = Square(token="YOUR_TOKEN")

# --- Create a timecard (clock in) ---
response = client.labor.create_timecard(
    timecard={
        "location_id": "L88917AVBK2S5",
        "team_member_id": "TEAM_MEMBER_ID",
        "start_at": "2024-11-01T09:00:00-07:00",
    },
    idempotency_key=str(uuid.uuid4()),
)
timecard = response.timecard
print(f"Timecard {timecard.id}, started at {timecard.start_at}")

# --- Clock out (update end_at) ---
client.labor.update_timecard(
    timecard_id=timecard.id,
    timecard={
        "location_id": "L88917AVBK2S5",
        "team_member_id": "TEAM_MEMBER_ID",
        "start_at": timecard.start_at,
        "end_at": "2024-11-01T17:00:00-07:00",
        "version": timecard.version,
    },
    idempotency_key=str(uuid.uuid4()),
)

# --- Search timecards ---
search = client.labor.search_timecards(
    query={
        "filter": {
            "location_ids": ["L88917AVBK2S5"],
            "team_member_ids": ["TEAM_MEMBER_ID"],
            "start": {"start_at": "2024-11-01T00:00:00Z"},
        }
    }
)
for tc in search.timecards or []:
    print(tc.id, tc.start_at, tc.end_at)
```

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

### Get Shift

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

Returns a single Shift specified by its ID.

```APIDOC
## Get Shift

### Description
Returns a single `Shift` specified by `id`.

### Method
GET

### Endpoint
/shifts/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - The UUID for the `Shift` being retrieved.

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

### Response
#### Success Response (200)
- **shift** (Shift) - A `Shift` object.

#### Response Example
```json
{
  "shift": {
    "id": "string",
    "employee_id": "string",
    "shift_state": "OPEN",
    "start_at": "2022-01-25T03:11:00-05:00",
    "end_at": "2022-01-25T13:11:00-05:00",
    "timezone": "America/Los_Angeles",
    "wage": {
      "title": "Bartender",
      "hourly_rate": {
        "amount": 1500,
        "currency": "USD"
      }
    },
    "breaks": [
      {
        "id": "string",
        "start_at": "2022-01-25T06:11:00-05:00",
        "end_at": "2022-01-25T06:16:00-05:00",
        "break_type_id": "string",
        "is_paid": true
      }
    ],
    "version": 1,
    "created_at": "2022-01-25T03:11:00-05:00",
    "updated_at": "2022-01-25T03:11:00-05:00",
    "team_member_id": "string",
    "location_id": "string",
    "idempotency_key": "string"
  }
}
```
```

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

### Create an Order

Source: https://context7.com/square/square-python-sdk/llms.txt

Creates a new order with specified location, reference ID, line items, taxes, and discounts. Requires an idempotency key.

```python
import uuid
from square import Square

client = Square(token="YOUR_TOKEN")

response = client.orders.create(
    order={
        "location_id": "L88917AVBK2S5",
        "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-tax", "name": "State Sales Tax", "percentage": "9", "scope": "ORDER"}
        ],
        "discounts": [
            {"uid": "one-dollar-off", "name": "Sale - $1.00 off",
             "amount_money": {"amount": 100, "currency": "USD"}, "scope": "LINE_ITEM"},
        ],
    },
    idempotency_key=str(uuid.uuid4()),
)
order = response.order
print(f"Order {order.id}, total={order.total_money}")
```

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

### Refunds Get

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

Retrieves a specific refund using the refund_id.

```APIDOC
## Refunds Get

### Description
Retrieves a specific refund using the `refund_id`.

### Method
GET (assumed based on SDK method name)

### Endpoint
`/v2/refunds/{refund_id}` (inferred)

### Parameters
#### Path Parameters
- **refund_id** (str) - Required - The unique ID for the desired `PaymentRefund`.

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

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

client = Square(
    token="YOUR_TOKEN",
)
client.refunds.get(
    refund_id="refund_id",
)
```

### Response
#### Success Response (200)
- **refund** (Refund) - Details of the retrieved refund.
```

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

### Use Legacy and New SDKs Together in Python

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

Instantiate both the new Square SDK client and the legacy Square SDK client within the same Python file. Replace `<YOUR_API_KEY>` with your actual Square 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

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

Retrieves a specific order by its unique ID.

```APIDOC
## GET /orders/{order_id}

### Description
Retrieves a specific order by its unique ID.

### Method
GET

### Endpoint
/orders/{order_id}

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

### Request Example
```python
client.orders.get(
    order_id="order_id",
)
```

### Response
#### Success Response (200)
- **GetOrderResponse** - Contains the details of the requested order.
```

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

### Get Transfer

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

Returns the InventoryTransfer object with the provided transfer_id.

```APIDOC
## GET TRANSFER

### Description
Returns the [InventoryTransfer](entity:InventoryTransfer) object with the provided `transfer_id`.

### Method
GET

### Endpoint
/v2/inventory/transfers/{transfer_id}

### Parameters
#### Path Parameters
- **transfer_id** (str) - Required - ID of the [InventoryTransfer](entity:InventoryTransfer) to retrieve.

#### Request Body
None

### Response
#### Success Response (200)
- **transfer** (InventoryTransfer) - Description of the transfer object.

### Response Example
{
  "transfer": {
    "id": "string",
    "reference_id": "string",
    "from_location_id": "string",
    "to_location_id": "string",
    "catalog_object_id": "string",
    "catalog_object_type": "string",
    "state": "string",
    "quantity": "string",
    "created_at": "string",
    "updated_at": "string",
    "expected_at": "string",
    "shipped_at": "string",
    "delivered_at": "string",
    "cancelled_at": "string",
    "from_state": "string",
    "to_state": "string",
    "team_member_id": "string",
    "product_type": "string",
    "type": "string"
  }
}
```

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

### Create and Manage Bookings

Source: https://context7.com/square/square-python-sdk/llms.txt

Creates a booking based on an available slot, lists bookings for a customer, and cancels a booking. Requires an active client and availability search results.

```python
import uuid
from square import Square

client = Square(token="YOUR_TOKEN")

# --- Create a booking ---
if availability.availabilities:
    slot = availability.availabilities[0]
    response = client.bookings.create(
        booking={
            "start_at": slot.start_at,
            "location_id": slot.location_id,
            "customer_id": "CUSTOMER_ID_ABC",
            "appointment_segments": [
                {
                    "service_variation_id": "SERVICE_VARIATION_ID",
                    "team_member_id": "TEAM_MEMBER_ID",
                    "duration_minutes": 60,
                }
            ],
        },
        idempotency_key=str(uuid.uuid4()),
    )
    booking = response.booking
    print(f"Booking {booking.id}, status={booking.status}")

# --- List bookings for a customer ---
for b in client.bookings.list(customer_id="CUSTOMER_ID_ABC"):
    print(b.id, b.start_at, b.status)

# --- Cancel a booking ---
client.bookings.cancel(
    booking_id=booking.id,
    booking_version=booking.version,
)
```

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

### Create, Activate, and Manage Gift Cards

Source: https://context7.com/square/square-python-sdk/llms.txt

Demonstrates creating a new digital gift card, activating it with a specific amount, linking it to a customer, retrieving it by its GAN, and listing active gift cards.

```python
import uuid
from square import Square

client = Square(token="YOUR_TOKEN")

# --- Create a new gift card ---
response = client.gift_cards.create(
    idempotency_key=str(uuid.uuid4()),
    location_id="L88917AVBK2S5",
    gift_card={"type": "DIGITAL"},
)
card = response.gift_card
print(f"Gift card {card.id}, GAN={card.gan}, balance={card.balance_money}")

# --- Load (activate) a gift card ---
client.gift_cards.activities.create(
    idempotency_key=str(uuid.uuid4()),
    activity={
        "type": "ACTIVATE",
        "location_id": "L88917AVBK2S5",
        "gift_card_id": card.id,
        "activate_activity_details": {
            "amount_money": {"amount": 5000, "currency": "USD"},  # $50.00
            "order_id": "ORDER_ID_ABC",
        },
    },
)

# --- Link gift card to a customer ---
client.gift_cards.link_customer(
    gift_card_id=card.id,
    customer_id="CUSTOMER_ID_ABC",
)

# --- Retrieve by GAN (gift card account number) ---
result = client.gift_cards.get_from_gan(gan=card.gan)
print(result.gift_card.balance_money)

# --- List gift cards ---
for gc in client.gift_cards.list(state="ACTIVE", customer_id="CUSTOMER_ID_ABC"):
    print(gc.id, gc.balance_money)
```