# Square (/integrations/square)

Use cases and templates: [Square integration for AI agents](https://www.sim.ai/integrations/square)





<BlockInfoCard type="square" color="#000000" />

{/* MANUAL-CONTENT-START:intro */}

Use [Square](https://squareup.com/) to take, retrieve, list, cancel, complete, or refund payments; manage customer profiles; create, retrieve, search, or pay for orders; and create, publish, cancel, or delete invoices.

The actions also manage catalog objects and images, read inventory counts, and look up locations. Configure a Square access token and the target environment. Payment and refund actions change live commerce records; use the correct environment and the action's idempotency fields before running them.

{/* MANUAL-CONTENT-END */}

## Use the block [#usage-instructions]

Take and refund payments, manage customers, build catalog items and images, create and search orders, and issue invoices. Authenticate with a Square access token (personal access token).

## Actions [#actions]

### Square Create Payment [#square-create-payment]

Take a payment using a payment source such as a card nonce or a card on file

#### Input [#input]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `sourceId` | string | Yes | ID of the payment source (card nonce, card-on-file ID, or wallet token) |
| `amount` | number | Yes | Amount in the smallest currency denomination (e.g. 1000 = $10.00) |
| `currency` | string | Yes | Three-letter ISO 4217 currency code (e.g. USD) |
| `idempotencyKey` | string | No | Unique key to make the request idempotent (auto-generated if omitted) |
| `customerId` | string | No | ID of the customer associated with the payment |
| `locationId` | string | No | ID of the location where the payment is taken (defaults to the main location) |
| `orderId` | string | No | ID of the order associated with the payment |
| `referenceId` | string | No | Optional external reference for the payment |
| `note` | string | No | Optional note attached to the payment |
| `autocomplete` | boolean | No | Whether to immediately capture the payment (defaults to true) |

#### Output [#output]

| Parameter | Type | Description |
| - | - | - |
| `payment` | object | Square Payment object |
| ↳ `id` | string | Unique ID for the payment |
| ↳ `status` | string | Payment status (APPROVED, PENDING, COMPLETED, CANCELED, or FAILED) |
| ↳ `amount_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `total_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `approved_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `app_fee_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `refunded_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `tip_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `source_type` | string | Source of the payment (CARD, BANK\_ACCOUNT, WALLET, etc.) |
| ↳ `card_details` | json | Details about a card payment |
| ↳ `location_id` | string | ID of the location where the payment was taken |
| ↳ `order_id` | string | ID of the associated order |
| ↳ `customer_id` | string | ID of the associated customer |
| ↳ `reference_id` | string | Optional external reference for the payment |
| ↳ `receipt_number` | string | Receipt number for the payment |
| ↳ `receipt_url` | string | URL of the payment receipt |
| ↳ `note` | string | Optional note attached to the payment |
| ↳ `refund_ids` | array | IDs of refunds associated with the payment |
| ↳ `processing_fee` | array | Processing fees applied to the payment |
| ↳ `created_at` | string | Timestamp when the payment was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the payment was last updated (RFC 3339) |
| ↳ `version_token` | string | Optimistic concurrency token for the payment |
| `metadata` | json | Payment summary metadata |
| ↳ `id` | string | Square payment ID |
| ↳ `status` | string | Current payment status |
| ↳ `order_id` | string | Associated order ID |

### Square Get Payment [#square-get-payment]

Retrieve details for a single payment by its ID

#### Input [#input-1]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `paymentId` | string | Yes | ID of the payment to retrieve |

#### Output [#output-1]

| Parameter | Type | Description |
| - | - | - |
| `payment` | object | Square Payment object |
| ↳ `id` | string | Unique ID for the payment |
| ↳ `status` | string | Payment status (APPROVED, PENDING, COMPLETED, CANCELED, or FAILED) |
| ↳ `amount_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `total_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `approved_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `app_fee_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `refunded_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `tip_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `source_type` | string | Source of the payment (CARD, BANK\_ACCOUNT, WALLET, etc.) |
| ↳ `card_details` | json | Details about a card payment |
| ↳ `location_id` | string | ID of the location where the payment was taken |
| ↳ `order_id` | string | ID of the associated order |
| ↳ `customer_id` | string | ID of the associated customer |
| ↳ `reference_id` | string | Optional external reference for the payment |
| ↳ `receipt_number` | string | Receipt number for the payment |
| ↳ `receipt_url` | string | URL of the payment receipt |
| ↳ `note` | string | Optional note attached to the payment |
| ↳ `refund_ids` | array | IDs of refunds associated with the payment |
| ↳ `processing_fee` | array | Processing fees applied to the payment |
| ↳ `created_at` | string | Timestamp when the payment was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the payment was last updated (RFC 3339) |
| ↳ `version_token` | string | Optimistic concurrency token for the payment |
| `metadata` | json | Payment summary metadata |
| ↳ `id` | string | Square payment ID |
| ↳ `status` | string | Current payment status |
| ↳ `order_id` | string | Associated order ID |

### Square List Payments [#square-list-payments]

List payments taken by the account, optionally filtered by location and time range

#### Input [#input-2]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `locationId` | string | No | Filter payments by location ID |
| `beginTime` | string | No | RFC 3339 timestamp for the beginning of the reporting period |
| `endTime` | string | No | RFC 3339 timestamp for the end of the reporting period |
| `limit` | number | No | Maximum number of results to return per page |
| `cursor` | string | No | Pagination cursor from a previous response |

#### Output [#output-2]

| Parameter | Type | Description |
| - | - | - |
| `payments` | array | Array of payment objects |
| ↳ `id` | string | Unique ID for the payment |
| ↳ `status` | string | Payment status (APPROVED, PENDING, COMPLETED, CANCELED, or FAILED) |
| ↳ `amount_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `total_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `approved_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `app_fee_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `refunded_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `tip_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `source_type` | string | Source of the payment (CARD, BANK\_ACCOUNT, WALLET, etc.) |
| ↳ `card_details` | json | Details about a card payment |
| ↳ `location_id` | string | ID of the location where the payment was taken |
| ↳ `order_id` | string | ID of the associated order |
| ↳ `customer_id` | string | ID of the associated customer |
| ↳ `reference_id` | string | Optional external reference for the payment |
| ↳ `receipt_number` | string | Receipt number for the payment |
| ↳ `receipt_url` | string | URL of the payment receipt |
| ↳ `note` | string | Optional note attached to the payment |
| ↳ `refund_ids` | array | IDs of refunds associated with the payment |
| ↳ `processing_fee` | array | Processing fees applied to the payment |
| ↳ `created_at` | string | Timestamp when the payment was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the payment was last updated (RFC 3339) |
| ↳ `version_token` | string | Optimistic concurrency token for the payment |
| `metadata` | json | List pagination metadata |
| ↳ `count` | number | Number of items returned in this page |
| ↳ `cursor` | string | Pagination cursor to fetch the next page, if more results exist |

### Square Cancel Payment [#square-cancel-payment]

Cancel (void) an authorized payment that has not been captured

#### Input [#input-3]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `paymentId` | string | Yes | ID of the payment to cancel |

#### Output [#output-3]

| Parameter | Type | Description |
| - | - | - |
| `payment` | object | Square Payment object |
| ↳ `id` | string | Unique ID for the payment |
| ↳ `status` | string | Payment status (APPROVED, PENDING, COMPLETED, CANCELED, or FAILED) |
| ↳ `amount_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `total_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `approved_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `app_fee_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `refunded_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `tip_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `source_type` | string | Source of the payment (CARD, BANK\_ACCOUNT, WALLET, etc.) |
| ↳ `card_details` | json | Details about a card payment |
| ↳ `location_id` | string | ID of the location where the payment was taken |
| ↳ `order_id` | string | ID of the associated order |
| ↳ `customer_id` | string | ID of the associated customer |
| ↳ `reference_id` | string | Optional external reference for the payment |
| ↳ `receipt_number` | string | Receipt number for the payment |
| ↳ `receipt_url` | string | URL of the payment receipt |
| ↳ `note` | string | Optional note attached to the payment |
| ↳ `refund_ids` | array | IDs of refunds associated with the payment |
| ↳ `processing_fee` | array | Processing fees applied to the payment |
| ↳ `created_at` | string | Timestamp when the payment was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the payment was last updated (RFC 3339) |
| ↳ `version_token` | string | Optimistic concurrency token for the payment |
| `metadata` | json | Payment summary metadata |
| ↳ `id` | string | Square payment ID |
| ↳ `status` | string | Current payment status |
| ↳ `order_id` | string | Associated order ID |

### Square Complete Payment [#square-complete-payment]

Capture (complete) a payment that was authorized with delayed capture

#### Input [#input-4]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `paymentId` | string | Yes | ID of the payment to complete |
| `versionToken` | string | No | Optional version token for optimistic concurrency control |

#### Output [#output-4]

| Parameter | Type | Description |
| - | - | - |
| `payment` | object | Square Payment object |
| ↳ `id` | string | Unique ID for the payment |
| ↳ `status` | string | Payment status (APPROVED, PENDING, COMPLETED, CANCELED, or FAILED) |
| ↳ `amount_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `total_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `approved_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `app_fee_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `refunded_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `tip_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `source_type` | string | Source of the payment (CARD, BANK\_ACCOUNT, WALLET, etc.) |
| ↳ `card_details` | json | Details about a card payment |
| ↳ `location_id` | string | ID of the location where the payment was taken |
| ↳ `order_id` | string | ID of the associated order |
| ↳ `customer_id` | string | ID of the associated customer |
| ↳ `reference_id` | string | Optional external reference for the payment |
| ↳ `receipt_number` | string | Receipt number for the payment |
| ↳ `receipt_url` | string | URL of the payment receipt |
| ↳ `note` | string | Optional note attached to the payment |
| ↳ `refund_ids` | array | IDs of refunds associated with the payment |
| ↳ `processing_fee` | array | Processing fees applied to the payment |
| ↳ `created_at` | string | Timestamp when the payment was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the payment was last updated (RFC 3339) |
| ↳ `version_token` | string | Optimistic concurrency token for the payment |
| `metadata` | json | Payment summary metadata |
| ↳ `id` | string | Square payment ID |
| ↳ `status` | string | Current payment status |
| ↳ `order_id` | string | Associated order ID |

### Square Refund Payment [#square-refund-payment]

Refund all or part of a completed payment

#### Input [#input-5]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `paymentId` | string | Yes | ID of the payment to refund |
| `amount` | number | Yes | Amount to refund in the smallest currency denomination (e.g. 100 = $1.00) |
| `currency` | string | Yes | Three-letter ISO 4217 currency code (e.g. USD) |
| `idempotencyKey` | string | No | Unique key to make the request idempotent (auto-generated if omitted) |
| `reason` | string | No | Reason for the refund |

#### Output [#output-5]

| Parameter | Type | Description |
| - | - | - |
| `refund` | object | Square PaymentRefund object |
| ↳ `id` | string | Unique ID for the refund |
| ↳ `status` | string | Refund status (PENDING, COMPLETED, REJECTED, or FAILED) |
| ↳ `amount_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `processing_fee` | array | Processing fees refunded |
| ↳ `payment_id` | string | ID of the payment being refunded |
| ↳ `order_id` | string | ID of the associated order |
| ↳ `location_id` | string | ID of the associated location |
| ↳ `reason` | string | Reason for the refund |
| ↳ `created_at` | string | Timestamp when the refund was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the refund was last updated (RFC 3339) |
| `metadata` | json | Refund summary metadata |
| ↳ `id` | string | Square refund ID |
| ↳ `status` | string | Current refund status |
| ↳ `payment_id` | string | Refunded payment ID |

### Square Get Refund [#square-get-refund]

Retrieve a single payment refund by its ID

#### Input [#input-6]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `refundId` | string | Yes | ID of the refund to retrieve |

#### Output [#output-6]

| Parameter | Type | Description |
| - | - | - |
| `refund` | object | Square PaymentRefund object |
| ↳ `id` | string | Unique ID for the refund |
| ↳ `status` | string | Refund status (PENDING, COMPLETED, REJECTED, or FAILED) |
| ↳ `amount_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `processing_fee` | array | Processing fees refunded |
| ↳ `payment_id` | string | ID of the payment being refunded |
| ↳ `order_id` | string | ID of the associated order |
| ↳ `location_id` | string | ID of the associated location |
| ↳ `reason` | string | Reason for the refund |
| ↳ `created_at` | string | Timestamp when the refund was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the refund was last updated (RFC 3339) |
| `metadata` | json | Refund summary metadata |
| ↳ `id` | string | Square refund ID |
| ↳ `status` | string | Current refund status |
| ↳ `payment_id` | string | Refunded payment ID |

### Square List Refunds [#square-list-refunds]

List payment refunds, optionally filtered by location, status, and time range

#### Input [#input-7]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `locationId` | string | No | Filter refunds by location ID |
| `status` | string | No | Filter by refund status (PENDING, COMPLETED, REJECTED, or FAILED) |
| `beginTime` | string | No | RFC 3339 timestamp for the beginning of the reporting period |
| `endTime` | string | No | RFC 3339 timestamp for the end of the reporting period |
| `limit` | number | No | Maximum number of results to return per page |
| `cursor` | string | No | Pagination cursor from a previous response |

#### Output [#output-7]

| Parameter | Type | Description |
| - | - | - |
| `refunds` | array | Array of refund objects |
| ↳ `id` | string | Unique ID for the refund |
| ↳ `status` | string | Refund status (PENDING, COMPLETED, REJECTED, or FAILED) |
| ↳ `amount_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `processing_fee` | array | Processing fees refunded |
| ↳ `payment_id` | string | ID of the payment being refunded |
| ↳ `order_id` | string | ID of the associated order |
| ↳ `location_id` | string | ID of the associated location |
| ↳ `reason` | string | Reason for the refund |
| ↳ `created_at` | string | Timestamp when the refund was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the refund was last updated (RFC 3339) |
| `metadata` | json | List pagination metadata |
| ↳ `count` | number | Number of items returned in this page |
| ↳ `cursor` | string | Pagination cursor to fetch the next page, if more results exist |

### Square Create Customer [#square-create-customer]

Create a new customer profile in the Square customer directory

#### Input [#input-8]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `givenName` | string | No | First name of the customer |
| `familyName` | string | No | Last name of the customer |
| `companyName` | string | No | Business name of the customer |
| `nickname` | string | No | Nickname of the customer |
| `emailAddress` | string | No | Email address of the customer |
| `phoneNumber` | string | No | Phone number of the customer |
| `birthday` | string | No | Birthday in YYYY-MM-DD or MM-DD format |
| `note` | string | No | Note about the customer |
| `referenceId` | string | No | Optional external reference for the customer |
| `address` | json | No | Square address object for the customer |
| `idempotencyKey` | string | No | Unique key to make the request idempotent (auto-generated if omitted) |

#### Output [#output-8]

| Parameter | Type | Description |
| - | - | - |
| `customer` | object | Square Customer object |
| ↳ `id` | string | Unique ID for the customer |
| ↳ `given_name` | string | First name of the customer |
| ↳ `family_name` | string | Last name of the customer |
| ↳ `nickname` | string | Nickname of the customer |
| ↳ `company_name` | string | Business name of the customer |
| ↳ `email_address` | string | Email address of the customer |
| ↳ `phone_number` | string | Phone number of the customer |
| ↳ `address` | object | Physical address |
| ↳ `address_line_1` | string | First line of the address |
| ↳ `address_line_2` | string | Second line of the address |
| ↳ `address_line_3` | string | Third line of the address |
| ↳ `locality` | string | City or town |
| ↳ `sublocality` | string | Neighborhood or district |
| ↳ `administrative_district_level_1` | string | State, province, or region |
| ↳ `postal_code` | string | Postal or ZIP code |
| ↳ `country` | string | Two-letter ISO 3166-1 alpha-2 country code |
| ↳ `first_name` | string | First name of the addressee |
| ↳ `last_name` | string | Last name of the addressee |
| ↳ `birthday` | string | Birthday in YYYY-MM-DD or MM-DD format |
| ↳ `reference_id` | string | Optional external reference for the customer |
| ↳ `note` | string | Note about the customer |
| ↳ `creation_source` | string | How the customer profile was created |
| ↳ `preferences` | json | Customer communication preferences |
| ↳ `group_ids` | array | IDs of customer groups the customer belongs to |
| ↳ `segment_ids` | array | IDs of customer segments the customer belongs to |
| ↳ `version` | number | Optimistic concurrency version of the customer |
| ↳ `created_at` | string | Timestamp when the customer was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the customer was last updated (RFC 3339) |
| `metadata` | json | Customer summary metadata |
| ↳ `id` | string | Square customer ID |
| ↳ `email_address` | string | Customer email address |
| ↳ `given_name` | string | Customer first name |
| ↳ `family_name` | string | Customer last name |

### Square Get Customer [#square-get-customer]

Retrieve a single customer profile by its ID

#### Input [#input-9]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `customerId` | string | Yes | ID of the customer to retrieve |

#### Output [#output-9]

| Parameter | Type | Description |
| - | - | - |
| `customer` | object | Square Customer object |
| ↳ `id` | string | Unique ID for the customer |
| ↳ `given_name` | string | First name of the customer |
| ↳ `family_name` | string | Last name of the customer |
| ↳ `nickname` | string | Nickname of the customer |
| ↳ `company_name` | string | Business name of the customer |
| ↳ `email_address` | string | Email address of the customer |
| ↳ `phone_number` | string | Phone number of the customer |
| ↳ `address` | object | Physical address |
| ↳ `address_line_1` | string | First line of the address |
| ↳ `address_line_2` | string | Second line of the address |
| ↳ `address_line_3` | string | Third line of the address |
| ↳ `locality` | string | City or town |
| ↳ `sublocality` | string | Neighborhood or district |
| ↳ `administrative_district_level_1` | string | State, province, or region |
| ↳ `postal_code` | string | Postal or ZIP code |
| ↳ `country` | string | Two-letter ISO 3166-1 alpha-2 country code |
| ↳ `first_name` | string | First name of the addressee |
| ↳ `last_name` | string | Last name of the addressee |
| ↳ `birthday` | string | Birthday in YYYY-MM-DD or MM-DD format |
| ↳ `reference_id` | string | Optional external reference for the customer |
| ↳ `note` | string | Note about the customer |
| ↳ `creation_source` | string | How the customer profile was created |
| ↳ `preferences` | json | Customer communication preferences |
| ↳ `group_ids` | array | IDs of customer groups the customer belongs to |
| ↳ `segment_ids` | array | IDs of customer segments the customer belongs to |
| ↳ `version` | number | Optimistic concurrency version of the customer |
| ↳ `created_at` | string | Timestamp when the customer was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the customer was last updated (RFC 3339) |
| `metadata` | json | Customer summary metadata |
| ↳ `id` | string | Square customer ID |
| ↳ `email_address` | string | Customer email address |
| ↳ `given_name` | string | Customer first name |
| ↳ `family_name` | string | Customer last name |

### Square List Customers [#square-list-customers]

List customer profiles in the Square customer directory

#### Input [#input-10]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `limit` | number | No | Maximum number of results to return per page (max 100) |
| `cursor` | string | No | Pagination cursor from a previous response |
| `sortField` | string | No | Field to sort by (DEFAULT or CREATED\_AT) |
| `sortOrder` | string | No | Sort order (ASC or DESC) |

#### Output [#output-10]

| Parameter | Type | Description |
| - | - | - |
| `customers` | array | Array of customer objects |
| ↳ `id` | string | Unique ID for the customer |
| ↳ `given_name` | string | First name of the customer |
| ↳ `family_name` | string | Last name of the customer |
| ↳ `nickname` | string | Nickname of the customer |
| ↳ `company_name` | string | Business name of the customer |
| ↳ `email_address` | string | Email address of the customer |
| ↳ `phone_number` | string | Phone number of the customer |
| ↳ `address` | object | Physical address |
| ↳ `address_line_1` | string | First line of the address |
| ↳ `address_line_2` | string | Second line of the address |
| ↳ `address_line_3` | string | Third line of the address |
| ↳ `locality` | string | City or town |
| ↳ `sublocality` | string | Neighborhood or district |
| ↳ `administrative_district_level_1` | string | State, province, or region |
| ↳ `postal_code` | string | Postal or ZIP code |
| ↳ `country` | string | Two-letter ISO 3166-1 alpha-2 country code |
| ↳ `first_name` | string | First name of the addressee |
| ↳ `last_name` | string | Last name of the addressee |
| ↳ `birthday` | string | Birthday in YYYY-MM-DD or MM-DD format |
| ↳ `reference_id` | string | Optional external reference for the customer |
| ↳ `note` | string | Note about the customer |
| ↳ `creation_source` | string | How the customer profile was created |
| ↳ `preferences` | json | Customer communication preferences |
| ↳ `group_ids` | array | IDs of customer groups the customer belongs to |
| ↳ `segment_ids` | array | IDs of customer segments the customer belongs to |
| ↳ `version` | number | Optimistic concurrency version of the customer |
| ↳ `created_at` | string | Timestamp when the customer was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the customer was last updated (RFC 3339) |
| `metadata` | json | List pagination metadata |
| ↳ `count` | number | Number of items returned in this page |
| ↳ `cursor` | string | Pagination cursor to fetch the next page, if more results exist |

### Square Search Customers [#square-search-customers]

Search customer profiles using filters such as email, phone, or creation date

#### Input [#input-11]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `query` | json | No | Square customer query object with optional filter and sort (e.g. \{"filter":\{"email\_address":\{"exact":"[a@b.com](mailto:a@b.com)"}}}) |
| `limit` | number | No | Maximum number of results to return per page |
| `cursor` | string | No | Pagination cursor from a previous response |

#### Output [#output-11]

| Parameter | Type | Description |
| - | - | - |
| `customers` | array | Array of matching customer objects |
| ↳ `id` | string | Unique ID for the customer |
| ↳ `given_name` | string | First name of the customer |
| ↳ `family_name` | string | Last name of the customer |
| ↳ `nickname` | string | Nickname of the customer |
| ↳ `company_name` | string | Business name of the customer |
| ↳ `email_address` | string | Email address of the customer |
| ↳ `phone_number` | string | Phone number of the customer |
| ↳ `address` | object | Physical address |
| ↳ `address_line_1` | string | First line of the address |
| ↳ `address_line_2` | string | Second line of the address |
| ↳ `address_line_3` | string | Third line of the address |
| ↳ `locality` | string | City or town |
| ↳ `sublocality` | string | Neighborhood or district |
| ↳ `administrative_district_level_1` | string | State, province, or region |
| ↳ `postal_code` | string | Postal or ZIP code |
| ↳ `country` | string | Two-letter ISO 3166-1 alpha-2 country code |
| ↳ `first_name` | string | First name of the addressee |
| ↳ `last_name` | string | Last name of the addressee |
| ↳ `birthday` | string | Birthday in YYYY-MM-DD or MM-DD format |
| ↳ `reference_id` | string | Optional external reference for the customer |
| ↳ `note` | string | Note about the customer |
| ↳ `creation_source` | string | How the customer profile was created |
| ↳ `preferences` | json | Customer communication preferences |
| ↳ `group_ids` | array | IDs of customer groups the customer belongs to |
| ↳ `segment_ids` | array | IDs of customer segments the customer belongs to |
| ↳ `version` | number | Optimistic concurrency version of the customer |
| ↳ `created_at` | string | Timestamp when the customer was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the customer was last updated (RFC 3339) |
| `metadata` | json | List pagination metadata |
| ↳ `count` | number | Number of items returned in this page |
| ↳ `cursor` | string | Pagination cursor to fetch the next page, if more results exist |

### Square Update Customer [#square-update-customer]

Update fields on an existing customer profile

#### Input [#input-12]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `customerId` | string | Yes | ID of the customer to update |
| `givenName` | string | No | First name of the customer |
| `familyName` | string | No | Last name of the customer |
| `companyName` | string | No | Business name of the customer |
| `nickname` | string | No | Nickname of the customer |
| `emailAddress` | string | No | Email address of the customer |
| `phoneNumber` | string | No | Phone number of the customer |
| `birthday` | string | No | Birthday in YYYY-MM-DD or MM-DD format |
| `note` | string | No | Note about the customer |
| `referenceId` | string | No | Optional external reference for the customer |
| `address` | json | No | Square address object for the customer |

#### Output [#output-12]

| Parameter | Type | Description |
| - | - | - |
| `customer` | object | Square Customer object |
| ↳ `id` | string | Unique ID for the customer |
| ↳ `given_name` | string | First name of the customer |
| ↳ `family_name` | string | Last name of the customer |
| ↳ `nickname` | string | Nickname of the customer |
| ↳ `company_name` | string | Business name of the customer |
| ↳ `email_address` | string | Email address of the customer |
| ↳ `phone_number` | string | Phone number of the customer |
| ↳ `address` | object | Physical address |
| ↳ `address_line_1` | string | First line of the address |
| ↳ `address_line_2` | string | Second line of the address |
| ↳ `address_line_3` | string | Third line of the address |
| ↳ `locality` | string | City or town |
| ↳ `sublocality` | string | Neighborhood or district |
| ↳ `administrative_district_level_1` | string | State, province, or region |
| ↳ `postal_code` | string | Postal or ZIP code |
| ↳ `country` | string | Two-letter ISO 3166-1 alpha-2 country code |
| ↳ `first_name` | string | First name of the addressee |
| ↳ `last_name` | string | Last name of the addressee |
| ↳ `birthday` | string | Birthday in YYYY-MM-DD or MM-DD format |
| ↳ `reference_id` | string | Optional external reference for the customer |
| ↳ `note` | string | Note about the customer |
| ↳ `creation_source` | string | How the customer profile was created |
| ↳ `preferences` | json | Customer communication preferences |
| ↳ `group_ids` | array | IDs of customer groups the customer belongs to |
| ↳ `segment_ids` | array | IDs of customer segments the customer belongs to |
| ↳ `version` | number | Optimistic concurrency version of the customer |
| ↳ `created_at` | string | Timestamp when the customer was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the customer was last updated (RFC 3339) |
| `metadata` | json | Customer summary metadata |
| ↳ `id` | string | Square customer ID |
| ↳ `email_address` | string | Customer email address |
| ↳ `given_name` | string | Customer first name |
| ↳ `family_name` | string | Customer last name |

### Square Delete Customer [#square-delete-customer]

Delete a customer profile from the Square customer directory

#### Input [#input-13]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `customerId` | string | Yes | ID of the customer to delete |

#### Output [#output-13]

| Parameter | Type | Description |
| - | - | - |
| `deleted` | boolean | Whether the customer was deleted |
| `id` | string | ID of the deleted customer |

### Square List Locations [#square-list-locations]

List all locations associated with the Square account

#### Input [#input-14]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |

#### Output [#output-14]

| Parameter | Type | Description |
| - | - | - |
| `locations` | array | Array of location objects |
| ↳ `id` | string | Unique ID for the location |
| ↳ `name` | string | Name of the location |
| ↳ `address` | object | Physical address |
| ↳ `address_line_1` | string | First line of the address |
| ↳ `address_line_2` | string | Second line of the address |
| ↳ `address_line_3` | string | Third line of the address |
| ↳ `locality` | string | City or town |
| ↳ `sublocality` | string | Neighborhood or district |
| ↳ `administrative_district_level_1` | string | State, province, or region |
| ↳ `postal_code` | string | Postal or ZIP code |
| ↳ `country` | string | Two-letter ISO 3166-1 alpha-2 country code |
| ↳ `first_name` | string | First name of the addressee |
| ↳ `last_name` | string | Last name of the addressee |
| ↳ `timezone` | string | IANA timezone of the location |
| ↳ `status` | string | Location status (ACTIVE or INACTIVE) |
| ↳ `type` | string | Location type (PHYSICAL or MOBILE) |
| ↳ `merchant_id` | string | ID of the merchant that owns the location |
| ↳ `country` | string | Country code of the location |
| ↳ `language_code` | string | Language code of the location |
| ↳ `currency` | string | Currency used by the location |
| ↳ `phone_number` | string | Phone number of the location |
| ↳ `business_name` | string | Business name shown to customers |
| ↳ `business_email` | string | Email of the business |
| ↳ `description` | string | Description of the location |
| ↳ `capabilities` | array | Capabilities of the location (e.g. CREDIT\_CARD\_PROCESSING) |
| ↳ `created_at` | string | Timestamp when the location was created (RFC 3339) |
| `metadata` | json | List metadata |
| ↳ `count` | number | Number of locations returned |

### Square Get Location [#square-get-location]

Retrieve a single location by its ID

#### Input [#input-15]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `locationId` | string | Yes | ID of the location to retrieve (use "main" for the main location) |

#### Output [#output-15]

| Parameter | Type | Description |
| - | - | - |
| `location` | object | Square Location object |
| ↳ `id` | string | Unique ID for the location |
| ↳ `name` | string | Name of the location |
| ↳ `address` | object | Physical address |
| ↳ `address_line_1` | string | First line of the address |
| ↳ `address_line_2` | string | Second line of the address |
| ↳ `address_line_3` | string | Third line of the address |
| ↳ `locality` | string | City or town |
| ↳ `sublocality` | string | Neighborhood or district |
| ↳ `administrative_district_level_1` | string | State, province, or region |
| ↳ `postal_code` | string | Postal or ZIP code |
| ↳ `country` | string | Two-letter ISO 3166-1 alpha-2 country code |
| ↳ `first_name` | string | First name of the addressee |
| ↳ `last_name` | string | Last name of the addressee |
| ↳ `timezone` | string | IANA timezone of the location |
| ↳ `status` | string | Location status (ACTIVE or INACTIVE) |
| ↳ `type` | string | Location type (PHYSICAL or MOBILE) |
| ↳ `merchant_id` | string | ID of the merchant that owns the location |
| ↳ `country` | string | Country code of the location |
| ↳ `language_code` | string | Language code of the location |
| ↳ `currency` | string | Currency used by the location |
| ↳ `phone_number` | string | Phone number of the location |
| ↳ `business_name` | string | Business name shown to customers |
| ↳ `business_email` | string | Email of the business |
| ↳ `description` | string | Description of the location |
| ↳ `capabilities` | array | Capabilities of the location (e.g. CREDIT\_CARD\_PROCESSING) |
| ↳ `created_at` | string | Timestamp when the location was created (RFC 3339) |
| `metadata` | json | Location summary metadata |
| ↳ `id` | string | Square location ID |
| ↳ `name` | string | Location name |

### Square Create Order [#square-create-order]

Create an order with line items, taxes, discounts, and fulfillments

#### Input [#input-16]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `order` | json | Yes | Square order object including location\_id and line\_items (e.g. \{"location\_id":"L1","line\_items":\[\{"name":"Coffee","quantity":"1","base\_price\_money":\{"amount":250,"currency":"USD"}}]}) |
| `idempotencyKey` | string | No | Unique key to make the request idempotent (auto-generated if omitted) |

#### Output [#output-16]

| Parameter | Type | Description |
| - | - | - |
| `order` | object | Square Order object |
| ↳ `id` | string | Unique ID for the order |
| ↳ `location_id` | string | ID of the location for the order |
| ↳ `reference_id` | string | Optional external reference for the order |
| ↳ `customer_id` | string | ID of the associated customer |
| ↳ `state` | string | Order state (OPEN, COMPLETED, or CANCELED) |
| ↳ `version` | number | Optimistic concurrency version of the order |
| ↳ `line_items` | array | Line items in the order |
| ↳ `taxes` | array | Taxes applied to the order |
| ↳ `discounts` | array | Discounts applied to the order |
| ↳ `fulfillments` | array | Fulfillments for the order |
| ↳ `net_amounts` | json | Net money amounts for the order |
| ↳ `total_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `total_tax_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `total_discount_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `total_service_charge_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `total_tip_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `created_at` | string | Timestamp when the order was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the order was last updated (RFC 3339) |
| ↳ `closed_at` | string | Timestamp when the order was closed (RFC 3339) |
| `metadata` | json | Order summary metadata |
| ↳ `id` | string | Square order ID |
| ↳ `state` | string | Current order state |
| ↳ `location_id` | string | Order location ID |

### Square Get Order [#square-get-order]

Retrieve a single order by its ID

#### Input [#input-17]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `orderId` | string | Yes | ID of the order to retrieve |

#### Output [#output-17]

| Parameter | Type | Description |
| - | - | - |
| `order` | object | Square Order object |
| ↳ `id` | string | Unique ID for the order |
| ↳ `location_id` | string | ID of the location for the order |
| ↳ `reference_id` | string | Optional external reference for the order |
| ↳ `customer_id` | string | ID of the associated customer |
| ↳ `state` | string | Order state (OPEN, COMPLETED, or CANCELED) |
| ↳ `version` | number | Optimistic concurrency version of the order |
| ↳ `line_items` | array | Line items in the order |
| ↳ `taxes` | array | Taxes applied to the order |
| ↳ `discounts` | array | Discounts applied to the order |
| ↳ `fulfillments` | array | Fulfillments for the order |
| ↳ `net_amounts` | json | Net money amounts for the order |
| ↳ `total_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `total_tax_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `total_discount_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `total_service_charge_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `total_tip_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `created_at` | string | Timestamp when the order was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the order was last updated (RFC 3339) |
| ↳ `closed_at` | string | Timestamp when the order was closed (RFC 3339) |
| `metadata` | json | Order summary metadata |
| ↳ `id` | string | Square order ID |
| ↳ `state` | string | Current order state |
| ↳ `location_id` | string | Order location ID |

### Square Search Orders [#square-search-orders]

Search orders across one or more locations using filters and sorting

#### Input [#input-18]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `locationIds` | array | Yes | Array of location IDs to search within |
| `query` | json | No | Square order query object with optional filter and sort (e.g. \{"filter":\{"state\_filter":\{"states":\["OPEN"]}}}) |
| `limit` | number | No | Maximum number of results to return per page |
| `cursor` | string | No | Pagination cursor from a previous response |

#### Output [#output-18]

| Parameter | Type | Description |
| - | - | - |
| `orders` | array | Array of matching order objects |
| ↳ `id` | string | Unique ID for the order |
| ↳ `location_id` | string | ID of the location for the order |
| ↳ `reference_id` | string | Optional external reference for the order |
| ↳ `customer_id` | string | ID of the associated customer |
| ↳ `state` | string | Order state (OPEN, COMPLETED, or CANCELED) |
| ↳ `version` | number | Optimistic concurrency version of the order |
| ↳ `line_items` | array | Line items in the order |
| ↳ `taxes` | array | Taxes applied to the order |
| ↳ `discounts` | array | Discounts applied to the order |
| ↳ `fulfillments` | array | Fulfillments for the order |
| ↳ `net_amounts` | json | Net money amounts for the order |
| ↳ `total_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `total_tax_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `total_discount_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `total_service_charge_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `total_tip_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `created_at` | string | Timestamp when the order was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the order was last updated (RFC 3339) |
| ↳ `closed_at` | string | Timestamp when the order was closed (RFC 3339) |
| `metadata` | json | List pagination metadata |
| ↳ `count` | number | Number of items returned in this page |
| ↳ `cursor` | string | Pagination cursor to fetch the next page, if more results exist |

### Square Pay Order [#square-pay-order]

Pay for an order using one or more already-approved payments

#### Input [#input-19]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `orderId` | string | Yes | ID of the order to pay for |
| `paymentIds` | array | No | IDs of approved payments to apply to the order |
| `orderVersion` | number | No | Version of the order being paid (for optimistic concurrency) |
| `idempotencyKey` | string | No | Unique key to make the request idempotent (auto-generated if omitted) |

#### Output [#output-19]

| Parameter | Type | Description |
| - | - | - |
| `order` | object | Square Order object |
| ↳ `id` | string | Unique ID for the order |
| ↳ `location_id` | string | ID of the location for the order |
| ↳ `reference_id` | string | Optional external reference for the order |
| ↳ `customer_id` | string | ID of the associated customer |
| ↳ `state` | string | Order state (OPEN, COMPLETED, or CANCELED) |
| ↳ `version` | number | Optimistic concurrency version of the order |
| ↳ `line_items` | array | Line items in the order |
| ↳ `taxes` | array | Taxes applied to the order |
| ↳ `discounts` | array | Discounts applied to the order |
| ↳ `fulfillments` | array | Fulfillments for the order |
| ↳ `net_amounts` | json | Net money amounts for the order |
| ↳ `total_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `total_tax_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `total_discount_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `total_service_charge_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `total_tip_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `created_at` | string | Timestamp when the order was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the order was last updated (RFC 3339) |
| ↳ `closed_at` | string | Timestamp when the order was closed (RFC 3339) |
| `metadata` | json | Order summary metadata |
| ↳ `id` | string | Square order ID |
| ↳ `state` | string | Current order state |
| ↳ `location_id` | string | Order location ID |

### Square Create Invoice [#square-create-invoice]

Create a draft invoice for an existing order and customer

#### Input [#input-20]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `invoice` | json | Yes | Square invoice object including location\_id, order\_id, primary\_recipient, and payment\_requests (e.g. \{"location\_id":"L1","order\_id":"O1","primary\_recipient":\{"customer\_id":"C1"},"payment\_requests":\[\{"request\_type":"BALANCE","due\_date":"2026-07-01"}]}) |
| `idempotencyKey` | string | No | Unique key to make the request idempotent (auto-generated if omitted) |

#### Output [#output-20]

| Parameter | Type | Description |
| - | - | - |
| `invoice` | object | Square Invoice object |
| ↳ `id` | string | Unique ID for the invoice |
| ↳ `version` | number | Optimistic concurrency version of the invoice |
| ↳ `location_id` | string | ID of the location for the invoice |
| ↳ `order_id` | string | ID of the order the invoice bills for |
| ↳ `status` | string | Invoice status (DRAFT, UNPAID, SCHEDULED, PARTIALLY\_PAID, PAID, etc.) |
| ↳ `invoice_number` | string | Human-readable invoice number |
| ↳ `title` | string | Title of the invoice |
| ↳ `description` | string | Description of the invoice |
| ↳ `public_url` | string | URL where the customer can view and pay the invoice |
| ↳ `primary_recipient` | json | Primary recipient of the invoice |
| ↳ `payment_requests` | array | Payment requests for the invoice |
| ↳ `next_payment_amount_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `scheduled_at` | string | Timestamp when the invoice is scheduled to be sent (RFC 3339) |
| ↳ `timezone` | string | Timezone used for invoice dates |
| ↳ `delivery_method` | string | How the invoice is delivered (EMAIL, SHARE\_MANUALLY, SMS) |
| ↳ `created_at` | string | Timestamp when the invoice was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the invoice was last updated (RFC 3339) |
| `metadata` | json | Invoice summary metadata |
| ↳ `id` | string | Square invoice ID |
| ↳ `status` | string | Current invoice status |
| ↳ `version` | number | Invoice version |

### Square Get Invoice [#square-get-invoice]

Retrieve a single invoice by its ID

#### Input [#input-21]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `invoiceId` | string | Yes | ID of the invoice to retrieve |

#### Output [#output-21]

| Parameter | Type | Description |
| - | - | - |
| `invoice` | object | Square Invoice object |
| ↳ `id` | string | Unique ID for the invoice |
| ↳ `version` | number | Optimistic concurrency version of the invoice |
| ↳ `location_id` | string | ID of the location for the invoice |
| ↳ `order_id` | string | ID of the order the invoice bills for |
| ↳ `status` | string | Invoice status (DRAFT, UNPAID, SCHEDULED, PARTIALLY\_PAID, PAID, etc.) |
| ↳ `invoice_number` | string | Human-readable invoice number |
| ↳ `title` | string | Title of the invoice |
| ↳ `description` | string | Description of the invoice |
| ↳ `public_url` | string | URL where the customer can view and pay the invoice |
| ↳ `primary_recipient` | json | Primary recipient of the invoice |
| ↳ `payment_requests` | array | Payment requests for the invoice |
| ↳ `next_payment_amount_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `scheduled_at` | string | Timestamp when the invoice is scheduled to be sent (RFC 3339) |
| ↳ `timezone` | string | Timezone used for invoice dates |
| ↳ `delivery_method` | string | How the invoice is delivered (EMAIL, SHARE\_MANUALLY, SMS) |
| ↳ `created_at` | string | Timestamp when the invoice was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the invoice was last updated (RFC 3339) |
| `metadata` | json | Invoice summary metadata |
| ↳ `id` | string | Square invoice ID |
| ↳ `status` | string | Current invoice status |
| ↳ `version` | number | Invoice version |

### Square List Invoices [#square-list-invoices]

List invoices for a specific location

#### Input [#input-22]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `locationId` | string | Yes | ID of the location to list invoices for |
| `limit` | number | No | Maximum number of results to return per page |
| `cursor` | string | No | Pagination cursor from a previous response |

#### Output [#output-22]

| Parameter | Type | Description |
| - | - | - |
| `invoices` | array | Array of invoice objects |
| ↳ `id` | string | Unique ID for the invoice |
| ↳ `version` | number | Optimistic concurrency version of the invoice |
| ↳ `location_id` | string | ID of the location for the invoice |
| ↳ `order_id` | string | ID of the order the invoice bills for |
| ↳ `status` | string | Invoice status (DRAFT, UNPAID, SCHEDULED, PARTIALLY\_PAID, PAID, etc.) |
| ↳ `invoice_number` | string | Human-readable invoice number |
| ↳ `title` | string | Title of the invoice |
| ↳ `description` | string | Description of the invoice |
| ↳ `public_url` | string | URL where the customer can view and pay the invoice |
| ↳ `primary_recipient` | json | Primary recipient of the invoice |
| ↳ `payment_requests` | array | Payment requests for the invoice |
| ↳ `next_payment_amount_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `scheduled_at` | string | Timestamp when the invoice is scheduled to be sent (RFC 3339) |
| ↳ `timezone` | string | Timezone used for invoice dates |
| ↳ `delivery_method` | string | How the invoice is delivered (EMAIL, SHARE\_MANUALLY, SMS) |
| ↳ `created_at` | string | Timestamp when the invoice was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the invoice was last updated (RFC 3339) |
| `metadata` | json | List pagination metadata |
| ↳ `count` | number | Number of items returned in this page |
| ↳ `cursor` | string | Pagination cursor to fetch the next page, if more results exist |

### Square Search Invoices [#square-search-invoices]

Search invoices across one or more locations

#### Input [#input-23]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `locationId` | string | Yes | ID of the location to search within (Square allows one location per search) |
| `limit` | number | No | Maximum number of results to return per page |
| `cursor` | string | No | Pagination cursor from a previous response |

#### Output [#output-23]

| Parameter | Type | Description |
| - | - | - |
| `invoices` | array | Array of matching invoice objects |
| ↳ `id` | string | Unique ID for the invoice |
| ↳ `version` | number | Optimistic concurrency version of the invoice |
| ↳ `location_id` | string | ID of the location for the invoice |
| ↳ `order_id` | string | ID of the order the invoice bills for |
| ↳ `status` | string | Invoice status (DRAFT, UNPAID, SCHEDULED, PARTIALLY\_PAID, PAID, etc.) |
| ↳ `invoice_number` | string | Human-readable invoice number |
| ↳ `title` | string | Title of the invoice |
| ↳ `description` | string | Description of the invoice |
| ↳ `public_url` | string | URL where the customer can view and pay the invoice |
| ↳ `primary_recipient` | json | Primary recipient of the invoice |
| ↳ `payment_requests` | array | Payment requests for the invoice |
| ↳ `next_payment_amount_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `scheduled_at` | string | Timestamp when the invoice is scheduled to be sent (RFC 3339) |
| ↳ `timezone` | string | Timezone used for invoice dates |
| ↳ `delivery_method` | string | How the invoice is delivered (EMAIL, SHARE\_MANUALLY, SMS) |
| ↳ `created_at` | string | Timestamp when the invoice was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the invoice was last updated (RFC 3339) |
| `metadata` | json | List pagination metadata |
| ↳ `count` | number | Number of items returned in this page |
| ↳ `cursor` | string | Pagination cursor to fetch the next page, if more results exist |

### Square Publish Invoice [#square-publish-invoice]

Publish a draft invoice so it is sent to the customer and becomes payable

#### Input [#input-24]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `invoiceId` | string | Yes | ID of the invoice to publish |
| `version` | number | Yes | Current version of the invoice (use the version returned by Create Invoice) |
| `idempotencyKey` | string | No | Unique key to make the request idempotent (auto-generated if omitted) |

#### Output [#output-24]

| Parameter | Type | Description |
| - | - | - |
| `invoice` | object | Square Invoice object |
| ↳ `id` | string | Unique ID for the invoice |
| ↳ `version` | number | Optimistic concurrency version of the invoice |
| ↳ `location_id` | string | ID of the location for the invoice |
| ↳ `order_id` | string | ID of the order the invoice bills for |
| ↳ `status` | string | Invoice status (DRAFT, UNPAID, SCHEDULED, PARTIALLY\_PAID, PAID, etc.) |
| ↳ `invoice_number` | string | Human-readable invoice number |
| ↳ `title` | string | Title of the invoice |
| ↳ `description` | string | Description of the invoice |
| ↳ `public_url` | string | URL where the customer can view and pay the invoice |
| ↳ `primary_recipient` | json | Primary recipient of the invoice |
| ↳ `payment_requests` | array | Payment requests for the invoice |
| ↳ `next_payment_amount_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `scheduled_at` | string | Timestamp when the invoice is scheduled to be sent (RFC 3339) |
| ↳ `timezone` | string | Timezone used for invoice dates |
| ↳ `delivery_method` | string | How the invoice is delivered (EMAIL, SHARE\_MANUALLY, SMS) |
| ↳ `created_at` | string | Timestamp when the invoice was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the invoice was last updated (RFC 3339) |
| `metadata` | json | Invoice summary metadata |
| ↳ `id` | string | Square invoice ID |
| ↳ `status` | string | Current invoice status |
| ↳ `version` | number | Invoice version |

### Square Cancel Invoice [#square-cancel-invoice]

Cancel a published invoice that is unpaid or partially paid

#### Input [#input-25]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `invoiceId` | string | Yes | ID of the invoice to cancel |
| `version` | number | Yes | Current version of the invoice |

#### Output [#output-25]

| Parameter | Type | Description |
| - | - | - |
| `invoice` | object | Square Invoice object |
| ↳ `id` | string | Unique ID for the invoice |
| ↳ `version` | number | Optimistic concurrency version of the invoice |
| ↳ `location_id` | string | ID of the location for the invoice |
| ↳ `order_id` | string | ID of the order the invoice bills for |
| ↳ `status` | string | Invoice status (DRAFT, UNPAID, SCHEDULED, PARTIALLY\_PAID, PAID, etc.) |
| ↳ `invoice_number` | string | Human-readable invoice number |
| ↳ `title` | string | Title of the invoice |
| ↳ `description` | string | Description of the invoice |
| ↳ `public_url` | string | URL where the customer can view and pay the invoice |
| ↳ `primary_recipient` | json | Primary recipient of the invoice |
| ↳ `payment_requests` | array | Payment requests for the invoice |
| ↳ `next_payment_amount_money` | object | Monetary amount with a currency |
| ↳ `amount` | number | Amount in the smallest denomination of the currency (e.g. cents for USD) |
| ↳ `currency` | string | Three-letter ISO 4217 currency code (e.g. USD) |
| ↳ `scheduled_at` | string | Timestamp when the invoice is scheduled to be sent (RFC 3339) |
| ↳ `timezone` | string | Timezone used for invoice dates |
| ↳ `delivery_method` | string | How the invoice is delivered (EMAIL, SHARE\_MANUALLY, SMS) |
| ↳ `created_at` | string | Timestamp when the invoice was created (RFC 3339) |
| ↳ `updated_at` | string | Timestamp when the invoice was last updated (RFC 3339) |
| `metadata` | json | Invoice summary metadata |
| ↳ `id` | string | Square invoice ID |
| ↳ `status` | string | Current invoice status |
| ↳ `version` | number | Invoice version |

### Square Delete Invoice [#square-delete-invoice]

Delete a draft invoice

#### Input [#input-26]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `invoiceId` | string | Yes | ID of the draft invoice to delete |
| `version` | number | No | Current version of the invoice (required if the invoice has been updated) |

#### Output [#output-26]

| Parameter | Type | Description |
| - | - | - |
| `deleted` | boolean | Whether the invoice was deleted |
| `id` | string | ID of the deleted invoice |

### Square Upsert Catalog Object [#square-upsert-catalog-object]

Create or update a catalog object such as an item, variation, or category

#### Input [#input-27]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `object` | json | Yes | Square catalog object to create or update. Use ID "#name" for new objects (e.g. \{"type":"ITEM","id":"#Coffee","item\_data":\{"name":"Coffee"}}) |
| `idempotencyKey` | string | No | Unique key to make the request idempotent (auto-generated if omitted) |

#### Output [#output-27]

| Parameter | Type | Description |
| - | - | - |
| `object` | object | Square CatalogObject |
| ↳ `type` | string | Type of catalog object (ITEM, ITEM\_VARIATION, CATEGORY, IMAGE, etc.) |
| ↳ `id` | string | Unique ID for the catalog object |
| ↳ `version` | number | Optimistic concurrency version of the object |
| ↳ `updated_at` | string | Timestamp when the object was last updated (RFC 3339) |
| ↳ `is_deleted` | boolean | Whether the object is deleted |
| ↳ `present_at_all_locations` | boolean | Whether the object is present at all locations |
| ↳ `item_data` | json | Item-specific data (when type is ITEM) |
| ↳ `item_variation_data` | json | Variation-specific data (when type is ITEM\_VARIATION) |
| ↳ `category_data` | json | Category-specific data (when type is CATEGORY) |
| ↳ `image_data` | json | Image-specific data (when type is IMAGE) |
| `metadata` | json | Catalog object summary metadata |
| ↳ `id` | string | Square catalog object ID |
| ↳ `type` | string | Catalog object type |
| ↳ `version` | number | Catalog object version |

### Square Get Catalog Object [#square-get-catalog-object]

Retrieve a single catalog object by its ID

#### Input [#input-28]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `objectId` | string | Yes | ID of the catalog object to retrieve |
| `includeRelatedObjects` | boolean | No | Whether to include related objects such as an item variations |

#### Output [#output-28]

| Parameter | Type | Description |
| - | - | - |
| `object` | object | Square CatalogObject |
| ↳ `type` | string | Type of catalog object (ITEM, ITEM\_VARIATION, CATEGORY, IMAGE, etc.) |
| ↳ `id` | string | Unique ID for the catalog object |
| ↳ `version` | number | Optimistic concurrency version of the object |
| ↳ `updated_at` | string | Timestamp when the object was last updated (RFC 3339) |
| ↳ `is_deleted` | boolean | Whether the object is deleted |
| ↳ `present_at_all_locations` | boolean | Whether the object is present at all locations |
| ↳ `item_data` | json | Item-specific data (when type is ITEM) |
| ↳ `item_variation_data` | json | Variation-specific data (when type is ITEM\_VARIATION) |
| ↳ `category_data` | json | Category-specific data (when type is CATEGORY) |
| ↳ `image_data` | json | Image-specific data (when type is IMAGE) |
| `metadata` | json | Catalog object summary metadata |
| ↳ `id` | string | Square catalog object ID |
| ↳ `type` | string | Catalog object type |
| ↳ `version` | number | Catalog object version |

### Square List Catalog [#square-list-catalog]

List catalog objects, optionally filtered by type

#### Input [#input-29]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `types` | string | No | Comma-separated catalog object types to return (e.g. ITEM,CATEGORY). Defaults to all top-level types |
| `cursor` | string | No | Pagination cursor from a previous response |

#### Output [#output-29]

| Parameter | Type | Description |
| - | - | - |
| `objects` | array | Array of catalog objects |
| ↳ `type` | string | Type of catalog object (ITEM, ITEM\_VARIATION, CATEGORY, IMAGE, etc.) |
| ↳ `id` | string | Unique ID for the catalog object |
| ↳ `version` | number | Optimistic concurrency version of the object |
| ↳ `updated_at` | string | Timestamp when the object was last updated (RFC 3339) |
| ↳ `is_deleted` | boolean | Whether the object is deleted |
| ↳ `present_at_all_locations` | boolean | Whether the object is present at all locations |
| ↳ `item_data` | json | Item-specific data (when type is ITEM) |
| ↳ `item_variation_data` | json | Variation-specific data (when type is ITEM\_VARIATION) |
| ↳ `category_data` | json | Category-specific data (when type is CATEGORY) |
| ↳ `image_data` | json | Image-specific data (when type is IMAGE) |
| `metadata` | json | List pagination metadata |
| ↳ `count` | number | Number of items returned in this page |
| ↳ `cursor` | string | Pagination cursor to fetch the next page, if more results exist |

### Square Search Catalog Objects [#square-search-catalog-objects]

Search catalog objects by type and query filters

#### Input [#input-30]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `objectTypes` | array | No | Array of catalog object types to search (e.g. \["ITEM","CATEGORY"]) |
| `query` | json | No | Square catalog query object (e.g. \{"text\_query":\{"keywords":\["coffee"]}} or \{"prefix\_query":\{...}}) |
| `limit` | number | No | Maximum number of results to return per page |
| `cursor` | string | No | Pagination cursor from a previous response |

#### Output [#output-30]

| Parameter | Type | Description |
| - | - | - |
| `objects` | array | Array of matching catalog objects |
| ↳ `type` | string | Type of catalog object (ITEM, ITEM\_VARIATION, CATEGORY, IMAGE, etc.) |
| ↳ `id` | string | Unique ID for the catalog object |
| ↳ `version` | number | Optimistic concurrency version of the object |
| ↳ `updated_at` | string | Timestamp when the object was last updated (RFC 3339) |
| ↳ `is_deleted` | boolean | Whether the object is deleted |
| ↳ `present_at_all_locations` | boolean | Whether the object is present at all locations |
| ↳ `item_data` | json | Item-specific data (when type is ITEM) |
| ↳ `item_variation_data` | json | Variation-specific data (when type is ITEM\_VARIATION) |
| ↳ `category_data` | json | Category-specific data (when type is CATEGORY) |
| ↳ `image_data` | json | Image-specific data (when type is IMAGE) |
| `metadata` | json | List pagination metadata |
| ↳ `count` | number | Number of items returned in this page |
| ↳ `cursor` | string | Pagination cursor to fetch the next page, if more results exist |

### Square Create Catalog Image [#square-create-catalog-image]

Upload an image and attach it to the catalog, optionally to a specific item

#### Input [#input-31]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `file` | file | Yes | The image file to upload (UserFile object) |
| `fileName` | string | No | Optional filename override for the image |
| `objectId` | string | No | ID of the catalog object (e.g. an item) to attach the image to |
| `caption` | string | No | Caption (alt text) for the image |
| `idempotencyKey` | string | No | Unique key to make the request idempotent (auto-generated if omitted) |

#### Output [#output-31]

| Parameter | Type | Description |
| - | - | - |
| `object` | object | Square CatalogObject |
| ↳ `type` | string | Type of catalog object (ITEM, ITEM\_VARIATION, CATEGORY, IMAGE, etc.) |
| ↳ `id` | string | Unique ID for the catalog object |
| ↳ `version` | number | Optimistic concurrency version of the object |
| ↳ `updated_at` | string | Timestamp when the object was last updated (RFC 3339) |
| ↳ `is_deleted` | boolean | Whether the object is deleted |
| ↳ `present_at_all_locations` | boolean | Whether the object is present at all locations |
| ↳ `item_data` | json | Item-specific data (when type is ITEM) |
| ↳ `item_variation_data` | json | Variation-specific data (when type is ITEM\_VARIATION) |
| ↳ `category_data` | json | Category-specific data (when type is CATEGORY) |
| ↳ `image_data` | json | Image-specific data (when type is IMAGE) |
| `metadata` | json | Catalog object summary metadata |
| ↳ `id` | string | Square catalog object ID |
| ↳ `type` | string | Catalog object type |
| ↳ `version` | number | Catalog object version |

### Square Delete Catalog Object [#square-delete-catalog-object]

Delete a catalog object and its children (e.g. an item and its variations)

#### Input [#input-32]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `objectId` | string | Yes | ID of the catalog object to delete |

#### Output [#output-32]

| Parameter | Type | Description |
| - | - | - |
| `deleted` | boolean | Whether the catalog object was deleted |
| `deleted_object_ids` | array | IDs of all catalog objects deleted (including children) |
| `deleted_at` | string | Timestamp when the deletion occurred (RFC 3339) |

### Square Batch Retrieve Inventory Counts [#square-batch-retrieve-inventory-counts]

Retrieve current inventory counts for catalog items across locations

#### Input [#input-33]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Square access token (personal access token) |
| `catalogObjectIds` | array | No | IDs of the catalog item variations to retrieve counts for |
| `locationIds` | array | No | IDs of the locations to retrieve counts for (defaults to all locations) |
| `states` | array | No | Inventory states to filter by (e.g. IN\_STOCK, SOLD, IN\_TRANSIT) |
| `updatedAfter` | string | No | Only return counts updated after this RFC 3339 timestamp |
| `limit` | number | No | Maximum number of results to return per page (1-1000) |
| `cursor` | string | No | Pagination cursor from a previous response |

#### Output [#output-33]

| Parameter | Type | Description |
| - | - | - |
| `counts` | array | Array of inventory count objects |
| ↳ `catalog_object_id` | string | ID of the catalog object (item variation) being counted |
| ↳ `catalog_object_type` | string | Type of the counted catalog object (usually ITEM\_VARIATION) |
| ↳ `state` | string | Inventory state (e.g. IN\_STOCK, SOLD, WASTE) |
| ↳ `location_id` | string | ID of the location for this count |
| ↳ `quantity` | string | Number of units in the given state at the location |
| ↳ `calculated_at` | string | Timestamp when the count was calculated (RFC 3339) |
| `metadata` | json | List pagination metadata |
| ↳ `count` | number | Number of items returned in this page |
| ↳ `cursor` | string | Pagination cursor to fetch the next page, if more results exist |