Integrate Square into the workflow. 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).
Take a payment using a payment source such as a card nonce or a card on file
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
sourceId | string | 是 | ID of the payment source (card nonce, card-on-file ID, or wallet token) |
amount | number | 是 | Amount in the smallest currency denomination (e.g. 1000 = $10.00) |
currency | string | 是 | Three-letter ISO 4217 currency code (e.g. USD) |
idempotencyKey | string | 否 | Unique key to make the request idempotent (auto-generated if omitted) |
customerId | string | 否 | ID of the customer associated with the payment |
locationId | string | 否 | ID of the location where the payment is taken (defaults to the main location) |
orderId | string | 否 | ID of the order associated with the payment |
referenceId | string | 否 | Optional external reference for the payment |
note | string | 否 | Optional note attached to the payment |
autocomplete | boolean | 否 | Whether to immediately capture the payment (defaults to true) |
| 参数 | 类型 | 描述 |
|---|
payment | object | The created 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 |
Retrieve details for a single payment by its ID
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
paymentId | string | 是 | ID of the payment to retrieve |
| 参数 | 类型 | 描述 |
|---|
payment | object | The retrieved 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 |
List payments taken by the account, optionally filtered by location and time range
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
locationId | string | 否 | Filter payments by location ID |
beginTime | string | 否 | RFC 3339 timestamp for the beginning of the reporting period |
endTime | string | 否 | RFC 3339 timestamp for the end of the reporting period |
limit | number | 否 | Maximum number of results to return per page |
cursor | string | 否 | Pagination cursor from a previous response |
| 参数 | 类型 | 描述 |
|---|
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 |
Cancel (void) an authorized payment that has not been captured
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
paymentId | string | 是 | ID of the payment to cancel |
| 参数 | 类型 | 描述 |
|---|
payment | object | The canceled 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 |
Capture (complete) a payment that was authorized with delayed capture
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
paymentId | string | 是 | ID of the payment to complete |
versionToken | string | 否 | Optional version token for optimistic concurrency control |
| 参数 | 类型 | 描述 |
|---|
payment | object | The completed 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 |
Refund all or part of a completed payment
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
paymentId | string | 是 | ID of the payment to refund |
amount | number | 是 | Amount to refund in the smallest currency denomination (e.g. 100 = $1.00) |
currency | string | 是 | Three-letter ISO 4217 currency code (e.g. USD) |
idempotencyKey | string | 否 | Unique key to make the request idempotent (auto-generated if omitted) |
reason | string | 否 | Reason for the refund |
| 参数 | 类型 | 描述 |
|---|
refund | object | The created refund 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 |
Retrieve a single payment refund by its ID
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
refundId | string | 是 | ID of the refund to retrieve |
| 参数 | 类型 | 描述 |
|---|
refund | object | The retrieved refund 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 |
List payment refunds, optionally filtered by location, status, and time range
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
locationId | string | 否 | Filter refunds by location ID |
status | string | 否 | Filter by refund status (PENDING, COMPLETED, REJECTED, or FAILED) |
beginTime | string | 否 | RFC 3339 timestamp for the beginning of the reporting period |
endTime | string | 否 | RFC 3339 timestamp for the end of the reporting period |
limit | number | 否 | Maximum number of results to return per page |
cursor | string | 否 | Pagination cursor from a previous response |
| 参数 | 类型 | 描述 |
|---|
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 |
Create a new customer profile in the Square customer directory
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
givenName | string | 否 | First name of the customer |
familyName | string | 否 | Last name of the customer |
companyName | string | 否 | Business name of the customer |
nickname | string | 否 | Nickname of the customer |
emailAddress | string | 否 | Email address of the customer |
phoneNumber | string | 否 | Phone number of the customer |
birthday | string | 否 | Birthday in YYYY-MM-DD or MM-DD format |
note | string | 否 | Note about the customer |
referenceId | string | 否 | Optional external reference for the customer |
address | json | 否 | Square address object for the customer |
idempotencyKey | string | 否 | Unique key to make the request idempotent (auto-generated if omitted) |
| 参数 | 类型 | 描述 |
|---|
customer | object | The created 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 |
Retrieve a single customer profile by its ID
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
customerId | string | 是 | ID of the customer to retrieve |
| 参数 | 类型 | 描述 |
|---|
customer | object | The retrieved 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 |
List customer profiles in the Square customer directory
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
limit | number | 否 | Maximum number of results to return per page (max 100) |
cursor | string | 否 | Pagination cursor from a previous response |
sortField | string | 否 | Field to sort by (DEFAULT or CREATED_AT) |
sortOrder | string | 否 | Sort order (ASC or DESC) |
| 参数 | 类型 | 描述 |
|---|
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 |
Search customer profiles using filters such as email, phone, or creation date
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
query | json | 否 | Square customer query object with optional filter and sort (e.g. {"filter":{"email_address":{"exact":"a@b.com"}}}) |
limit | number | 否 | Maximum number of results to return per page |
cursor | string | 否 | Pagination cursor from a previous response |
| 参数 | 类型 | 描述 |
|---|
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 |
Update fields on an existing customer profile
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
customerId | string | 是 | ID of the customer to update |
givenName | string | 否 | First name of the customer |
familyName | string | 否 | Last name of the customer |
companyName | string | 否 | Business name of the customer |
nickname | string | 否 | Nickname of the customer |
emailAddress | string | 否 | Email address of the customer |
phoneNumber | string | 否 | Phone number of the customer |
birthday | string | 否 | Birthday in YYYY-MM-DD or MM-DD format |
note | string | 否 | Note about the customer |
referenceId | string | 否 | Optional external reference for the customer |
address | json | 否 | Square address object for the customer |
| 参数 | 类型 | 描述 |
|---|
customer | object | The updated 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 |
Delete a customer profile from the Square customer directory
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
customerId | string | 是 | ID of the customer to delete |
| 参数 | 类型 | 描述 |
|---|
deleted | boolean | Whether the customer was deleted |
id | string | ID of the deleted customer |
List all locations associated with the Square account
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
| 参数 | 类型 | 描述 |
|---|
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 |
Retrieve a single location by its ID
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
locationId | string | 是 | ID of the location to retrieve (use "main" for the main location) |
| 参数 | 类型 | 描述 |
|---|
location | object | The retrieved 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 |
Create an order with line items, taxes, discounts, and fulfillments
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
order | json | 是 | 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 | 否 | Unique key to make the request idempotent (auto-generated if omitted) |
| 参数 | 类型 | 描述 |
|---|
order | object | The created 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 |
Retrieve a single order by its ID
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
orderId | string | 是 | ID of the order to retrieve |
| 参数 | 类型 | 描述 |
|---|
order | object | The retrieved 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 |
Search orders across one or more locations using filters and sorting
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
locationIds | array | 是 | Array of location IDs to search within |
query | json | 否 | Square order query object with optional filter and sort (e.g. {"filter":{"state_filter":{"states":["OPEN"]}}}) |
limit | number | 否 | Maximum number of results to return per page |
cursor | string | 否 | Pagination cursor from a previous response |
| 参数 | 类型 | 描述 |
|---|
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 |
Pay for an order using one or more already-approved payments
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
orderId | string | 是 | ID of the order to pay for |
paymentIds | array | 否 | IDs of approved payments to apply to the order |
orderVersion | number | 否 | Version of the order being paid (for optimistic concurrency) |
idempotencyKey | string | 否 | Unique key to make the request idempotent (auto-generated if omitted) |
| 参数 | 类型 | 描述 |
|---|
order | object | The paid 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 |
Create a draft invoice for an existing order and customer
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
invoice | json | 是 | 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 | 否 | Unique key to make the request idempotent (auto-generated if omitted) |
| 参数 | 类型 | 描述 |
|---|
invoice | object | The created 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 |
Retrieve a single invoice by its ID
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
invoiceId | string | 是 | ID of the invoice to retrieve |
| 参数 | 类型 | 描述 |
|---|
invoice | object | The retrieved 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 |
List invoices for a specific location
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
locationId | string | 是 | ID of the location to list invoices for |
limit | number | 否 | Maximum number of results to return per page |
cursor | string | 否 | Pagination cursor from a previous response |
| 参数 | 类型 | 描述 |
|---|
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 |
Search invoices across one or more locations
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
locationId | string | 是 | ID of the location to search within (Square allows one location per search) |
limit | number | 否 | Maximum number of results to return per page |
cursor | string | 否 | Pagination cursor from a previous response |
| 参数 | 类型 | 描述 |
|---|
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 |
Publish a draft invoice so it is sent to the customer and becomes payable
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
invoiceId | string | 是 | ID of the invoice to publish |
version | number | 是 | Current version of the invoice (use the version returned by Create Invoice) |
idempotencyKey | string | 否 | Unique key to make the request idempotent (auto-generated if omitted) |
| 参数 | 类型 | 描述 |
|---|
invoice | object | The published 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 |
Cancel a published invoice that is unpaid or partially paid
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
invoiceId | string | 是 | ID of the invoice to cancel |
version | number | 是 | Current version of the invoice |
| 参数 | 类型 | 描述 |
|---|
invoice | object | The canceled 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 |
Delete a draft invoice
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
invoiceId | string | 是 | ID of the draft invoice to delete |
version | number | 否 | Current version of the invoice (required if the invoice has been updated) |
| 参数 | 类型 | 描述 |
|---|
deleted | boolean | Whether the invoice was deleted |
id | string | ID of the deleted invoice |
Create or update a catalog object such as an item, variation, or category
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
object | json | 是 | 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 | 否 | Unique key to make the request idempotent (auto-generated if omitted) |
| 参数 | 类型 | 描述 |
|---|
object | object | The created or updated catalog object |
↳ 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 |
Retrieve a single catalog object by its ID
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
objectId | string | 是 | ID of the catalog object to retrieve |
includeRelatedObjects | boolean | 否 | Whether to include related objects such as an item variations |
| 参数 | 类型 | 描述 |
|---|
object | object | The retrieved catalog object |
↳ 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 |
List catalog objects, optionally filtered by type
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
types | string | 否 | Comma-separated catalog object types to return (e.g. ITEM,CATEGORY). Defaults to all top-level types |
cursor | string | 否 | Pagination cursor from a previous response |
| 参数 | 类型 | 描述 |
|---|
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 |
Search catalog objects by type and query filters
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
objectTypes | array | 否 | Array of catalog object types to search (e.g. ["ITEM","CATEGORY"]) |
query | json | 否 | Square catalog query object (e.g. {"text_query":{"keywords":["coffee"]}} or {"prefix_query":{...}}) |
limit | number | 否 | Maximum number of results to return per page |
cursor | string | 否 | Pagination cursor from a previous response |
| 参数 | 类型 | 描述 |
|---|
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 |
Upload an image and attach it to the catalog, optionally to a specific item
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
file | file | 是 | The image file to upload (UserFile object) |
fileName | string | 否 | Optional filename override for the image |
objectId | string | 否 | ID of the catalog object (e.g. an item) to attach the image to |
caption | string | 否 | Caption (alt text) for the image |
idempotencyKey | string | 否 | Unique key to make the request idempotent (auto-generated if omitted) |
| 参数 | 类型 | 描述 |
|---|
object | object | The created catalog image object |
↳ 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 |
Delete a catalog object and its children (e.g. an item and its variations)
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
objectId | string | 是 | ID of the catalog object to delete |
| 参数 | 类型 | 描述 |
|---|
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) |
Retrieve current inventory counts for catalog items across locations
| 参数 | 类型 | 必填 | 描述 |
|---|
apiKey | string | 是 | Square access token (personal access token) |
catalogObjectIds | array | 否 | IDs of the catalog item variations to retrieve counts for |
locationIds | array | 否 | IDs of the locations to retrieve counts for (defaults to all locations) |
states | array | 否 | Inventory states to filter by (e.g. IN_STOCK, SOLD, IN_TRANSIT) |
updatedAfter | string | 否 | Only return counts updated after this RFC 3339 timestamp |
limit | number | 否 | Maximum number of results to return per page (1-1000) |
cursor | string | 否 | Pagination cursor from a previous response |
| 参数 | 类型 | 描述 |
|---|
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 |
