Customers

Locations

Orders

Represents a payment processed by the Square API.

Represents an amount of money. `Money` fields can be signed or unsigned.
Fields that do not explicitly define whether they are signed or unsigned are
considered unsigned and can only hold positive amounts. For signed fields, the
sign of the value indicates the purpose of the money transfer. See
[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)
for more information.

The amount of money, in the smallest denomination of the currency
indicated by `currency`. For example, when `currency` is `USD`, `amount` is
in cents. Monetary amounts can be positive or negative. See the specific
field description to determine the meaning of the sign in a particular case.

The type of currency, in __ISO 4217 format__. For example, the currency
code for US dollars is `USD`.

See [Currency](https://developer.squareup.com/reference/square_2024-03-20/enums/Currency) for possible values.

Details about the application that took the payment.

The Square ID assigned to the application used to take the payment. 
Application developers can use this information to identify payments that 
their application processed. 
For example, if a developer uses a custom application to process payments, 
this field contains the application ID from the Developer Dashboard. 
If a seller uses a [Square App Marketplace](https://developer.squareup.com/docs/app-marketplace) 
application to process payments, the field contains the corresponding application ID.

The Square product, such as Square Point of Sale (POS), 
Square Invoices, or Square Virtual Terminal.

Additional details about BANK_ACCOUNT type payments.

The ownership type of the bank account performing the transfer.
The type can be `INDIVIDUAL`, `COMPANY`, or `ACCOUNT_TYPE_UNKNOWN`.

The name of the bank associated with the bank account.

The two-letter ISO code representing the country the bank account is located in.

Information about errors encountered during the request.

Uniquely identifies the bank account for this seller and can be used
to determine if payments are from the same bank account.

The statement description as sent to the bank.

The type of the bank transfer. The type can be `ACH` or `UNKNOWN`.

Represents a postal address in a country. 
For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).

The first line of the address.

Fields that start with `address_line` provide the address's most specific
details, like street number, street name, and building name. They do *not*
provide less specific details like city, state/province, or country (these
details are provided in other fields).

A civil entity within the address's country. In the US, this
is the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).

A civil entity within the address's `administrative_district_level_1`.
In the US, this is the county.

A civil entity within the address's `administrative_district_level_2`,
if any.

The address's country, in the two-letter format of ISO 3166. For example, `US` or `FR`.

Optional first name when it's representing recipient.

Optional last name when it's representing recipient.

The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).

The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).

A civil region within the address's `locality`, if any.

A civil region within the address's `sublocality`, if any.

A civil region within the address's `sublocality_2`, if any.

Additional details about a Buy Now Pay Later payment type.

The brand used for the Buy Now Pay Later payment.
The brand can be `AFTERPAY`, `CLEARPAY` or `UNKNOWN`.

Actions that can be performed on this payment:
- `EDIT_AMOUNT_UP` - The payment amount can be edited up.
- `EDIT_AMOUNT_DOWN` - The payment amount can be edited down.
- `EDIT_TIP_AMOUNT_UP` - The tip amount can be edited up.
- `EDIT_TIP_AMOUNT_DOWN` - The tip amount can be edited down.
- `EDIT_DELAY_ACTION` - The delay_action can be edited.

Reflects the current status of a card payment. Contains only non-confidential information.

For EMV payments, the cryptogram generated for the payment.

For EMV payments, the application ID identifies the EMV application used for the payment.

For EMV payments, the human-readable name of the EMV application used for the payment.

The status code returned by the card issuer that describes the payment's
authorization status.

The status code returned from the Address Verification System (AVS) check. The code can be
`AVS_ACCEPTED`, `AVS_REJECTED`, or `AVS_NOT_CHECKED`.

The status code returned from the Card Verification Value (CVV) check. The code can be
`CVV_ACCEPTED`, `CVV_REJECTED`, or `CVV_NOT_CHECKED`.

The method used to enter the card's details for the payment. The method can be
`KEYED`, `SWIPED`, `EMV`, `ON_FILE`, or `CONTACTLESS`.

Whether the card must be physically present for the payment to
be refunded.  If set to `true`, the card must be present.

