Use Square 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.

Use the block

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

Square Create Payment

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

Inputs and outputs

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

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

Retrieve details for a single payment by its ID

Inputs and outputs

Input

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

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 List Payments

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

Inputs and outputs

Input

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

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

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

Inputs and outputs

Input

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

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 Complete Payment

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

Inputs and outputs

Input

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

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

Refund all or part of a completed payment

Inputs and outputs

Input

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

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

Retrieve a single payment refund by its ID

Inputs and outputs

Input

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

Output

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

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

Inputs and outputs

Input

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

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

Create a new customer profile in the Square customer directory

Inputs and outputs

Input

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

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

Retrieve a single customer profile by its ID

Inputs and outputs

Input

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

Output

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

List customer profiles in the Square customer directory

Inputs and outputs

Input

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

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

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

Inputs and outputs

Input

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"}}})
limit	number	No	Maximum number of results to return per page
cursor	string	No	Pagination cursor from a previous response

Output

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

Update fields on an existing customer profile

Inputs and outputs

Input

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

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

Delete a customer profile from the Square customer directory

Inputs and outputs

Input

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

Output

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

Square List Locations

List all locations associated with the Square account

Inputs and outputs

Input

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

Output

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

Retrieve a single location by its ID

Inputs and outputs

Input

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

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

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

Inputs and outputs

Input

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

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

Retrieve a single order by its ID

Inputs and outputs

Input

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

Output

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

Search orders across one or more locations using filters and sorting

Inputs and outputs

Input

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

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

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

Inputs and outputs

Input

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

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

Create a draft invoice for an existing order and customer

Inputs and outputs

Input

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

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

Retrieve a single invoice by its ID

Inputs and outputs

Input

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

Output

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

List invoices for a specific location

Inputs and outputs

Input

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

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

Search invoices across one or more locations

Inputs and outputs

Input

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

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

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

Inputs and outputs

Input

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

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

Cancel a published invoice that is unpaid or partially paid

Inputs and outputs

Input

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

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

Delete a draft invoice

Inputs and outputs

Input

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

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

Square Upsert Catalog Object

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

Inputs and outputs

Input

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

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

Retrieve a single catalog object by its ID

Inputs and outputs

Input

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

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

List catalog objects, optionally filtered by type

Inputs and outputs

Input

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

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

Search catalog objects by type and query filters

Inputs and outputs

Input

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

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

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

Inputs and outputs

Input

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

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

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

Inputs and outputs

Input

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

Output

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

Retrieve current inventory counts for catalog items across locations

Inputs and outputs

Input

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

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