The statement description sent to the card networks.

Note: The actual statement description varies and is likely to be truncated and appended with
additional information on a per issuer basis.

The card payment's current state. The state can be AUTHORIZED, CAPTURED, VOIDED, or
FAILED.

For EMV payments, the method used to verify the cardholder's identity. The method can be
`PIN`, `SIGNATURE`, `PIN_AND_SIGNATURE`, `ON_DEVICE`, or `NONE`.

For EMV payments, the results of the cardholder verification. The result can be
`SUCCESS`, `FAILURE`, or `UNKNOWN`.

Stores details about a cash payment. Contains only non-confidential information. For more information, see 
[Take Cash Payments](https://developer.squareup.com/docs/payments-api/take-payments/cash-payments).

The timestamp of when the payment was created, in RFC 3339 format.

The ID of the customer associated with the payment. If the ID is 
not provided in the `CreatePayment` request that was used to create the `Payment`, 
Square may use information in the request 
(such as the billing and shipping address, email address, and payment source) 
to identify a matching customer profile in the Customer Directory. 
If found, the profile ID is used. If a profile is not found, the 
API attempts to create an 
[instant profile](https://developer.squareup.com/docs/customers-api/what-it-does#instant-profiles). 
If the API cannot create an 
instant profile (either because the seller has disabled it or the 
seller's region prevents creating it), this field remains unset. Note that 
this process is asynchronous and it may take some time before a 
customer ID is added to the payment.

The action to be applied to the payment when the `delay_duration` has elapsed.

Current values include `CANCEL` and `COMPLETE`.

The duration of time after the payment's creation when Square automatically applies the
`delay_action` to the payment. This automatic `delay_action` applies only to payments that
do not reach a terminal state (COMPLETED, CANCELED, or FAILED) before the `delay_duration`
time period.

This field is specified as a time duration, in RFC 3339 format.

Notes:
This feature is only supported for card payments.

Default:

- Card-present payments: "PT36H" (36 hours) from the creation time.
- Card-not-present payments: "P7D" (7 days) from the creation time.

The read-only timestamp of when the `delay_action` is automatically applied,
in RFC 3339 format.

Note that this field is calculated by summing the payment's `delay_duration` and `created_at`
fields. The `created_at` field is generated by Square and might not exactly match the
time on your local machine.

Details about the device that took the payment.

The Square-issued installation ID for the device.

The name of the device set by the seller.

__Deprecated__: Use `Payment.team_member_id` instead.

An optional ID of the employee associated with taking the payment.

Stores details about an external payment. Contains only non-confidential information.
For more information, see 
[Take External Payments](https://developer.squareup.com/docs/payments-api/take-payments/external-payments).

A description of the external payment source. For example, 
"Food Delivery Service".

An ID to associate the payment to its originating source.

The type of external payment the seller received. It can be one of the following:
- CHECK - Paid using a physical check.
- BANK_TRANSFER - Paid using external bank transfer.
- OTHER\_GIFT\_CARD - Paid using a non-Square gift card.
- CRYPTO - Paid using a crypto currency.
- SQUARE_CASH - Paid using Square Cash App.
- SOCIAL - Paid using peer-to-peer payment applications.
- EXTERNAL - A third-party application gathered this payment outside of Square.
- EMONEY - Paid using an E-money provider.
- CARD - A credit or debit card that Square does not support.
- STORED_BALANCE - Use for house accounts, store credit, and so forth.
- FOOD_VOUCHER - Restaurant voucher provided by employers to employees to pay for meals
- OTHER - A type not listed here.

The ID of the location associated with the payment.

An optional note to include when creating a payment.

The ID of the order associated with the payment.

The processing fees and fee adjustments assessed by Square for this payment.

The payment's receipt number.
The field is missing if a payment is canceled.

The URL for the payment's receipt.
The field is only populated for COMPLETED payments.

An optional ID that associates the payment with an entity in
another system.

A list of `refund_id`s identifying refunds for the payment.

Represents fraud risk information for the associated payment.

When you take a payment through Square's Payments API (using the `CreatePayment`
endpoint), Square evaluates it and assigns a risk level to the payment. Sellers
can use this information to determine the course of action (for example,
provide the goods/services or refund the payment).

The timestamp when payment risk was evaluated, in RFC 3339 format.

The risk level associated with the payment

The source type for this payment.

Current values include `CARD`, `BANK_ACCOUNT`, `WALLET`, `BUY_NOW_PAY_LATER`, `SQUARE_ACCOUNT`,
`CASH` and `EXTERNAL`. For information about these payment source types,
see [Take Payments](https://developer.squareup.com/docs/payments-api/take-payments).

Additional details about Square Account payments.

Unique identifier for the payment source used for this payment.

Additional payment information that gets added to the customer's card statement
as part of the statement description.

Note that the `statement_description_identifier` might get truncated on the statement description
to fit the required information including the Square identifier (SQ *) and the name of the
seller taking the payment.

Indicates whether the payment is APPROVED, PENDING, COMPLETED, CANCELED, or FAILED.

An optional ID of the [TeamMember](https://developer.squareup.com/reference/square_2024-03-20/objects/TeamMember) associated with taking the payment.

The timestamp of when the payment was last updated, in RFC 3339 format.

Used for optimistic concurrency. This opaque token identifies a specific version of the
`Payment` object.

Additional details about `WALLET` type payments. Contains only non-confidential information.

The brand used for the `WALLET` payment. The brand can be `CASH_APP`, `PAYPAY`, `ALIPAY`,
`RAKUTEN_PAY`, `AU_PAY`, `D_BARAI`, `MERPAY`, `WECHAT_PAY` or `UNKNOWN`.

The status of the `WALLET` payment. The status can be `AUTHORIZED`, `CAPTURED`, `VOIDED`, or
`FAILED`.

Payments

Refunds

Transactions

Square

Generates code to authorize a mobile application to connect to a Square card reader.

Authorization codes are one-time-use codes and expire 60 minutes after being issued.

__Important:__ The `Authorization` header you provide to this endpoint must have the following format:

```
Authorization: Bearer ACCESS_TOKEN
```

Replace `ACCESS_TOKEN` with a
[valid production authorization credential](https://developer.squareup.com/docs/build-basics/access-tokens).

CreateMobileAuthorizationCode

`RenewToken` is deprecated. For information about refreshing OAuth access tokens, see
[Migrate from Renew to Refresh OAuth Tokens](https://developer.squareup.com/docs/oauth-api/migrate-to-refresh-tokens).

Renews an OAuth access token before it expires.

OAuth access tokens besides your application's personal access token expire after 30 days.
You can also renew expired tokens within 15 days of their expiration.
You cannot renew an access token that has been expired for more than 15 days.
Instead, the associated user must recomplete the OAuth flow from the beginning.

__Important:__ The `Authorization` header for this endpoint must have the
following format:

```
Authorization: Client APPLICATION_SECRET
```

Replace `APPLICATION_SECRET` with the application secret on the **Credentials**
page in the [Developer Dashboard](https://developer.squareup.com/apps).

RenewToken

Revokes an access token generated with the OAuth flow.

If an account has more than one OAuth access token for your application, this
endpoint revokes all of them, regardless of which token you specify. 

__Important:__ The `Authorization` header for this endpoint must have the
following format:

```
Authorization: Client APPLICATION_SECRET
```

Replace `APPLICATION_SECRET` with the application secret on the **OAuth**
page for your application in the Developer Dashboard.

RevokeToken

Returns an OAuth access token and a refresh token unless the 
`short_lived` parameter is set to `true`, in which case the endpoint 
returns only an access token.

The `grant_type` parameter specifies the type of OAuth request. If 
`grant_type` is `authorization_code`, you must include the authorization 
code you received when a seller granted you authorization. If `grant_type` 
is `refresh_token`, you must provide a valid refresh token. If you're using 
an old version of the Square APIs (prior to March 13, 2019), `grant_type` 
can be `migration_token` and you must provide a valid migration token.

You can use the `scopes` parameter to limit the set of permissions granted 
to the access token and refresh token. You can use the `short_lived` parameter 
to create an access token that expires in 24 hours.

__Note:__ OAuth tokens should be encrypted and stored on a secure server. 
Application clients should never interact directly with OAuth tokens.

ObtainToken

Returns information about an [OAuth access token](https://developer.squareup.com/docs/build-basics/access-tokens#get-an-oauth-access-token) or an application’s [personal access token](https://developer.squareup.com/docs/build-basics/access-tokens#get-a-personal-access-token).

Add the access token to the Authorization header of the request.

__Important:__ The `Authorization` header you provide to this endpoint must have the following format:

```
Authorization: Bearer ACCESS_TOKEN
```

where `ACCESS_TOKEN` is a
[valid production authorization credential](https://developer.squareup.com/docs/build-basics/access-tokens).

If the access token is expired or not a valid access token, the endpoint returns an `UNAUTHORIZED` error.

RetrieveTokenStatus

Provides summary information for a merchant's online store orders.

V1ListOrders

Provides comprehensive information for a single online store order, including the order's history.

V1RetrieveOrder

Updates the details of an online store order. Every update you perform on an order corresponds to one of three actions:

V1UpdateOrder

Activates a domain for use with Apple Pay on the Web and Square. A validation
is performed on this domain by Apple to ensure that it is properly set up as
an Apple Pay enabled domain.

This endpoint provides an easy way for platform developers to bulk activate
Apple Pay on the Web with Square for merchants using their platform.

Note: The SqPaymentForm library is deprecated as of May 13, 2021, and will only receive critical security updates until it is retired on October 31, 2022.
You must migrate your payment form code to the Web Payments SDK to continue using your domain for Apple Pay. For more information on migrating to the Web Payments SDK, see [Migrate to the Web Payments SDK](https://developer.squareup.com/docs/web-payments/migrate).

To learn more about the Web Payments SDK and how to add Apple Pay, see [Take an Apple Pay Payment](https://developer.squareup.com/docs/web-payments/apple-pay).

RegisterDomain

Returns a list of [BankAccount](https://developer.squareup.com/reference/square_2024-03-20/objects/BankAccount) objects linked to a Square account.

ListBankAccounts

Returns details of a [BankAccount](https://developer.squareup.com/reference/square_2024-03-20/objects/BankAccount) identified by V1 bank account ID.

GetBankAccountByV1Id

Returns details of a [BankAccount](https://developer.squareup.com/reference/square_2024-03-20/objects/BankAccount)
linked to a Square account.

GetBankAccount

Retrieve a collection of bookings.

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

ListBookings

Creates a booking.

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

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

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

CreateBooking

Searches for availabilities for booking.

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

SearchAvailability

Bulk-Retrieves a list of bookings by booking IDs.

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

BulkRetrieveBookings

RetrieveBusinessBookingProfile

Get all bookings custom attribute definitions.

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

ListBookingCustomAttributeDefinitions

Creates a bookings custom attribute definition.

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

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

CreateBookingCustomAttributeDefinition

Retrieves a bookings custom attribute definition.

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

RetrieveBookingCustomAttributeDefinition

Updates a bookings custom attribute definition.

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

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

UpdateBookingCustomAttributeDefinition

Deletes a bookings custom attribute definition.

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

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

DeleteBookingCustomAttributeDefinition

Bulk deletes bookings custom attributes.

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

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

BulkDeleteBookingCustomAttributes

Bulk upserts bookings custom attributes.

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

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

BulkUpsertBookingCustomAttributes

Lists location booking profiles of a seller.

ListLocationBookingProfiles

Retrieves a seller's location booking profile.

RetrieveLocationBookingProfile

ListTeamMemberBookingProfiles

Retrieves one or more team members' booking profiles.

BulkRetrieveTeamMemberBookingProfiles

Retrieves a team member's booking profile.

RetrieveTeamMemberBookingProfile

Retrieves a booking.

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

RetrieveBooking

Updates a booking.

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

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

UpdateBooking

Cancels an existing booking.

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

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

CancelBooking

Lists a booking's custom attributes.

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

ListBookingCustomAttributes

Retrieves a bookings custom attribute.

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

RetrieveBookingCustomAttribute

Upserts a bookings custom attribute.

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

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

UpsertBookingCustomAttribute

Deletes a bookings custom attribute.

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

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

DeleteBookingCustomAttribute

Retrieves a list of cards owned by the account making the request.
A max of 25 cards will be returned.

ListCards

Adds a card on file to an existing merchant.

CreateCard

RetrieveCard

Disables the card, preventing any further updates or charges.
Disabling an already disabled card is allowed but has no effect.

DisableCard

Provides the details for all of the cash drawer shifts for a location
in a date range.

ListCashDrawerShifts

Provides the summary details for a single cash drawer shift. See
[ListCashDrawerShiftEvents](https://developer.squareup.com/reference/square_2024-03-20/cash-drawers-api/list-cash-drawer-shift-events) for a list of cash drawer shift events.

RetrieveCashDrawerShift

Provides a paginated list of events for a single cash drawer shift.

ListCashDrawerShiftEvents

Deletes a set of [CatalogItem](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogItem)s based on the
provided list of target IDs and returns a set of successfully deleted IDs in
the response. Deletion is a cascading event such that all children of the
targeted object are also deleted. For example, deleting a CatalogItem will
also delete all of its [CatalogItemVariation](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogItemVariation)
children.

`BatchDeleteCatalogObjects` succeeds even if only a portion of the targeted
IDs can be deleted. The response will only include IDs that were
actually deleted.

To ensure consistency, only one delete request is processed at a time per seller account.  
While one (batch or non-batch) delete request is being processed, other (batched and non-batched) 
delete requests are rejected with the `429` error code.

BatchDeleteCatalogObjects

Returns a set of objects based on the provided ID.
Each [CatalogItem](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogItem) returned in the set includes all of its
child information including: all of its
[CatalogItemVariation](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogItemVariation) objects, references to
its [CatalogModifierList](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogModifierList) objects, and the ids of
any [CatalogTax](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogTax) objects that apply to it.

BatchRetrieveCatalogObjects

Creates or updates up to 10,000 target objects based on the provided
list of objects. The target objects are grouped into batches and each batch is
inserted/updated in an all-or-nothing manner. If an object within a batch is
malformed in some way, or violates a database constraint, the entire batch
containing that item will be disregarded. However, other batches in the same
request may still succeed. Each batch may contain up to 1,000 objects, and
batches will be processed in order as long as the total object count for the
request (items, variations, modifier lists, discounts, and taxes) is no more
than 10,000.

To ensure consistency, only one update request is processed at a time per seller account.  
While one (batch or non-batch) update request is being processed, other (batched and non-batched) 
update requests are rejected with the `429` error code.

BatchUpsertCatalogObjects

Retrieves information about the Square Catalog API, such as batch size
limits that can be used by the `BatchUpsertCatalogObjects` endpoint.

CatalogInfo

Returns a list of all [CatalogObject](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogObject)s of the specified types in the catalog. 

The `types` parameter is specified as a comma-separated list of the [CatalogObjectType](https://developer.squareup.com/reference/square_2024-03-20/enums/CatalogObjectType) values, 
for example, "`ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, `CATEGORY`, `DISCOUNT`, `TAX`, `IMAGE`".

__Important:__ ListCatalog does not return deleted catalog items. To retrieve
deleted catalog items, use [SearchCatalogObjects](https://developer.squareup.com/reference/square_2024-03-20/catalog-api/search-catalog-objects)
and set the `include_deleted_objects` attribute value to `true`.

ListCatalog

Creates a new or updates the specified [CatalogObject](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogObject).

To ensure consistency, only one update request is processed at a time per seller account.  
While one (batch or non-batch) update request is being processed, other (batched and non-batched) 
update requests are rejected with the `429` error code.

UpsertCatalogObject

Returns a single [CatalogItem](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogItem) as a
[CatalogObject](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogObject) based on the provided ID. The returned
object includes all of the relevant [CatalogItem](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogItem)
information including: [CatalogItemVariation](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogItemVariation)
children, references to its
[CatalogModifierList](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogModifierList) objects, and the ids of
any [CatalogTax](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogTax) objects that apply to it.

RetrieveCatalogObject

Deletes a single [CatalogObject](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogObject) based on the
provided ID and returns the set of successfully deleted IDs in the response.
Deletion is a cascading event such that all children of the targeted object
are also deleted. For example, deleting a [CatalogItem](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogItem)
will also delete all of its
[CatalogItemVariation](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogItemVariation) children.

To ensure consistency, only one delete request is processed at a time per seller account.  
While one (batch or non-batch) delete request is being processed, other (batched and non-batched) 
delete requests are rejected with the `429` error code.

DeleteCatalogObject

Searches for [CatalogObject](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogObject) of any type by matching supported search attribute values,
excluding custom attribute values on items or item variations, against one or more of the specified query filters.

This (`SearchCatalogObjects`) endpoint differs from the [SearchCatalogItems](https://developer.squareup.com/reference/square_2024-03-20/catalog-api/search-catalog-items)
endpoint in the following aspects:

- `SearchCatalogItems` can only search for items or item variations, whereas `SearchCatalogObjects` can search for any type of catalog objects.
- `SearchCatalogItems` supports the custom attribute query filters to return items or item variations that contain custom attribute values, where `SearchCatalogObjects` does not.
- `SearchCatalogItems` does not support the `include_deleted_objects` filter to search for deleted items or item variations, whereas `SearchCatalogObjects` does.
- The both endpoints have different call conventions, including the query filter formats.

SearchCatalogObjects

Searches for catalog items or item variations by matching supported search attribute values, including
custom attribute values, against one or more of the specified query filters.

This (`SearchCatalogItems`) endpoint differs from the [SearchCatalogObjects](https://developer.squareup.com/reference/square_2024-03-20/catalog-api/search-catalog-objects)
endpoint in the following aspects:

- `SearchCatalogItems` can only search for items or item variations, whereas `SearchCatalogObjects` can search for any type of catalog objects.
- `SearchCatalogItems` supports the custom attribute query filters to return items or item variations that contain custom attribute values, where `SearchCatalogObjects` does not.
- `SearchCatalogItems` does not support the `include_deleted_objects` filter to search for deleted items or item variations, whereas `SearchCatalogObjects` does.
- The both endpoints use different call conventions, including the query filter formats.

SearchCatalogItems

Updates the [CatalogModifierList](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogModifierList) objects
that apply to the targeted [CatalogItem](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogItem) without having
to perform an upsert on the entire item.

UpdateItemModifierLists

Updates the [CatalogTax](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogTax) objects that apply to the
targeted [CatalogItem](https://developer.squareup.com/reference/square_2024-03-20/objects/CatalogItem) without having to perform an
upsert on the entire item.

UpdateItemTaxes

Lists customer profiles associated with a Square account.

Under normal operating conditions, newly created or updated customer profiles become available
for the listing operation in well under 30 seconds. Occasionally, propagation of the new or updated
profiles can take closer to one minute or longer, especially during network incidents and outages.

ListCustomers

Creates a new customer for a business.

You must provide at least one of the following values in your request to this
endpoint:

- `given_name`
- `family_name`
- `company_name`
- `email_address`
- `phone_number`

CreateCustomer

Creates multiple [customer profiles](https://developer.squareup.com/reference/square_2024-03-20/objects/Customer) for a business.

This endpoint takes a map of individual create requests and returns a map of responses.

You must provide at least one of the following values in each create request:

- `given_name`
- `family_name`
- `company_name`
- `email_address`
- `phone_number`

BulkCreateCustomers

Deletes multiple customer profiles.

The endpoint takes a list of customer IDs and returns a map of responses.

Field Name	API Key	Type
Id	id	string
Created At	created_at	string
Updated At	updated_at	string
Given Name	given_name	string
Family Name	family_name	string

Square API Integration Profile

How to work with Customers in Square API

Operations on Customers Collection

Build every single integration your customers need with AI