Skip to content
Changelog

Report a bug

Square integration: operations for AI agents

Square connects to Type.com as an integration. This page lists the 332 operations documented for Claude and Codex in Type.com: 158 read, 82 write, 92 destructive.

About Square

Square provides payment processing, POS systems, invoicing, and e-commerce tools, enabling sellers to accept card payments and manage their business

Categories: Commerce & Payments

How to connect Square to Type.com

Access
Organization connection: one shared account for the workspace.
MCP
This integration is not available through Type’s MCP server. It remains available in Type.

To add the connection, follow the steps in Space connections.

Documented operations

332 operations. Your connection's permissions determine which operations are available. API references describe the vendor surface; they do not expand your connection's credentials or access.

332 operations listed.

OAuth

  • Read

    RetrieveTokenStatus

    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.

    POST /oauth2/token/status

  • Write

    ObtainToken

    Returns an OAuth access token and refresh token using the `authorization_code` or `refresh_token` grant type. When `grant_type` is `authorization_code`: - With the [code flow](https://developer.squareup.com/docs/oauth-api/overview#code-flow), provide `code`, `client_id`, and `client_secret`. - With the [PKCE flow](https://developer.squareup.com/docs/oauth-api/overview#pkce-flow), provide `code`, `client_id`, and `code_verifier`. When `grant_type` is `refresh_token`: - With the code flow, provide `refresh_token`, `client_id`, and `client_secret`. The response returns the same refresh token provided in the request. - With the PKCE flow, provide `refresh_token` and `client_id`. The response returns a new refresh token. You can use the `scopes` parameter to limit the set of permissions authorized by the access token. You can use the `short_lived` parameter to create an access token that expires in 24 hours. __Important:__ OAuth tokens should be encrypted and stored on a secure server. Application clients should never interact directly with OAuth tokens.

    POST /oauth2/token

  • Destructive

    RevokeToken

    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.

    POST /oauth2/revoke

V1Transactions

  • Read

    V1ListOrders (deprecated)

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

    GET /v1/{location_id}/orders

  • Read

    V1RetrieveOrder (deprecated)

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

    GET /v1/{location_id}/orders/{order_id}

  • Destructive

    V1UpdateOrder (deprecated)

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

    PUT /v1/{location_id}/orders/{order_id}

Apple Pay

  • Write

    RegisterDomain

    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: You will need to host a valid domain verification file on your domain to support Apple Pay. The current version of this file is always available at https://app.squareup.com/digital-wallets/apple-pay/apple-developer-merchantid-domain-association, and should be hosted at `.well_known/apple-developer-merchantid-domain-association` on your domain. This file is subject to change; we strongly recommend checking for updates regularly and avoiding long-lived caches that might not keep in sync with the correct file version. 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).

    POST /v2/apple-pay/domains

Bank Accounts

  • Read

    ListBankAccounts

    Returns a list of [BankAccount](entity:BankAccount) objects linked to a Square account.

    GET /v2/bank-accounts

  • Read

    GetBankAccountByV1Id

    Returns details of a [BankAccount](entity:BankAccount) identified by V1 bank account ID.

    GET /v2/bank-accounts/by-v1-id/{v1_bank_account_id}

  • Read

    GetBankAccount

    Retrieve details of a [BankAccount](entity:BankAccount) bank account linked to a Square account.

    GET /v2/bank-accounts/{bank_account_id}

  • Write

    CreateBankAccount

    Store a bank account on file for a square account

    POST /v2/bank-accounts

  • Destructive

    DisableBankAccount

    Disable a bank account.

    POST /v2/bank-accounts/{bank_account_id}/disable

Bookings

  • Read

    ListBookings

    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.

    GET /v2/bookings

  • Read

    SearchAvailability

    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.

    POST /v2/bookings/availability/search

  • Read

    BulkRetrieveBookings

    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.

    POST /v2/bookings/bulk-retrieve

  • Read

    RetrieveBusinessBookingProfile

    Retrieves a seller's booking profile.

    GET /v2/bookings/business-booking-profile

  • Read

    ListLocationBookingProfiles

    Lists location booking profiles of a seller.

    GET /v2/bookings/location-booking-profiles

  • Read

    RetrieveLocationBookingProfile

    Retrieves a seller's location booking profile.

    GET /v2/bookings/location-booking-profiles/{location_id}

  • Read

    ListTeamMemberBookingProfiles

    Lists booking profiles for team members.

    GET /v2/bookings/team-member-booking-profiles

  • Read

    BulkRetrieveTeamMemberBookingProfiles

    Retrieves one or more team members' booking profiles.

    POST /v2/bookings/team-member-booking-profiles/bulk-retrieve

  • Read

    RetrieveTeamMemberBookingProfile

    Retrieves a team member's booking profile.

    GET /v2/bookings/team-member-booking-profiles/{team_member_id}

  • Read

    RetrieveBooking

    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.

    GET /v2/bookings/{booking_id}

  • Write

    CreateBooking

    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*.

    POST /v2/bookings

  • Destructive

    UpdateBooking

    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*.

    PUT /v2/bookings/{booking_id}

  • Destructive

    CancelBooking

    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*.

    POST /v2/bookings/{booking_id}/cancel

Booking Custom Attributes

  • Read

    ListBookingCustomAttributeDefinitions

    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.

    GET /v2/bookings/custom-attribute-definitions

  • Read

    RetrieveBookingCustomAttributeDefinition

    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.

    GET /v2/bookings/custom-attribute-definitions/{key}

  • Read

    ListBookingCustomAttributes

    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.

    GET /v2/bookings/{booking_id}/custom-attributes

  • Read

    RetrieveBookingCustomAttribute

    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.

    GET /v2/bookings/{booking_id}/custom-attributes/{key}

  • Write

    CreateBookingCustomAttributeDefinition

    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*.

    POST /v2/bookings/custom-attribute-definitions

  • Write

    BulkUpsertBookingCustomAttributes

    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*.

    POST /v2/bookings/custom-attributes/bulk-upsert

  • Destructive

    DeleteBookingCustomAttributeDefinition

    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*.

    DELETE /v2/bookings/custom-attribute-definitions/{key}

  • Destructive

    UpdateBookingCustomAttributeDefinition

    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*.

    PUT /v2/bookings/custom-attribute-definitions/{key}

  • Destructive

    BulkDeleteBookingCustomAttributes

    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*.

    POST /v2/bookings/custom-attributes/bulk-delete

  • Destructive

    DeleteBookingCustomAttribute

    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*.

    DELETE /v2/bookings/{booking_id}/custom-attributes/{key}

  • Destructive

    UpsertBookingCustomAttribute

    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*.

    PUT /v2/bookings/{booking_id}/custom-attributes/{key}

Cards

  • Read

    ListCards

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

    GET /v2/cards

  • Read

    RetrieveCard

    Retrieves details for a specific Card.

    GET /v2/cards/{card_id}

  • Write

    CreateCard

    Adds a card on file to an existing merchant.

    POST /v2/cards

  • Destructive

    DisableCard

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

    POST /v2/cards/{card_id}/disable

Cash Drawers

  • Read

    ListCashDrawerShifts

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

    GET /v2/cash-drawers/shifts

  • Read

    RetrieveCashDrawerShift

    Provides the summary details for a single cash drawer shift. See [ListCashDrawerShiftEvents](api-endpoint:CashDrawers-ListCashDrawerShiftEvents) for a list of cash drawer shift events.

    GET /v2/cash-drawers/shifts/{shift_id}

  • Read

    ListCashDrawerShiftEvents

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

    GET /v2/cash-drawers/shifts/{shift_id}/events

Catalog

  • Read

    BatchRetrieveCatalogObjects

    Returns a set of objects based on the provided ID. Each [CatalogItem](entity:CatalogItem) returned in the set includes all of its child information including: all of its [CatalogItemVariation](entity:CatalogItemVariation) objects, references to its [CatalogModifierList](entity:CatalogModifierList) objects, and the ids of any [CatalogTax](entity:CatalogTax) objects that apply to it.

    POST /v2/catalog/batch-retrieve

  • Read

    CatalogInfo

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

    GET /v2/catalog/info

  • Read

    ListCatalog

    Returns a list of all [CatalogObject](entity:CatalogObject)s of the specified types in the catalog. The `types` parameter is specified as a comma-separated list of the [CatalogObjectType](entity:CatalogObjectType) values, for example, "`ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, `CATEGORY`, `DISCOUNT`, `TAX`, `IMAGE`". Always specify `types` explicitly. When upgrading to a newer API version, omitting `types` may cause new object types to appear in results that were not returned under the previous version. __Important:__ ListCatalog does not return deleted catalog items. To retrieve deleted catalog items, use [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects) and set the `include_deleted_objects` attribute value to `true`.

    GET /v2/catalog/list

  • Read

    RetrieveCatalogObject

    Returns a single [CatalogItem](entity:CatalogItem) as a [CatalogObject](entity:CatalogObject) based on the provided ID. The returned object includes all of the relevant [CatalogItem](entity:CatalogItem) information including: [CatalogItemVariation](entity:CatalogItemVariation) children, references to its [CatalogModifierList](entity:CatalogModifierList) objects, and the ids of any [CatalogTax](entity:CatalogTax) objects that apply to it.

    GET /v2/catalog/object/{object_id}

  • Read

    SearchCatalogObjects

    Searches for [CatalogObject](entity: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](api-endpoint:Catalog-SearchCatalogItems) 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. The `object_types` parameter is specified as a list of [CatalogObjectType](entity:CatalogObjectType) values. Always specify `object_types` explicitly. When upgrading to a newer API version, omitting `object_types` may cause new object types to appear in results that were not returned under the previous version.

    POST /v2/catalog/search

  • Read

    SearchCatalogItems

    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](api-endpoint:Catalog-SearchCatalogObjects) 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.

    POST /v2/catalog/search-catalog-items

  • Write

    CreateCatalogImage

    Uploads an image file to be represented by a [CatalogImage](entity:CatalogImage) object that can be linked to an existing [CatalogObject](entity:CatalogObject) instance. The resulting `CatalogImage` is unattached to any `CatalogObject` if the `object_id` is not specified. This `CreateCatalogImage` endpoint accepts HTTP multipart/form-data requests with a JSON part and an image file part in JPEG, PJPEG, PNG, or GIF format. The maximum file size is 15MB.

    POST /v2/catalog/images

  • Write

    UpdateItemModifierLists

    Updates the [CatalogModifierList](entity:CatalogModifierList) objects that apply to the targeted [CatalogItem](entity:CatalogItem) without having to perform an upsert on the entire item.

    POST /v2/catalog/update-item-modifier-lists

  • Write

    UpdateItemTaxes

    Updates the [CatalogTax](entity:CatalogTax) objects that apply to the targeted [CatalogItem](entity:CatalogItem) without having to perform an upsert on the entire item.

    POST /v2/catalog/update-item-taxes

  • Destructive

    BatchDeleteCatalogObjects

    Deletes a set of [CatalogItem](entity: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](entity: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.

    POST /v2/catalog/batch-delete

  • Destructive

    BatchUpsertCatalogObjects

    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. This endpoint uses full-replacement semantics. The client must send the complete object, and any field absent from the request is interpreted as an intentional clear. This logic applies to nested objects as well. For example, omitting inlined children like variations will delete them. 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. Prefer batching related changes into a single call rather than issuing many small writes, since each write acquires the lock separately and parallel writes to the same seller will contend with each other, producing `429` errors.

    POST /v2/catalog/batch-upsert

  • Destructive

    UpdateCatalogImage

    Uploads a new image file to replace the existing one in the specified [CatalogImage](entity:CatalogImage) object. This `UpdateCatalogImage` endpoint accepts HTTP multipart/form-data requests with a JSON part and an image file part in JPEG, PJPEG, PNG, or GIF format. The maximum file size is 15MB.

    PUT /v2/catalog/images/{image_id}

  • Destructive

    UpsertCatalogObject

    Creates a new or updates the specified [CatalogObject](entity:CatalogObject). This endpoint uses full-replacement semantics. The client must send the complete object, and any field absent from the request is interpreted as an intentional clear. This logic applies to nested objects as well. For example, omitting inlined children like variations will delete them. 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.

    POST /v2/catalog/object

  • Destructive

    DeleteCatalogObject

    Deletes a single [CatalogObject](entity: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](entity:CatalogItem) will also delete all of its [CatalogItemVariation](entity: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.

    DELETE /v2/catalog/object/{object_id}

Channels

  • Read

    ListChannels

    GET /v2/channels

    GET /v2/channels

  • Read

    BulkRetrieveChannels

    POST /v2/channels/bulk-retrieve

    POST /v2/channels/bulk-retrieve

  • Read

    RetrieveChannel

    GET /v2/channels/{channel_id}

    GET /v2/channels/{channel_id}

Customers

  • Read

    ListCustomers

    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.

    GET /v2/customers

  • Read

    BulkRetrieveCustomers

    Retrieves multiple customer profiles. This endpoint takes a list of customer IDs and returns a map of responses.

    POST /v2/customers/bulk-retrieve

  • Read

    SearchCustomers

    Searches the customer profiles associated with a Square account using one or more supported query filters. Calling `SearchCustomers` without any explicit query filter returns all customer profiles ordered alphabetically based on `given_name` and `family_name`. Under normal operating conditions, newly created or updated customer profiles become available for the search 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.

    POST /v2/customers/search

  • Read

    RetrieveCustomer

    Returns details for a single customer.

    GET /v2/customers/{customer_id}

  • Write

    CreateCustomer

    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`

    POST /v2/customers

  • Write

    BulkCreateCustomers

    Creates multiple [customer profiles](entity: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`

    POST /v2/customers/bulk-create

  • Write

    CreateCustomerCard (deprecated)

    Adds a card on file to an existing customer. As with charges, calls to `CreateCustomerCard` are idempotent. Multiple calls with the same card nonce return the same card record that was created with the provided nonce during the _first_ call.

    POST /v2/customers/{customer_id}/cards

  • Destructive

    BulkDeleteCustomers

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

    POST /v2/customers/bulk-delete

  • Destructive

    BulkUpdateCustomers

    Updates multiple customer profiles. This endpoint takes a map of individual update requests and returns a map of responses.

    POST /v2/customers/bulk-update

  • Destructive

    DeleteCustomer

    Deletes a customer profile from a business. To delete a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile.

    DELETE /v2/customers/{customer_id}

  • Destructive

    UpdateCustomer

    Updates a customer profile. This endpoint supports sparse updates, so only new or changed fields are required in the request. To add or update a field, specify the new value. To remove a field, specify `null`. To update a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile.

    PUT /v2/customers/{customer_id}

  • Destructive

    DeleteCustomerCard (deprecated)

    Removes a card on file from a customer.

    DELETE /v2/customers/{customer_id}/cards/{card_id}

  • Destructive

    RemoveGroupFromCustomer

    Removes a group membership from a customer. The customer is identified by the `customer_id` value and the customer group is identified by the `group_id` value.

    DELETE /v2/customers/{customer_id}/groups/{group_id}

  • Destructive

    AddGroupToCustomer

    Adds a group membership to a customer. The customer is identified by the `customer_id` value and the customer group is identified by the `group_id` value.

    PUT /v2/customers/{customer_id}/groups/{group_id}

Customer Custom Attributes

  • Read

    ListCustomerCustomAttributeDefinitions

    Lists the customer-related [custom attribute definitions](entity:CustomAttributeDefinition) that belong to a Square seller account. When all response pages are retrieved, the results include all custom attribute definitions that are visible to the requesting application, including those that are created by other applications and set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes (also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.

    GET /v2/customers/custom-attribute-definitions

  • Read

    RetrieveCustomerCustomAttributeDefinition

    Retrieves a customer-related [custom attribute definition](entity:CustomAttributeDefinition) from a Square seller account. To retrieve a custom attribute definition created by another application, the `visibility` setting must be `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes (also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.

    GET /v2/customers/custom-attribute-definitions/{key}

  • Read

    ListCustomerCustomAttributes

    Lists the [custom attributes](entity:CustomAttribute) associated with a customer profile. You can use the `with_definitions` query parameter to also retrieve custom attribute definitions in the same call. When all response pages are retrieved, the results include all custom attributes that are visible to the requesting application, including those that are owned by other applications and set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.

    GET /v2/customers/{customer_id}/custom-attributes

  • Read

    RetrieveCustomerCustomAttribute

    Retrieves a [custom attribute](entity:CustomAttribute) associated with a customer profile. You can use the `with_definition` query parameter to also retrieve the custom attribute definition in the same call. To retrieve a custom attribute owned by another application, the `visibility` setting must be `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes (also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.

    GET /v2/customers/{customer_id}/custom-attributes/{key}

  • Write

    CreateCustomerCustomAttributeDefinition

    Creates a customer-related [custom attribute definition](entity:CustomAttributeDefinition) for a Square seller account. Use this endpoint to define a custom attribute that can be associated with customer profiles. A custom attribute definition specifies the `key`, `visibility`, `schema`, and other properties for a custom attribute. After the definition is created, you can call [UpsertCustomerCustomAttribute](api-endpoint:CustomerCustomAttributes-UpsertCustomerCustomAttribute) or [BulkUpsertCustomerCustomAttributes](api-endpoint:CustomerCustomAttributes-BulkUpsertCustomerCustomAttributes) to set the custom attribute for customer profiles in the seller's Customer Directory. Sellers can view all custom attributes in exported customer data, including those set to `VISIBILITY_HIDDEN`.

    POST /v2/customers/custom-attribute-definitions

  • Write

    BulkUpsertCustomerCustomAttributes

    Creates or updates [custom attributes](entity:CustomAttribute) for customer profiles as a bulk operation. Use this endpoint to set the value of one or more custom attributes for one or more customer profiles. A custom attribute is based on a custom attribute definition in a Square seller account, which is created using the [CreateCustomerCustomAttributeDefinition](api-endpoint:CustomerCustomAttributes-CreateCustomerCustomAttributeDefinition) endpoint. This `BulkUpsertCustomerCustomAttributes` endpoint accepts a map of 1 to 25 individual upsert requests and returns a map of individual upsert responses. Each upsert request has a unique ID and provides a customer ID and custom attribute. Each upsert response is returned with the ID of the corresponding request. To create or update a custom attribute owned by another application, the `visibility` setting must be `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes (also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.

    POST /v2/customers/custom-attributes/bulk-upsert

  • Write

    UpsertCustomerCustomAttribute

    Creates or updates a [custom attribute](entity:CustomAttribute) for a customer profile. Use this endpoint to set the value of a custom attribute for a specified customer profile. A custom attribute is based on a custom attribute definition in a Square seller account, which is created using the [CreateCustomerCustomAttributeDefinition](api-endpoint:CustomerCustomAttributes-CreateCustomerCustomAttributeDefinition) endpoint. To create or update a custom attribute owned by another application, the `visibility` setting must be `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes (also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.

    POST /v2/customers/{customer_id}/custom-attributes/{key}

  • Destructive

    DeleteCustomerCustomAttributeDefinition

    Deletes a customer-related [custom attribute definition](entity:CustomAttributeDefinition) from a Square seller account. Deleting a custom attribute definition also deletes the corresponding custom attribute from all customer profiles in the seller's Customer Directory. Only the definition owner can delete a custom attribute definition.

    DELETE /v2/customers/custom-attribute-definitions/{key}

  • Destructive

    UpdateCustomerCustomAttributeDefinition

    Updates a customer-related [custom attribute definition](entity:CustomAttributeDefinition) for a Square seller account. Use this endpoint to update the following fields: `name`, `description`, `visibility`, or the `schema` for a `Selection` data type. Only the definition owner can update a custom attribute definition. Note that sellers can view all custom attributes in exported customer data, including those set to `VISIBILITY_HIDDEN`.

    PUT /v2/customers/custom-attribute-definitions/{key}

  • Destructive

    DeleteCustomerCustomAttribute

    Deletes a [custom attribute](entity:CustomAttribute) associated with a customer profile. To delete a custom attribute owned by another application, the `visibility` setting must be `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes (also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.

    DELETE /v2/customers/{customer_id}/custom-attributes/{key}

Customer Groups

  • Read

    ListCustomerGroups

    Retrieves the list of customer groups of a business.

    GET /v2/customers/groups

  • Read

    RetrieveCustomerGroup

    Retrieves a specific customer group as identified by the `group_id` value.

    GET /v2/customers/groups/{group_id}

  • Write

    CreateCustomerGroup

    Creates a new customer group for a business. The request must include the `name` value of the group.

    POST /v2/customers/groups

  • Destructive

    DeleteCustomerGroup

    Deletes a customer group as identified by the `group_id` value.

    DELETE /v2/customers/groups/{group_id}

  • Destructive

    UpdateCustomerGroup

    Updates a customer group as identified by the `group_id` value.

    PUT /v2/customers/groups/{group_id}

Customer Segments

  • Read

    ListCustomerSegments

    Retrieves the list of customer segments of a business.

    GET /v2/customers/segments

  • Read

    RetrieveCustomerSegment

    Retrieves a specific customer segment as identified by the `segment_id` value.

    GET /v2/customers/segments/{segment_id}

Devices

  • Read

    ListDevices

    List devices associated with the merchant. Currently, only Terminal API devices are supported.

    GET /v2/devices

  • Read

    ListDeviceCodes

    Lists all DeviceCodes associated with the merchant.

    GET /v2/devices/codes

  • Read

    GetDeviceCode

    Retrieves DeviceCode with the associated ID.

    GET /v2/devices/codes/{id}

  • Read

    GetDevice

    Retrieves Device with the associated `device_id`.

    GET /v2/devices/{device_id}

  • Write

    CreateDeviceCode

    Creates a DeviceCode that can be used to login to a Square Terminal device to enter the connected terminal mode.

    POST /v2/devices/codes

Disputes

  • Read

    ListDisputes

    Returns a list of disputes associated with a particular account.

    GET /v2/disputes

  • Read

    RetrieveDispute

    Returns details about a specific dispute.

    GET /v2/disputes/{dispute_id}

  • Read

    ListDisputeEvidence

    Returns a list of evidence associated with a dispute.

    GET /v2/disputes/{dispute_id}/evidence

  • Read

    RetrieveDisputeEvidence

    Returns the metadata for the evidence specified in the request URL path. You must maintain a copy of any evidence uploaded if you want to reference it later. Evidence cannot be downloaded after you upload it.

    GET /v2/disputes/{dispute_id}/evidence/{evidence_id}

  • Write

    AcceptDispute

    Accepts the loss on a dispute. Square returns the disputed amount to the cardholder and updates the dispute state to ACCEPTED. Square debits the disputed amount from the seller’s Square account. If the Square account does not have sufficient funds, Square debits the associated bank account.

    POST /v2/disputes/{dispute_id}/accept

  • Write

    CreateDisputeEvidenceFile

    Uploads a file to use as evidence in a dispute challenge. The endpoint accepts HTTP multipart/form-data file uploads in HEIC, HEIF, JPEG, PDF, PNG, and TIFF formats.

    POST /v2/disputes/{dispute_id}/evidence-files

  • Write

    CreateDisputeEvidenceText

    Uploads text to use as evidence for a dispute challenge.

    POST /v2/disputes/{dispute_id}/evidence-text

  • Destructive

    DeleteDisputeEvidence

    Removes specified evidence from a dispute. Square does not send the bank any evidence that is removed.

    DELETE /v2/disputes/{dispute_id}/evidence/{evidence_id}

  • Destructive

    SubmitEvidence

    Submits evidence to the cardholder's bank. The evidence submitted by this endpoint includes evidence uploaded using the [CreateDisputeEvidenceFile](api-endpoint:Disputes-CreateDisputeEvidenceFile) and [CreateDisputeEvidenceText](api-endpoint:Disputes-CreateDisputeEvidenceText) endpoints and evidence automatically provided by Square, when available. Evidence cannot be removed from a dispute after submission.

    POST /v2/disputes/{dispute_id}/submit-evidence

Employees

  • Read

    ListEmployees (deprecated)

    ListEmployees

    GET /v2/employees

  • Read

    RetrieveEmployee (deprecated)

    RetrieveEmployee

    GET /v2/employees/{id}

Events

  • Read

    SearchEvents

    Search for Square API events that occur within a 28-day timeframe.

    POST /v2/events

  • Read

    ListEventTypes

    Lists all event types that you can subscribe to as webhooks or query using the Events API.

    GET /v2/events/types

  • Destructive

    DisableEvents

    Disables events to prevent them from being searchable. All events are disabled by default. You must enable events to make them searchable. Disabling events for a specific time period prevents them from being searchable, even if you re-enable them later.

    PUT /v2/events/disable

  • Destructive

    EnableEvents

    Enables events to make them searchable. Only events that occur while in the enabled state are searchable.

    PUT /v2/events/enable

Gift Cards

  • Read

    ListGiftCards

    Lists all gift cards. You can specify optional filters to retrieve a subset of the gift cards. Results are sorted by `created_at` in ascending order.

    GET /v2/gift-cards

  • Read

    RetrieveGiftCardFromGAN

    Retrieves a gift card using the gift card account number (GAN).

    POST /v2/gift-cards/from-gan

  • Read

    RetrieveGiftCardFromNonce

    Retrieves a gift card using a secure payment token that represents the gift card.

    POST /v2/gift-cards/from-nonce

  • Read

    RetrieveGiftCard

    Retrieves a gift card using the gift card ID.

    GET /v2/gift-cards/{id}

  • Write

    CreateGiftCard

    Creates a digital gift card or registers a physical (plastic) gift card. The resulting gift card has a `PENDING` state. To activate a gift card so that it can be redeemed for purchases, call [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) and create an `ACTIVATE` activity with the initial balance. Alternatively, you can use [RefundPayment](api-endpoint:Refunds-RefundPayment) to refund a payment to the new gift card.

    POST /v2/gift-cards

  • Write

    LinkCustomerToGiftCard

    Links a customer to a gift card, which is also referred to as adding a card on file.

    POST /v2/gift-cards/{gift_card_id}/link-customer

  • Write

    UnlinkCustomerFromGiftCard

    Unlinks a customer from a gift card, which is also referred to as removing a card on file.

    POST /v2/gift-cards/{gift_card_id}/unlink-customer

Gift Card Activities

  • Read

    ListGiftCardActivities

    Lists gift card activities. By default, you get gift card activities for all gift cards in the seller's account. You can optionally specify query parameters to filter the list. For example, you can get a list of gift card activities for a gift card, for all gift cards in a specific region, or for activities within a time window.

    GET /v2/gift-cards/activities

  • Destructive

    CreateGiftCardActivity

    Creates a gift card activity to manage the balance or state of a [gift card](entity:GiftCard). For example, create an `ACTIVATE` activity to activate a gift card with an initial balance before first use.

    POST /v2/gift-cards/activities

Inventory

  • Read

    ListInventoryAdjustmentReasons

    Returns the standard and custom inventory adjustment reasons available to the seller.

    GET /v2/inventory/adjustment-reasons

  • Read

    RetrieveInventoryAdjustmentReason

    Returns the inventory adjustment reason identified by the provided `reason_id`. Deleted custom reasons can be retrieved by ID.

    POST /v2/inventory/adjustment-reasons/retrieve

  • Read

    DeprecatedRetrieveInventoryAdjustment (deprecated)

    Deprecated version of [RetrieveInventoryAdjustment](api-endpoint:Inventory-RetrieveInventoryAdjustment) after the endpoint URL is updated to conform to the standard convention.

    GET /v2/inventory/adjustment/{adjustment_id}

  • Read

    RetrieveInventoryAdjustment

    Returns the [InventoryAdjustment](entity:InventoryAdjustment) object with the provided `adjustment_id`.

    GET /v2/inventory/adjustments/{adjustment_id}

  • Read

    DeprecatedBatchRetrieveInventoryChanges (deprecated)

    Deprecated version of [BatchRetrieveInventoryChanges](api-endpoint:Inventory-BatchRetrieveInventoryChanges) after the endpoint URL is updated to conform to the standard convention.

    POST /v2/inventory/batch-retrieve-changes

  • Read

    DeprecatedBatchRetrieveInventoryCounts (deprecated)

    Deprecated version of [BatchRetrieveInventoryCounts](api-endpoint:Inventory-BatchRetrieveInventoryCounts) after the endpoint URL is updated to conform to the standard convention.

    POST /v2/inventory/batch-retrieve-counts

  • Read

    BatchRetrieveInventoryChanges

    Returns historical physical counts and adjustments based on the provided filter criteria. Results are paginated and sorted in ascending order according their `occurred_at` timestamp (oldest first). BatchRetrieveInventoryChanges is a catch-all query endpoint for queries that cannot be handled by other, simpler endpoints.

    POST /v2/inventory/changes/batch-retrieve

  • Read

    BatchRetrieveInventoryCounts

    Returns current counts for the provided [CatalogObject](entity:CatalogObject)s at the requested [Location](entity:Location)s. Results are paginated and sorted in descending order according to their `calculated_at` timestamp (newest first). When `updated_after` is specified, only counts that have changed since that time (based on the server timestamp for the most recent change) are returned. This allows clients to perform a "sync" operation, for example in response to receiving a Webhook notification.

    POST /v2/inventory/counts/batch-retrieve

  • Read

    DeprecatedRetrieveInventoryPhysicalCount (deprecated)

    Deprecated version of [RetrieveInventoryPhysicalCount](api-endpoint:Inventory-RetrieveInventoryPhysicalCount) after the endpoint URL is updated to conform to the standard convention.

    GET /v2/inventory/physical-count/{physical_count_id}

  • Read

    RetrieveInventoryPhysicalCount

    Returns the [InventoryPhysicalCount](entity:InventoryPhysicalCount) object with the provided `physical_count_id`.

    GET /v2/inventory/physical-counts/{physical_count_id}

  • Read

    RetrieveInventoryCount

    Retrieves the current calculated stock count for a given [CatalogObject](entity:CatalogObject) at a given set of [Location](entity:Location)s. Responses are paginated and unsorted. For more sophisticated queries, use a batch endpoint.

    GET /v2/inventory/{catalog_object_id}

  • Read

    RetrieveInventoryChanges (deprecated)

    Returns a set of physical counts and inventory adjustments for the provided [CatalogObject](entity:CatalogObject) at the requested [Location](entity:Location)s. You can achieve the same result by calling [BatchRetrieveInventoryChanges](api-endpoint:Inventory-BatchRetrieveInventoryChanges) and having the `catalog_object_ids` list contain a single element of the `CatalogObject` ID. Results are paginated and sorted in descending order according to their `occurred_at` timestamp (newest first). There are no limits on how far back the caller can page. This endpoint can be used to display recent changes for a specific item. For more sophisticated queries, use a batch endpoint.

    GET /v2/inventory/{catalog_object_id}/changes

  • Write

    CreateInventoryAdjustmentReason

    Creates a custom inventory adjustment reason.

    POST /v2/inventory/adjustment-reasons/create

  • Write

    RestoreInventoryAdjustmentReason

    Restores a soft-deleted custom inventory adjustment reason.

    POST /v2/inventory/adjustment-reasons/restore

  • Write

    DeprecatedBatchChangeInventory (deprecated)

    Deprecated version of [BatchChangeInventory](api-endpoint:Inventory-BatchChangeInventory) after the endpoint URL is updated to conform to the standard convention.

    POST /v2/inventory/batch-change

  • Write

    BatchChangeInventory

    Applies adjustments and counts to the provided item quantities. On success: returns the current calculated counts for all objects referenced in the request. On failure: returns a list of related errors.

    POST /v2/inventory/changes/batch-create

  • Destructive

    DeleteInventoryAdjustmentReason

    Soft deletes a custom inventory adjustment reason.

    POST /v2/inventory/adjustment-reasons/delete

  • Destructive

    UpdateInventoryAdjustmentReason

    Updates a custom inventory adjustment reason.

    PUT /v2/inventory/adjustment-reasons/update

  • Destructive

    UpdateInventoryAdjustment

    Applies an update to the provided adjustment. On success: returns the newly updated adjustment. On failure: returns a list of related errors.

    PUT /v2/inventory/adjustments/update

Invoices

  • Read

    ListInvoices

    Returns a list of invoices for a given location. The response is paginated. If truncated, the response includes a `cursor` that you use in a subsequent request to retrieve the next set of invoices.

    GET /v2/invoices

  • Read

    SearchInvoices

    Searches for invoices from a location specified in the filter. You can optionally specify customers in the filter for whom to retrieve invoices. In the current implementation, you can only specify one location and optionally one customer. The response is paginated. If truncated, the response includes a `cursor` that you use in a subsequent request to retrieve the next set of invoices.

    POST /v2/invoices/search

  • Read

    GetInvoice

    Retrieves an invoice by invoice ID.

    GET /v2/invoices/{invoice_id}

  • Write

    CreateInvoice

    Creates a draft [invoice](entity:Invoice) for an order created using the Orders API. A draft invoice remains in your account and no action is taken. You must publish the invoice before Square can process it (send it to the customer's email address or charge the customer’s card on file).

    POST /v2/invoices

  • Write

    CreateInvoiceAttachment

    Uploads a file and attaches it to an invoice. This endpoint accepts HTTP multipart/form-data file uploads with a JSON `request` part and a `file` part. The `file` part must be a `readable stream` that contains a file in a supported format: GIF, JPEG, PNG, TIFF, BMP, or PDF. Invoices can have up to 10 attachments with a total file size of 25 MB. Attachments can be added only to invoices in the `DRAFT`, `SCHEDULED`, `UNPAID`, or `PARTIALLY_PAID` state. __NOTE:__ When testing in the Sandbox environment, the total file size is limited to 1 KB.

    POST /v2/invoices/{invoice_id}/attachments

  • Write

    PublishInvoice

    Publishes the specified draft invoice. After an invoice is published, Square follows up based on the invoice configuration. For example, Square sends the invoice to the customer's email address, charges the customer's card on file, or does nothing. Square also makes the invoice available on a Square-hosted invoice page. The invoice `status` also changes from `DRAFT` to a status based on the invoice configuration. For example, the status changes to `UNPAID` if Square emails the invoice or `PARTIALLY_PAID` if Square charges a card on file for a portion of the invoice amount. In addition to the required `ORDERS_WRITE` and `INVOICES_WRITE` permissions, `CUSTOMERS_READ` and `PAYMENTS_WRITE` are required when publishing invoices configured for card-on-file payments.

    POST /v2/invoices/{invoice_id}/publish

  • Destructive

    DeleteInvoice

    Deletes the specified invoice. When an invoice is deleted, the associated order status changes to CANCELED. You can only delete a draft invoice (you cannot delete a published invoice, including one that is scheduled for processing).

    DELETE /v2/invoices/{invoice_id}

  • Destructive

    UpdateInvoice

    Updates an invoice. This endpoint supports sparse updates, so you only need to specify the fields you want to change along with the required `version` field. Some restrictions apply to updating invoices. For example, you cannot change the `order_id` or `location_id` field.

    PUT /v2/invoices/{invoice_id}

  • Destructive

    DeleteInvoiceAttachment

    Removes an attachment from an invoice and permanently deletes the file. Attachments can be removed only from invoices in the `DRAFT`, `SCHEDULED`, `UNPAID`, or `PARTIALLY_PAID` state.

    DELETE /v2/invoices/{invoice_id}/attachments/{attachment_id}

  • Destructive

    CancelInvoice

    Cancels an invoice. The seller cannot collect payments for the canceled invoice. You cannot cancel an invoice in the `DRAFT` state or in a terminal state: `PAID`, `REFUNDED`, `CANCELED`, or `FAILED`.

    POST /v2/invoices/{invoice_id}/cancel

Labor

  • Read

    ListBreakTypes

    Returns a paginated list of `BreakType` instances for a business.

    GET /v2/labor/break-types

  • Read

    GetBreakType

    Returns a single `BreakType` specified by `id`.

    GET /v2/labor/break-types/{id}

  • Read

    ListEmployeeWages (deprecated)

    Returns a paginated list of `EmployeeWage` instances for a business.

    GET /v2/labor/employee-wages

  • Read

    GetEmployeeWage (deprecated)

    Returns a single `EmployeeWage` specified by `id`.

    GET /v2/labor/employee-wages/{id}

  • Read

    SearchScheduledShifts

    Returns a paginated list of scheduled shifts, with optional filter and sort settings. By default, results are sorted by `start_at` in ascending order.

    POST /v2/labor/scheduled-shifts/search

  • Read

    RetrieveScheduledShift

    Retrieves a scheduled shift by ID.

    GET /v2/labor/scheduled-shifts/{id}

  • Read

    SearchShifts (deprecated)

    Returns a paginated list of `Shift` records for a business. The list to be returned can be filtered by: - Location IDs - Team member IDs - Shift status (`OPEN` or `CLOSED`) - Shift start - Shift end - Workday details The list can be sorted by: - `START_AT` - `END_AT` - `CREATED_AT` - `UPDATED_AT`

    POST /v2/labor/shifts/search

  • Read

    GetShift (deprecated)

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

    GET /v2/labor/shifts/{id}

  • Read

    ListTeamMemberWages

    Returns a paginated list of `TeamMemberWage` instances for a business.

    GET /v2/labor/team-member-wages

  • Read

    GetTeamMemberWage

    Returns a single `TeamMemberWage` specified by `id`.

    GET /v2/labor/team-member-wages/{id}

  • Read

    SearchTimecards

    Returns a paginated list of `Timecard` records for a business. The list to be returned can be filtered by: - Location IDs - Team member IDs - Timecard status (`OPEN` or `CLOSED`) - Timecard start - Timecard end - Workday details The list can be sorted by: - `START_AT` - `END_AT` - `CREATED_AT` - `UPDATED_AT`

    POST /v2/labor/timecards/search

  • Read

    RetrieveTimecard

    Returns a single `Timecard` specified by `id`.

    GET /v2/labor/timecards/{id}

  • Read

    ListWorkweekConfigs

    Returns a list of `WorkweekConfig` instances for a business.

    GET /v2/labor/workweek-configs

  • Write

    CreateBreakType

    Creates a new `BreakType`. A `BreakType` is a template for creating `Break` objects. You must provide the following values in your request to this endpoint: - `location_id` - `break_name` - `expected_duration` - `is_paid` You can only have three `BreakType` instances per location. If you attempt to add a fourth `BreakType` for a location, an `INVALID_REQUEST_ERROR` "Exceeded limit of 3 breaks per location." is returned.

    POST /v2/labor/break-types

  • Write

    BulkPublishScheduledShifts

    Publishes 1 - 100 scheduled shifts. This endpoint takes a map of individual publish requests and returns a map of responses. When a scheduled shift is published, Square keeps the `draft_shift_details` field as is and copies it to the `published_shift_details` field. The minimum `start_at` and maximum `end_at` timestamps of all shifts in a `BulkPublishScheduledShifts` request must fall within a two-week period.

    POST /v2/labor/scheduled-shifts/bulk-publish

  • Write

    PublishScheduledShift

    Publishes a scheduled shift. When a scheduled shift is published, Square keeps the `draft_shift_details` field as is and copies it to the `published_shift_details` field.

    POST /v2/labor/scheduled-shifts/{id}/publish

  • Write

    CreateShift (deprecated)

    Creates a new `Shift`. A `Shift` represents a complete workday for a single team member. You must provide the following values in your request to this endpoint: - `location_id` - `team_member_id` - `start_at` An attempt to create a new `Shift` can result in a `BAD_REQUEST` error when: - The `status` of the new `Shift` is `OPEN` and the team member has another shift with an `OPEN` status. - The `start_at` date is in the future. - The `start_at` or `end_at` date overlaps another shift for the same team member. - The `Break` instances are set in the request and a break `start_at` is before the `Shift.start_at`, a break `end_at` is after the `Shift.end_at`, or both.

    POST /v2/labor/shifts

  • Write

    UpdateShift (deprecated)

    Updates an existing `Shift`. When adding a `Break` to a `Shift`, any earlier `Break` instances in the `Shift` have the `end_at` property set to a valid RFC-3339 datetime string. When closing a `Shift`, all `Break` instances in the `Shift` must be complete with `end_at` set on each `Break`.

    PUT /v2/labor/shifts/{id}

  • Write

    CreateTimecard

    Creates a new `Timecard`. A `Timecard` represents a complete workday for a single team member. You must provide the following values in your request to this endpoint: - `location_id` - `team_member_id` - `start_at` An attempt to create a new `Timecard` can result in a `BAD_REQUEST` error when: - The `status` of the new `Timecard` is `OPEN` and the team member has another timecard with an `OPEN` status. - The `start_at` date is in the future. - The `start_at` or `end_at` date overlaps another timecard for the same team member. - The `Break` instances are set in the request and a break `start_at` is before the `Timecard.start_at`, a break `end_at` is after the `Timecard.end_at`, or both.

    POST /v2/labor/timecards

  • Destructive

    DeleteBreakType

    Deletes an existing `BreakType`. A `BreakType` can be deleted even if it is referenced from a `Shift`.

    DELETE /v2/labor/break-types/{id}

  • Destructive

    UpdateBreakType

    Updates an existing `BreakType`.

    PUT /v2/labor/break-types/{id}

  • Destructive

    CreateScheduledShift

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

    POST /v2/labor/scheduled-shifts

  • Destructive

    UpdateScheduledShift

    Updates the draft shift details for a scheduled shift. This endpoint supports sparse updates, so only new, changed, or removed fields are required in the request. You must publish the shift to make updates public. You can make the following updates to `draft_shift_details`: - Change the `location_id`, `job_id`, `start_at`, and `end_at` fields. - Add, change, or clear the `team_member_id` and `notes` fields. To clear these fields, set the value to null. - Change the `is_deleted` field. To delete a scheduled shift, set `is_deleted` to true and then publish the shift.

    PUT /v2/labor/scheduled-shifts/{id}

  • Destructive

    DeleteShift (deprecated)

    Deletes a `Shift`.

    DELETE /v2/labor/shifts/{id}

  • Destructive

    DeleteTimecard

    Deletes a `Timecard`.

    DELETE /v2/labor/timecards/{id}

  • Destructive

    UpdateTimecard

    Updates an existing `Timecard`. When adding a `Break` to a `Timecard`, any earlier `Break` instances in the `Timecard` have the `end_at` property set to a valid RFC-3339 datetime string. When closing a `Timecard`, all `Break` instances in the `Timecard` must be complete with `end_at` set on each `Break`.

    PUT /v2/labor/timecards/{id}

  • Destructive

    UpdateWorkweekConfig

    Updates a `WorkweekConfig`.

    PUT /v2/labor/workweek-configs/{id}

Locations

  • Read

    ListLocations

    Provides details about all of the seller's [locations](https://developer.squareup.com/docs/locations-api), including those with an inactive status. Locations are listed alphabetically by `name`.

    GET /v2/locations

  • Read

    RetrieveLocation

    Retrieves details of a single location. Specify "main" as the location ID to retrieve details of the [main location](https://developer.squareup.com/docs/locations-api#about-the-main-location).

    GET /v2/locations/{location_id}

  • Write

    CreateLocation

    Creates a [location](https://developer.squareup.com/docs/locations-api). Creating new locations allows for separate configuration of receipt layouts, item prices, and sales reports. Developers can use locations to separate sales activity through applications that integrate with Square from sales activity elsewhere in a seller's account. Locations created programmatically with the Locations API last forever and are visible to the seller for their own management. Therefore, ensure that each location has a sensible and unique name.

    POST /v2/locations

  • Destructive

    UpdateLocation

    Updates a [location](https://developer.squareup.com/docs/locations-api).

    PUT /v2/locations/{location_id}

Location Custom Attributes

  • Read

    ListLocationCustomAttributeDefinitions

    Lists the location-related [custom attribute definitions](entity:CustomAttributeDefinition) that belong to a Square seller account. When all response pages are retrieved, the results include all custom attribute definitions that are visible to the requesting application, including those that are created by other applications and set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.

    GET /v2/locations/custom-attribute-definitions

  • Read

    RetrieveLocationCustomAttributeDefinition

    Retrieves a location-related [custom attribute definition](entity:CustomAttributeDefinition) from a Square seller account. To retrieve a custom attribute definition created by another application, the `visibility` setting must be `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.

    GET /v2/locations/custom-attribute-definitions/{key}

  • Read

    ListLocationCustomAttributes

    Lists the [custom attributes](entity:CustomAttribute) associated with a location. You can use the `with_definitions` query parameter to also retrieve custom attribute definitions in the same call. When all response pages are retrieved, the results include all custom attributes that are visible to the requesting application, including those that are owned by other applications and set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.

    GET /v2/locations/{location_id}/custom-attributes

  • Read

    RetrieveLocationCustomAttribute

    Retrieves a [custom attribute](entity:CustomAttribute) associated with a location. You can use the `with_definition` query parameter to also retrieve the custom attribute definition in the same call. To retrieve a custom attribute owned by another application, the `visibility` setting must be `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.

    GET /v2/locations/{location_id}/custom-attributes/{key}

  • Write

    CreateLocationCustomAttributeDefinition

    Creates a location-related [custom attribute definition](entity:CustomAttributeDefinition) for a Square seller account. Use this endpoint to define a custom attribute that can be associated with locations. A custom attribute definition specifies the `key`, `visibility`, `schema`, and other properties for a custom attribute. After the definition is created, you can call [UpsertLocationCustomAttribute](api-endpoint:LocationCustomAttributes-UpsertLocationCustomAttribute) or [BulkUpsertLocationCustomAttributes](api-endpoint:LocationCustomAttributes-BulkUpsertLocationCustomAttributes) to set the custom attribute for locations.

    POST /v2/locations/custom-attribute-definitions

  • Write

    BulkUpsertLocationCustomAttributes

    Creates or updates [custom attributes](entity:CustomAttribute) for locations as a bulk operation. Use this endpoint to set the value of one or more custom attributes for one or more locations. A custom attribute is based on a custom attribute definition in a Square seller account, which is created using the [CreateLocationCustomAttributeDefinition](api-endpoint:LocationCustomAttributes-CreateLocationCustomAttributeDefinition) endpoint. This `BulkUpsertLocationCustomAttributes` endpoint accepts a map of 1 to 25 individual upsert requests and returns a map of individual upsert responses. Each upsert request has a unique ID and provides a location ID and custom attribute. Each upsert response is returned with the ID of the corresponding request. To create or update a custom attribute owned by another application, the `visibility` setting must be `VISIBILITY_READ_WRITE_VALUES`.

    POST /v2/locations/custom-attributes/bulk-upsert

  • Write

    UpsertLocationCustomAttribute

    Creates or updates a [custom attribute](entity:CustomAttribute) for a location. Use this endpoint to set the value of a custom attribute for a specified location. A custom attribute is based on a custom attribute definition in a Square seller account, which is created using the [CreateLocationCustomAttributeDefinition](api-endpoint:LocationCustomAttributes-CreateLocationCustomAttributeDefinition) endpoint. To create or update a custom attribute owned by another application, the `visibility` setting must be `VISIBILITY_READ_WRITE_VALUES`.

    POST /v2/locations/{location_id}/custom-attributes/{key}

  • Destructive

    DeleteLocationCustomAttributeDefinition

    Deletes a location-related [custom attribute definition](entity:CustomAttributeDefinition) from a Square seller account. Deleting a custom attribute definition also deletes the corresponding custom attribute from all locations. Only the definition owner can delete a custom attribute definition.

    DELETE /v2/locations/custom-attribute-definitions/{key}

  • Destructive

    UpdateLocationCustomAttributeDefinition

    Updates a location-related [custom attribute definition](entity:CustomAttributeDefinition) for a Square seller account. Use this endpoint to update the following fields: `name`, `description`, `visibility`, or the `schema` for a `Selection` data type. Only the definition owner can update a custom attribute definition.

    PUT /v2/locations/custom-attribute-definitions/{key}

  • Destructive

    BulkDeleteLocationCustomAttributes

    Deletes [custom attributes](entity:CustomAttribute) for locations as a bulk operation. To delete a custom attribute owned by another application, the `visibility` setting must be `VISIBILITY_READ_WRITE_VALUES`.

    POST /v2/locations/custom-attributes/bulk-delete

  • Destructive

    DeleteLocationCustomAttribute

    Deletes a [custom attribute](entity:CustomAttribute) associated with a location. To delete a custom attribute owned by another application, the `visibility` setting must be `VISIBILITY_READ_WRITE_VALUES`.

    DELETE /v2/locations/{location_id}/custom-attributes/{key}

Checkout

  • Read

    RetrieveLocationSettings

    Retrieves the location-level settings for a Square-hosted checkout page.

    GET /v2/online-checkout/location-settings/{location_id}

  • Read

    RetrieveMerchantSettings

    Retrieves the merchant-level settings for a Square-hosted checkout page.

    GET /v2/online-checkout/merchant-settings

  • Write

    CreateCheckout (deprecated)

    Links a `checkoutId` to a `checkout_page_url` that customers are directed to in order to provide their payment information using a payment processing workflow hosted on connect.squareup.com. NOTE: The Checkout API has been updated with new features. For more information, see [Checkout API highlights](https://developer.squareup.com/docs/checkout-api#checkout-api-highlights).

    POST /v2/locations/{location_id}/checkouts

  • Destructive

    UpdateLocationSettings

    Updates the location-level settings for a Square-hosted checkout page.

    PUT /v2/online-checkout/location-settings/{location_id}

  • Destructive

    UpdateMerchantSettings

    Updates the merchant-level settings for a Square-hosted checkout page.

    PUT /v2/online-checkout/merchant-settings

Transactions

  • Read

    ListTransactions (deprecated)

    Lists transactions for a particular location. Transactions include payment information from sales and exchanges and refund information from returns and exchanges. Max results per [page](https://developer.squareup.com/docs/working-with-apis/pagination): 50

    GET /v2/locations/{location_id}/transactions

  • Read

    RetrieveTransaction (deprecated)

    Retrieves details for a single transaction.

    GET /v2/locations/{location_id}/transactions/{transaction_id}

Loyalty

  • Read

    SearchLoyaltyAccounts

    Searches for loyalty accounts in a loyalty program. You can search for a loyalty account using the phone number or customer ID associated with the account. To return all loyalty accounts, specify an empty `query` object or omit it entirely. Search results are sorted by `created_at` in ascending order.

    POST /v2/loyalty/accounts/search

  • Read

    RetrieveLoyaltyAccount

    Retrieves a loyalty account.

    GET /v2/loyalty/accounts/{account_id}

  • Read

    SearchLoyaltyEvents

    Searches for loyalty events. A Square loyalty program maintains a ledger of events that occur during the lifetime of a buyer's loyalty account. Each change in the point balance (for example, points earned, points redeemed, and points expired) is recorded in the ledger. Using this endpoint, you can search the ledger for events. Search results are sorted by `created_at` in descending order.

    POST /v2/loyalty/events/search

  • Read

    ListLoyaltyPrograms (deprecated)

    Returns a list of loyalty programs in the seller's account. Loyalty programs define how buyers can earn points and redeem points for rewards. Square sellers can have only one loyalty program, which is created and managed from the Seller Dashboard. For more information, see [Loyalty Program Overview](https://developer.squareup.com/docs/loyalty/overview). Replaced with [RetrieveLoyaltyProgram](api-endpoint:Loyalty-RetrieveLoyaltyProgram) when used with the keyword `main`.

    GET /v2/loyalty/programs

  • Read

    RetrieveLoyaltyProgram

    Retrieves the loyalty program in a seller's account, specified by the program ID or the keyword `main`. Loyalty programs define how buyers can earn points and redeem points for rewards. Square sellers can have only one loyalty program, which is created and managed from the Seller Dashboard. For more information, see [Loyalty Program Overview](https://developer.squareup.com/docs/loyalty/overview).

    GET /v2/loyalty/programs/{program_id}

  • Read

    CalculateLoyaltyPoints

    Calculates the number of points a buyer can earn from a purchase. Applications might call this endpoint to display the points to the buyer. - If you are using the Orders API to manage orders, provide the `order_id` and (optional) `loyalty_account_id`. Square reads the order to compute the points earned from the base loyalty program and an associated [loyalty promotion](entity:LoyaltyPromotion). - If you are not using the Orders API to manage orders, provide `transaction_amount_money` with the purchase amount. Square uses this amount to calculate the points earned from the base loyalty program, but not points earned from a loyalty promotion. For spend-based and visit-based programs, the `tax_mode` setting of the accrual rule indicates how taxes should be treated for loyalty points accrual. If the purchase qualifies for program points, call [ListLoyaltyPromotions](api-endpoint:Loyalty-ListLoyaltyPromotions) and perform a client-side computation to calculate whether the purchase also qualifies for promotion points. For more information, see [Calculating promotion points](https://developer.squareup.com/docs/loyalty-api/loyalty-promotions#calculate-promotion-points).

    POST /v2/loyalty/programs/{program_id}/calculate

  • Read

    ListLoyaltyPromotions

    Lists the loyalty promotions associated with a [loyalty program](entity:LoyaltyProgram). Results are sorted by the `created_at` date in descending order (newest to oldest).

    GET /v2/loyalty/programs/{program_id}/promotions

  • Read

    RetrieveLoyaltyPromotion

    Retrieves a loyalty promotion.

    GET /v2/loyalty/programs/{program_id}/promotions/{promotion_id}

  • Read

    SearchLoyaltyRewards

    Searches for loyalty rewards. This endpoint accepts a request with no query filters and returns results for all loyalty accounts. If you include a `query` object, `loyalty_account_id` is required and `status` is optional. If you know a reward ID, use the [RetrieveLoyaltyReward](api-endpoint:Loyalty-RetrieveLoyaltyReward) endpoint. Search results are sorted by `updated_at` in descending order.

    POST /v2/loyalty/rewards/search

  • Read

    RetrieveLoyaltyReward

    Retrieves a loyalty reward.

    GET /v2/loyalty/rewards/{reward_id}

  • Write

    CreateLoyaltyAccount

    Creates a loyalty account. To create a loyalty account, you must provide the `program_id` and a `mapping` with the `phone_number` of the buyer.

    POST /v2/loyalty/accounts

  • Write

    AccumulateLoyaltyPoints

    Adds points earned from a purchase to a [loyalty account](entity:LoyaltyAccount). - If you are using the Orders API to manage orders, provide the `order_id`. Square reads the order to compute the points earned from both the base loyalty program and an associated [loyalty promotion](entity:LoyaltyPromotion). For purchases that qualify for multiple accrual rules, Square computes points based on the accrual rule that grants the most points. For purchases that qualify for multiple promotions, Square computes points based on the most recently created promotion. A purchase must first qualify for program points to be eligible for promotion points. - If you are not using the Orders API to manage orders, provide `points` with the number of points to add. You must first perform a client-side computation of the points earned from the loyalty program and loyalty promotion. For spend-based and visit-based programs, you can call [CalculateLoyaltyPoints](api-endpoint:Loyalty-CalculateLoyaltyPoints) to compute the points earned from the base loyalty program. For information about computing points earned from a loyalty promotion, see [Calculating promotion points](https://developer.squareup.com/docs/loyalty-api/loyalty-promotions#calculate-promotion-points).

    POST /v2/loyalty/accounts/{account_id}/accumulate

  • Write

    CreateLoyaltyPromotion

    Creates a loyalty promotion for a [loyalty program](entity:LoyaltyProgram). A loyalty promotion enables buyers to earn points in addition to those earned from the base loyalty program. This endpoint sets the loyalty promotion to the `ACTIVE` or `SCHEDULED` status, depending on the `available_time` setting. A loyalty program can have a maximum of 10 loyalty promotions with an `ACTIVE` or `SCHEDULED` status.

    POST /v2/loyalty/programs/{program_id}/promotions

  • Write

    CreateLoyaltyReward

    Creates a loyalty reward. In the process, the endpoint does following: - Uses the `reward_tier_id` in the request to determine the number of points to lock for this reward. - If the request includes `order_id`, it adds the reward and related discount to the order. After a reward is created, the points are locked and not available for the buyer to redeem another reward.

    POST /v2/loyalty/rewards

  • Destructive

    AdjustLoyaltyPoints

    Adds points to or subtracts points from a buyer's account. Use this endpoint only when you need to manually adjust points. Otherwise, in your application flow, you call [AccumulateLoyaltyPoints](api-endpoint:Loyalty-AccumulateLoyaltyPoints) to add points when a buyer pays for the purchase.

    POST /v2/loyalty/accounts/{account_id}/adjust

  • Destructive

    CancelLoyaltyPromotion

    Cancels a loyalty promotion. Use this endpoint to cancel an `ACTIVE` promotion earlier than the end date, cancel an `ACTIVE` promotion when an end date is not specified, or cancel a `SCHEDULED` promotion. Because updating a promotion is not supported, you can also use this endpoint to cancel a promotion before you create a new one. This endpoint sets the loyalty promotion to the `CANCELED` state

    POST /v2/loyalty/programs/{program_id}/promotions/{promotion_id}/cancel

  • Destructive

    DeleteLoyaltyReward

    Deletes a loyalty reward by doing the following: - Returns the loyalty points back to the loyalty account. - If an order ID was specified when the reward was created (see [CreateLoyaltyReward](api-endpoint:Loyalty-CreateLoyaltyReward)), it updates the order by removing the reward and related discounts. You cannot delete a reward that has reached the terminal state (REDEEMED).

    DELETE /v2/loyalty/rewards/{reward_id}

  • Destructive

    RedeemLoyaltyReward

    Redeems a loyalty reward. The endpoint sets the reward to the `REDEEMED` terminal state. If you are using your own order processing system (not using the Orders API), you call this endpoint after the buyer paid for the purchase. After the reward reaches the terminal state, it cannot be deleted. In other words, points used for the reward cannot be returned to the account.

    POST /v2/loyalty/rewards/{reward_id}/redeem

Merchants

  • Read

    ListMerchants

    Provides details about the merchant associated with a given access token. The access token used to connect your application to a Square seller is associated with a single merchant. That means that `ListMerchants` returns a list with a single `Merchant` object. You can specify your personal access token to get your own merchant information or specify an OAuth token to get the information for the merchant that granted your application access. If you know the merchant ID, you can also use the [RetrieveMerchant](api-endpoint:Merchants-RetrieveMerchant) endpoint to retrieve the merchant information.

    GET /v2/merchants

  • Read

    RetrieveMerchant

    Retrieves the `Merchant` object for the given `merchant_id`.

    GET /v2/merchants/{merchant_id}

Merchant Custom Attributes

  • Read

    ListMerchantCustomAttributeDefinitions

    Lists the merchant-related [custom attribute definitions](entity:CustomAttributeDefinition) that belong to a Square seller account. When all response pages are retrieved, the results include all custom attribute definitions that are visible to the requesting application, including those that are created by other applications and set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.

    GET /v2/merchants/custom-attribute-definitions

  • Read

    RetrieveMerchantCustomAttributeDefinition

    Retrieves a merchant-related [custom attribute definition](entity:CustomAttributeDefinition) from a Square seller account. To retrieve a custom attribute definition created by another application, the `visibility` setting must be `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.

    GET /v2/merchants/custom-attribute-definitions/{key}

  • Read

    ListMerchantCustomAttributes

    Lists the [custom attributes](entity:CustomAttribute) associated with a merchant. You can use the `with_definitions` query parameter to also retrieve custom attribute definitions in the same call. When all response pages are retrieved, the results include all custom attributes that are visible to the requesting application, including those that are owned by other applications and set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.

    GET /v2/merchants/{merchant_id}/custom-attributes

  • Read

    RetrieveMerchantCustomAttribute

    Retrieves a [custom attribute](entity:CustomAttribute) associated with a merchant. You can use the `with_definition` query parameter to also retrieve the custom attribute definition in the same call. To retrieve a custom attribute owned by another application, the `visibility` setting must be `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.

    GET /v2/merchants/{merchant_id}/custom-attributes/{key}

  • Write

    CreateMerchantCustomAttributeDefinition

    Creates a merchant-related [custom attribute definition](entity:CustomAttributeDefinition) for a Square seller account. Use this endpoint to define a custom attribute that can be associated with a merchant connecting to your application. A custom attribute definition specifies the `key`, `visibility`, `schema`, and other properties for a custom attribute. After the definition is created, you can call [UpsertMerchantCustomAttribute](api-endpoint:MerchantCustomAttributes-UpsertMerchantCustomAttribute) or [BulkUpsertMerchantCustomAttributes](api-endpoint:MerchantCustomAttributes-BulkUpsertMerchantCustomAttributes) to set the custom attribute for a merchant.

    POST /v2/merchants/custom-attribute-definitions

  • Write

    BulkUpsertMerchantCustomAttributes

    Creates or updates [custom attributes](entity:CustomAttribute) for a merchant as a bulk operation. Use this endpoint to set the value of one or more custom attributes for a merchant. A custom attribute is based on a custom attribute definition in a Square seller account, which is created using the [CreateMerchantCustomAttributeDefinition](api-endpoint:MerchantCustomAttributes-CreateMerchantCustomAttributeDefinition) endpoint. This `BulkUpsertMerchantCustomAttributes` endpoint accepts a map of 1 to 25 individual upsert requests and returns a map of individual upsert responses. Each upsert request has a unique ID and provides a merchant ID and custom attribute. Each upsert response is returned with the ID of the corresponding request. To create or update a custom attribute owned by another application, the `visibility` setting must be `VISIBILITY_READ_WRITE_VALUES`.

    POST /v2/merchants/custom-attributes/bulk-upsert

  • Write

    UpsertMerchantCustomAttribute

    Creates or updates a [custom attribute](entity:CustomAttribute) for a merchant. Use this endpoint to set the value of a custom attribute for a specified merchant. A custom attribute is based on a custom attribute definition in a Square seller account, which is created using the [CreateMerchantCustomAttributeDefinition](api-endpoint:MerchantCustomAttributes-CreateMerchantCustomAttributeDefinition) endpoint. To create or update a custom attribute owned by another application, the `visibility` setting must be `VISIBILITY_READ_WRITE_VALUES`.

    POST /v2/merchants/{merchant_id}/custom-attributes/{key}

  • Destructive

    DeleteMerchantCustomAttributeDefinition

    Deletes a merchant-related [custom attribute definition](entity:CustomAttributeDefinition) from a Square seller account. Deleting a custom attribute definition also deletes the corresponding custom attribute from the merchant. Only the definition owner can delete a custom attribute definition.

    DELETE /v2/merchants/custom-attribute-definitions/{key}

  • Destructive

    UpdateMerchantCustomAttributeDefinition

    Updates a merchant-related [custom attribute definition](entity:CustomAttributeDefinition) for a Square seller account. Use this endpoint to update the following fields: `name`, `description`, `visibility`, or the `schema` for a `Selection` data type. Only the definition owner can update a custom attribute definition.

    PUT /v2/merchants/custom-attribute-definitions/{key}

  • Destructive

    BulkDeleteMerchantCustomAttributes

    Deletes [custom attributes](entity:CustomAttribute) for a merchant as a bulk operation. To delete a custom attribute owned by another application, the `visibility` setting must be `VISIBILITY_READ_WRITE_VALUES`.

    POST /v2/merchants/custom-attributes/bulk-delete

  • Destructive

    DeleteMerchantCustomAttribute

    Deletes a [custom attribute](entity:CustomAttribute) associated with a merchant. To delete a custom attribute owned by another application, the `visibility` setting must be `VISIBILITY_READ_WRITE_VALUES`.

    DELETE /v2/merchants/{merchant_id}/custom-attributes/{key}

Orders

  • Read

    BatchRetrieveOrders

    Retrieves a set of [orders](entity:Order) by their IDs. If a given order ID does not exist, the ID is ignored instead of generating an error.

    POST /v2/orders/batch-retrieve

  • Read

    CalculateOrder

    Enables applications to preview order pricing without creating an order.

    POST /v2/orders/calculate

  • Read

    SearchOrders

    Search all orders for one or more locations. Orders include all sales, returns, and exchanges regardless of how or when they entered the Square ecosystem (such as Point of Sale, Invoices, and Connect APIs). `SearchOrders` requests need to specify which locations to search and define a [SearchOrdersQuery](entity:SearchOrdersQuery) object that controls how to sort or filter the results. Your `SearchOrdersQuery` can: Set filter criteria. Set the sort order. Determine whether to return results as complete `Order` objects or as [OrderEntry](entity:OrderEntry) objects. Note that details for orders processed with Square Point of Sale while in offline mode might not be transmitted to Square for up to 72 hours. Offline orders have a `created_at` value that reflects the time the order was transmitted to Square and created server-side, not the time the order was created on the Point of Sale device.

    POST /v2/orders/search

  • Read

    RetrieveOrder

    Retrieves an [Order](entity:Order) by ID.

    GET /v2/orders/{order_id}

  • Write

    CreateOrder

    Creates a new [order](entity:Order) that can include information about products for purchase and settings to apply to the purchase. To pay for a created order, see [Pay for Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders). You can modify open orders using the [UpdateOrder](api-endpoint:Orders-UpdateOrder) endpoint.

    POST /v2/orders

  • Write

    CloneOrder

    Creates a new order, in the `DRAFT` state, by duplicating an existing order. The newly created order has only the core fields (such as line items, taxes, and discounts) copied from the original order.

    POST /v2/orders/clone

  • Write

    PayOrder

    Pay for an [order](entity:Order) using one or more approved [payments](entity:Payment) or settle an order with a total of `0`. The total of the `payment_ids` listed in the request must be equal to the order total. Orders with a total amount of `0` can be marked as paid by specifying an empty array of `payment_ids` in the request. To be used with `PayOrder`, a payment must: - Reference the order by specifying the `order_id` when [creating the payment](api-endpoint:Payments-CreatePayment). Any approved payments that reference the same `order_id` not specified in the `payment_ids` is canceled. - Be approved with [delayed capture](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture). Using a delayed capture payment with `PayOrder` completes the approved payment.

    POST /v2/orders/{order_id}/pay

  • Destructive

    UpdateOrder

    Updates an open [order](entity:Order) by adding, replacing, or deleting fields. Orders with a `COMPLETED` or `CANCELED` state cannot be updated. An `UpdateOrder` request requires the following: - The `order_id` in the endpoint path, identifying the order to update. - The latest `version` of the order to update. - The [sparse order](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders#sparse-order-objects) containing only the fields to update and the version to which the update is being applied. - If deleting fields, the [dot notation paths](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders#identifying-fields-to-delete) identifying the fields to clear. To pay for an order, see [Pay for Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders).

    PUT /v2/orders/{order_id}

Order Custom Attributes

  • Read

    ListOrderCustomAttributeDefinitions

    Lists the order-related [custom attribute definitions](entity:CustomAttributeDefinition) that belong to a Square seller account. When all response pages are retrieved, the results include all custom attribute definitions that are visible to the requesting application, including those that are created by other applications and set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes (also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.

    GET /v2/orders/custom-attribute-definitions

  • Read

    RetrieveOrderCustomAttributeDefinition

    Retrieves an order-related [custom attribute definition](entity:CustomAttributeDefinition) from a Square seller account. To retrieve a custom attribute definition created by another application, the `visibility` setting must be `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes (also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.

    GET /v2/orders/custom-attribute-definitions/{key}

  • Read

    ListOrderCustomAttributes

    Lists the [custom attributes](entity:CustomAttribute) associated with an order. You can use the `with_definitions` query parameter to also retrieve custom attribute definitions in the same call. When all response pages are retrieved, the results include all custom attributes that are visible to the requesting application, including those that are owned by other applications and set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.

    GET /v2/orders/{order_id}/custom-attributes

  • Read

    RetrieveOrderCustomAttribute

    Retrieves a [custom attribute](entity:CustomAttribute) associated with an order. You can use the `with_definition` query parameter to also retrieve the custom attribute definition in the same call. To retrieve a custom attribute owned by another application, the `visibility` setting must be `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.

    GET /v2/orders/{order_id}/custom-attributes/{custom_attribute_key}

  • Write

    CreateOrderCustomAttributeDefinition

    Creates an order-related custom attribute definition. Use this endpoint to define a custom attribute that can be associated with orders. After creating a custom attribute definition, you can set the custom attribute for orders in the Square seller account.

    POST /v2/orders/custom-attribute-definitions

  • Write

    UpsertOrderCustomAttribute

    Creates or updates a [custom attribute](entity:CustomAttribute) for an order. Use this endpoint to set the value of a custom attribute for a specific order. A custom attribute is based on a custom attribute definition in a Square seller account. (To create a custom attribute definition, use the [CreateOrderCustomAttributeDefinition](api-endpoint:OrderCustomAttributes-CreateOrderCustomAttributeDefinition) endpoint.) To create or update a custom attribute owned by another application, the `visibility` setting must be `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes (also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.

    POST /v2/orders/{order_id}/custom-attributes/{custom_attribute_key}

  • Destructive

    DeleteOrderCustomAttributeDefinition

    Deletes an order-related [custom attribute definition](entity:CustomAttributeDefinition) from a Square seller account. Only the definition owner can delete a custom attribute definition.

    DELETE /v2/orders/custom-attribute-definitions/{key}

  • Destructive

    UpdateOrderCustomAttributeDefinition

    Updates an order-related custom attribute definition for a Square seller account. Only the definition owner can update a custom attribute definition. Note that sellers can view all custom attributes in exported customer data, including those set to `VISIBILITY_HIDDEN`.

    PUT /v2/orders/custom-attribute-definitions/{key}

  • Destructive

    BulkDeleteOrderCustomAttributes

    Deletes order [custom attributes](entity:CustomAttribute) as a bulk operation. Use this endpoint to delete one or more custom attributes from one or more orders. A custom attribute is based on a custom attribute definition in a Square seller account. (To create a custom attribute definition, use the [CreateOrderCustomAttributeDefinition](api-endpoint:OrderCustomAttributes-CreateOrderCustomAttributeDefinition) endpoint.) This `BulkDeleteOrderCustomAttributes` endpoint accepts a map of 1 to 25 individual delete requests and returns a map of individual delete responses. Each delete request has a unique ID and provides an order ID and custom attribute. Each delete response is returned with the ID of the corresponding request. To delete a custom attribute owned by another application, the `visibility` setting must be `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes (also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.

    POST /v2/orders/custom-attributes/bulk-delete

  • Destructive

    BulkUpsertOrderCustomAttributes

    Creates or updates order [custom attributes](entity:CustomAttribute) as a bulk operation. Use this endpoint to delete one or more custom attributes from one or more orders. A custom attribute is based on a custom attribute definition in a Square seller account. (To create a custom attribute definition, use the [CreateOrderCustomAttributeDefinition](api-endpoint:OrderCustomAttributes-CreateOrderCustomAttributeDefinition) endpoint.) This `BulkUpsertOrderCustomAttributes` endpoint accepts a map of 1 to 25 individual upsert requests and returns a map of individual upsert responses. Each upsert request has a unique ID and provides an order ID and custom attribute. Each upsert response is returned with the ID of the corresponding request. To create or update a custom attribute owned by another application, the `visibility` setting must be `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes (also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.

    POST /v2/orders/custom-attributes/bulk-upsert

  • Destructive

    DeleteOrderCustomAttribute

    Deletes a [custom attribute](entity:CustomAttribute) associated with a customer profile. To delete a custom attribute owned by another application, the `visibility` setting must be `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom attributes (also known as custom fields) are always set to `VISIBILITY_READ_WRITE_VALUES`.

    DELETE /v2/orders/{order_id}/custom-attributes/{custom_attribute_key}

Payments

  • Read

    ListPayments

    Retrieves a list of payments taken by the account making the request. Results are eventually consistent, and new payments or changes to payments might take several seconds to appear. The maximum results per page is 100.

    GET /v2/payments

  • Read

    GetPayment

    Retrieves details for a specific payment.

    GET /v2/payments/{payment_id}

  • Write

    CreatePayment

    Creates a payment using the provided source. You can use this endpoint to charge a card (credit/debit card or Square gift card) or record a payment that the seller received outside of Square (cash payment from a buyer or a payment that an external entity processed on behalf of the seller). The endpoint creates a `Payment` object and returns it in the response.

    POST /v2/payments

  • Write

    CompletePayment

    Completes (captures) a payment. By default, payments are set to complete immediately after they are created. You can use this endpoint to complete a payment with the APPROVED `status`.

    POST /v2/payments/{payment_id}/complete

  • Destructive

    CancelPaymentByIdempotencyKey

    Cancels (voids) a payment identified by the idempotency key that is specified in the request. Use this method when the status of a `CreatePayment` request is unknown (for example, after you send a `CreatePayment` request, a network error occurs and you do not get a response). In this case, you can direct Square to cancel the payment using this endpoint. In the request, you provide the same idempotency key that you provided in your `CreatePayment` request that you want to cancel. After canceling the payment, you can submit your `CreatePayment` request again. Note that if no payment with the specified idempotency key is found, no action is taken and the endpoint returns successfully.

    POST /v2/payments/cancel

  • Destructive

    UpdatePayment

    Updates a payment with the APPROVED status. You can update the `amount_money` and `tip_money` using this endpoint.

    PUT /v2/payments/{payment_id}

  • Destructive

    CancelPayment

    Cancels (voids) a payment. You can use this endpoint to cancel a payment with the APPROVED `status`.

    POST /v2/payments/{payment_id}/cancel

Payouts

  • Read

    ListPayouts

    Retrieves a list of all payouts for the default location. You can filter payouts by location ID, status, time range, and order them in ascending or descending order. To call this endpoint, set `PAYOUTS_READ` for the OAuth scope.

    GET /v2/payouts

  • Read

    GetPayout

    Retrieves details of a specific payout identified by a payout ID. To call this endpoint, set `PAYOUTS_READ` for the OAuth scope.

    GET /v2/payouts/{payout_id}

  • Read

    ListPayoutEntries

    Retrieves a list of all payout entries for a specific payout. To call this endpoint, set `PAYOUTS_READ` for the OAuth scope.

    GET /v2/payouts/{payout_id}/payout-entries

Refunds

  • Read

    ListPaymentRefunds

    Retrieves a list of refunds for the account making the request. Results are eventually consistent, and new refunds or changes to refunds might take several seconds to appear. The maximum results per page is 100.

    GET /v2/refunds

  • Read

    GetPaymentRefund

    Retrieves a specific refund using the `refund_id`.

    GET /v2/refunds/{refund_id}

  • Write

    RefundPayment

    Refunds a payment. You can refund the entire payment amount or a portion of it. You can use this endpoint to refund a card payment or record a refund of a cash or external payment. For more information, see [Refund Payment](https://developer.squareup.com/docs/payments-api/refund-payments).

    POST /v2/refunds

Sites

  • Read

    ListSites

    Lists the Square Online sites that belong to a seller. Sites are listed in descending order by the `created_at` date. __Note:__ Square Online APIs are publicly available as part of an early access program. For more information, see [Early access program for Square Online APIs](https://developer.squareup.com/docs/online-api#early-access-program-for-square-online-apis).

    GET /v2/sites

Snippets

  • Read

    RetrieveSnippet

    Retrieves your snippet from a Square Online site. A site can contain snippets from multiple snippet applications, but you can retrieve only the snippet that was added by your application. You can call [ListSites](api-endpoint:Sites-ListSites) to get the IDs of the sites that belong to a seller. __Note:__ Square Online APIs are publicly available as part of an early access program. For more information, see [Early access program for Square Online APIs](https://developer.squareup.com/docs/online-api#early-access-program-for-square-online-apis).

    GET /v2/sites/{site_id}/snippet

  • Write

    UpsertSnippet

    Adds a snippet to a Square Online site or updates the existing snippet on the site. The snippet code is appended to the end of the `head` element on every page of the site, except checkout pages. A snippet application can add one snippet to a given site. You can call [ListSites](api-endpoint:Sites-ListSites) to get the IDs of the sites that belong to a seller. __Note:__ Square Online APIs are publicly available as part of an early access program. For more information, see [Early access program for Square Online APIs](https://developer.squareup.com/docs/online-api#early-access-program-for-square-online-apis).

    POST /v2/sites/{site_id}/snippet

  • Destructive

    DeleteSnippet

    Removes your snippet from a Square Online site. You can call [ListSites](api-endpoint:Sites-ListSites) to get the IDs of the sites that belong to a seller. __Note:__ Square Online APIs are publicly available as part of an early access program. For more information, see [Early access program for Square Online APIs](https://developer.squareup.com/docs/online-api#early-access-program-for-square-online-apis).

    DELETE /v2/sites/{site_id}/snippet

Subscriptions

  • Read

    SearchSubscriptions

    Searches for subscriptions. Results are ordered chronologically by subscription creation date. If the request specifies more than one location ID, the endpoint orders the result by location ID, and then by creation date within each location. If no locations are given in the query, all locations are searched. You can also optionally specify `customer_ids` to search by customer. If left unset, all customers associated with the specified locations are returned. If the request specifies customer IDs, the endpoint orders results first by location, within location by customer ID, and within customer by subscription creation date.

    POST /v2/subscriptions/search

  • Read

    RetrieveSubscription

    Retrieves a specific subscription.

    GET /v2/subscriptions/{subscription_id}

  • Read

    ListSubscriptionEvents

    Lists all [events](https://developer.squareup.com/docs/subscriptions-api/actions-events) for a specific subscription.

    GET /v2/subscriptions/{subscription_id}/events

  • Write

    CreateSubscription

    Enrolls a customer in a subscription. If you provide a card on file in the request, Square charges the card for the subscription. Otherwise, Square sends an invoice to the customer's email address. The subscription starts immediately, unless the request includes the optional `start_date`. Each individual subscription is associated with a particular location. For more information, see [Create a subscription](https://developer.squareup.com/docs/subscriptions-api/manage-subscriptions#create-a-subscription).

    POST /v2/subscriptions

  • Write

    BulkSwapPlan

    Schedules a plan variation change for all active subscriptions under a given plan variation. For more information, see [Swap Subscription Plan Variations](https://developer.squareup.com/docs/subscriptions-api/swap-plan-variations).

    POST /v2/subscriptions/bulk-swap-plan

  • Write

    ChangeBillingAnchorDate

    Changes the [billing anchor date](https://developer.squareup.com/docs/subscriptions-api/subscription-billing#billing-dates) for a subscription.

    POST /v2/subscriptions/{subscription_id}/billing-anchor

  • Write

    PauseSubscription

    Schedules a `PAUSE` action to pause an active subscription.

    POST /v2/subscriptions/{subscription_id}/pause

  • Write

    ResumeSubscription

    Schedules a `RESUME` action to resume a paused or a deactivated subscription.

    POST /v2/subscriptions/{subscription_id}/resume

  • Write

    SwapPlan

    Schedules a `SWAP_PLAN` action to swap a subscription plan variation in an existing subscription. For more information, see [Swap Subscription Plan Variations](https://developer.squareup.com/docs/subscriptions-api/swap-plan-variations).

    POST /v2/subscriptions/{subscription_id}/swap-plan

  • Destructive

    UpdateSubscription

    Updates a subscription by modifying or clearing `subscription` field values. To clear a field, set its value to `null`.

    PUT /v2/subscriptions/{subscription_id}

  • Destructive

    DeleteSubscriptionAction

    Deletes a scheduled action for a subscription.

    DELETE /v2/subscriptions/{subscription_id}/actions/{action_id}

  • Destructive

    CancelSubscription

    Schedules a `CANCEL` action to cancel an active subscription. This sets the `canceled_date` field to the end of the active billing period. After this date, the subscription status changes from ACTIVE to CANCELED.

    POST /v2/subscriptions/{subscription_id}/cancel

Team

  • Read

    ListJobs

    Lists jobs in a seller account. Results are sorted by title in ascending order.

    GET /v2/team-members/jobs

  • Read

    RetrieveJob

    Retrieves a specified job.

    GET /v2/team-members/jobs/{job_id}

  • Read

    SearchTeamMembers

    Returns a paginated list of `TeamMember` objects for a business. The list can be filtered by location IDs, `ACTIVE` or `INACTIVE` status, or whether the team member is the Square account owner.

    POST /v2/team-members/search

  • Read

    RetrieveTeamMember

    Retrieves a `TeamMember` object for the given `TeamMember.id`. Learn about [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#retrieve-a-team-member).

    GET /v2/team-members/{team_member_id}

  • Read

    RetrieveWageSetting

    Retrieves a `WageSetting` object for a team member specified by `TeamMember.id`. For more information, see [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#retrievewagesetting). Square recommends using [RetrieveTeamMember](api-endpoint:Team-RetrieveTeamMember) or [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers) to get this information directly from the `TeamMember.wage_setting` field.

    GET /v2/team-members/{team_member_id}/wage-setting

  • Write

    CreateTeamMember

    Creates a single `TeamMember` object. The `TeamMember` object is returned on successful creates. You must provide the following values in your request to this endpoint: - `given_name` - `family_name` Learn about [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#createteammember).

    POST /v2/team-members

  • Write

    BulkCreateTeamMembers

    Creates multiple `TeamMember` objects. The created `TeamMember` objects are returned on successful creates. This process is non-transactional and processes as much of the request as possible. If one of the creates in the request cannot be successfully processed, the request is not marked as failed, but the body of the response contains explicit error information for the failed create. Learn about [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#bulk-create-team-members).

    POST /v2/team-members/bulk-create

  • Write

    CreateJob

    Creates a job in a seller account. A job defines a title and tip eligibility. Note that compensation is defined in a [job assignment](entity:JobAssignment) in a team member's wage setting.

    POST /v2/team-members/jobs

  • Destructive

    BulkUpdateTeamMembers

    Updates multiple `TeamMember` objects. The updated `TeamMember` objects are returned on successful updates. This process is non-transactional and processes as much of the request as possible. If one of the updates in the request cannot be successfully processed, the request is not marked as failed, but the body of the response contains explicit error information for the failed update. Learn about [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#bulk-update-team-members).

    POST /v2/team-members/bulk-update

  • Destructive

    UpdateJob

    Updates the title or tip eligibility of a job. Changes to the title propagate to all `JobAssignment`, `Shift`, and `TeamMemberWage` objects that reference the job ID. Changes to tip eligibility propagate to all `TeamMemberWage` objects that reference the job ID.

    PUT /v2/team-members/jobs/{job_id}

  • Destructive

    UpdateTeamMember

    Updates a single `TeamMember` object. The `TeamMember` object is returned on successful updates. Learn about [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#update-a-team-member).

    PUT /v2/team-members/{team_member_id}

  • Destructive

    UpdateWageSetting

    Creates or updates a `WageSetting` object. The object is created if a `WageSetting` with the specified `team_member_id` doesn't exist. Otherwise, it fully replaces the `WageSetting` object for the team member. The `WageSetting` is returned on a successful update. For more information, see [Troubleshooting the Team API](https://developer.squareup.com/docs/team/troubleshooting#create-or-update-a-wage-setting). Square recommends using [CreateTeamMember](api-endpoint:Team-CreateTeamMember) or [UpdateTeamMember](api-endpoint:Team-UpdateTeamMember) to manage the `TeamMember.wage_setting` field directly.

    PUT /v2/team-members/{team_member_id}/wage-setting

Terminal

  • Read

    SearchTerminalActions

    Retrieves a filtered list of Terminal action requests created by the account making the request. Terminal action requests are available for 30 days.

    POST /v2/terminals/actions/search

  • Read

    GetTerminalAction

    Retrieves a Terminal action request by `action_id`. Terminal action requests are available for 30 days.

    GET /v2/terminals/actions/{action_id}

  • Read

    SearchTerminalCheckouts

    Returns a filtered list of Terminal checkout requests created by the application making the request. Only Terminal checkout requests created for the merchant scoped to the OAuth token are returned. Terminal checkout requests are available for 30 days.

    POST /v2/terminals/checkouts/search

  • Read

    GetTerminalCheckout

    Retrieves a Terminal checkout request by `checkout_id`. Terminal checkout requests are available for 30 days.

    GET /v2/terminals/checkouts/{checkout_id}

  • Read

    SearchTerminalRefunds

    Retrieves a filtered list of Interac Terminal refund requests created by the seller making the request. Terminal refund requests are available for 30 days.

    POST /v2/terminals/refunds/search

  • Read

    GetTerminalRefund

    Retrieves an Interac Terminal refund object by ID. Terminal refund objects are available for 30 days.

    GET /v2/terminals/refunds/{terminal_refund_id}

  • Write

    CreateTerminalAction

    Creates a Terminal action request and sends it to the specified device.

    POST /v2/terminals/actions

  • Write

    DismissTerminalAction

    Dismisses a Terminal action request if the status and type of the request permits it. See [Link and Dismiss Actions](https://developer.squareup.com/docs/terminal-api/advanced-features/custom-workflows/link-and-dismiss-actions) for more details.

    POST /v2/terminals/actions/{action_id}/dismiss

  • Write

    CreateTerminalCheckout

    Creates a Terminal checkout request and sends it to the specified device to take a payment for the requested amount.

    POST /v2/terminals/checkouts

  • Write

    DismissTerminalCheckout

    Dismisses a Terminal checkout request if the status and type of the request permits it.

    POST /v2/terminals/checkouts/{checkout_id}/dismiss

  • Write

    CreateTerminalRefund

    Creates a request to refund an Interac payment completed on a Square Terminal. Refunds for Interac payments on a Square Terminal are supported only for Interac debit cards in Canada. Other refunds for Terminal payments should use the Refunds API. For more information, see [Refunds API](api:Refunds).

    POST /v2/terminals/refunds

  • Write

    DismissTerminalRefund

    Dismisses a Terminal refund request if the status and type of the request permits it.

    POST /v2/terminals/refunds/{terminal_refund_id}/dismiss

  • Destructive

    CancelTerminalAction

    Cancels a Terminal action request if the status of the request permits it.

    POST /v2/terminals/actions/{action_id}/cancel

  • Destructive

    CancelTerminalCheckout

    Cancels a Terminal checkout request if the status of the request permits it.

    POST /v2/terminals/checkouts/{checkout_id}/cancel

  • Destructive

    CancelTerminalRefund

    Cancels an Interac Terminal refund request by refund request ID if the status of the request permits it.

    POST /v2/terminals/refunds/{terminal_refund_id}/cancel

Transfer Order

  • Read

    SearchTransferOrders

    Searches for transfer orders using filters. Returns a paginated list of matching [TransferOrder](entity:TransferOrder)s sorted by creation date. Common search scenarios: - Find orders for a source [Location](entity:Location) - Find orders for a destination [Location](entity:Location) - Find orders in a particular [TransferOrderStatus](entity:TransferOrderStatus)

    POST /v2/transfer-orders/search

  • Read

    RetrieveTransferOrder

    Retrieves a specific [TransferOrder](entity:TransferOrder) by ID. Returns the complete order details including: - Basic information (status, dates, notes) - Line items with ordered and received quantities - Source and destination [Location](entity:Location)s - Tracking information (if available)

    GET /v2/transfer-orders/{transfer_order_id}

  • Write

    CreateTransferOrder

    Creates a new transfer order in [DRAFT](entity:TransferOrderStatus) status. A transfer order represents the intent to move [CatalogItemVariation](entity:CatalogItemVariation)s from one [Location](entity:Location) to another. The source and destination locations must be different and must belong to your Square account. In [DRAFT](entity:TransferOrderStatus) status, you can: - Add or remove items - Modify quantities - Update shipping information - Delete the entire order via [DeleteTransferOrder](api-endpoint:TransferOrders-DeleteTransferOrder) The request requires source_location_id and destination_location_id. Inventory levels are not affected until the order is started via [StartTransferOrder](api-endpoint:TransferOrders-StartTransferOrder). Common integration points: - Sync with warehouse management systems - Automate regular stock transfers - Initialize transfers from inventory optimization systems Creates a [transfer_order.created](webhook:transfer_order.created) webhook event.

    POST /v2/transfer-orders

  • Write

    ReceiveTransferOrder

    Records receipt of [CatalogItemVariation](entity:CatalogItemVariation)s for a transfer order. This endpoint supports partial receiving - you can receive items in multiple batches. For each line item, you can specify: - Quantity received in good condition (added to destination inventory with [InventoryState](entity:InventoryState) of IN_STOCK) - Quantity damaged during transit/handling (added to destination inventory with [InventoryState](entity:InventoryState) of WASTE) - Quantity canceled (returned to source location's inventory) The order must be in [STARTED](entity:TransferOrderStatus) or [PARTIALLY_RECEIVED](entity:TransferOrderStatus) status. Received quantities are added to the destination [Location](entity:Location)'s inventory according to their condition. Canceled quantities are immediately returned to the source [Location](entity:Location)'s inventory. When all items are either received, damaged, or canceled, the order moves to [COMPLETED](entity:TransferOrderStatus) status. Creates a [transfer_order.updated](webhook:transfer_order.updated) webhook event.

    POST /v2/transfer-orders/{transfer_order_id}/receive

  • Write

    StartTransferOrder

    Changes a [DRAFT](entity:TransferOrderStatus) transfer order to [STARTED](entity:TransferOrderStatus) status. This decrements inventory at the source [Location](entity:Location) and marks it as in-transit. The order must be in [DRAFT](entity:TransferOrderStatus) status and have all required fields populated. Once started, the order can no longer be deleted, but it can be canceled via [CancelTransferOrder](api-endpoint:TransferOrders-CancelTransferOrder). Creates a [transfer_order.updated](webhook:transfer_order.updated) webhook event.

    POST /v2/transfer-orders/{transfer_order_id}/start

  • Destructive

    DeleteTransferOrder

    Deletes a transfer order in [DRAFT](entity:TransferOrderStatus) status. Only draft orders can be deleted. Once an order is started via [StartTransferOrder](api-endpoint:TransferOrders-StartTransferOrder), it can no longer be deleted. Creates a [transfer_order.deleted](webhook:transfer_order.deleted) webhook event.

    DELETE /v2/transfer-orders/{transfer_order_id}

  • Destructive

    UpdateTransferOrder

    Updates an existing transfer order. This endpoint supports sparse updates, allowing you to modify specific fields without affecting others. Creates a [transfer_order.updated](webhook:transfer_order.updated) webhook event.

    PUT /v2/transfer-orders/{transfer_order_id}

  • Destructive

    CancelTransferOrder

    Cancels a transfer order in [STARTED](entity:TransferOrderStatus) or [PARTIALLY_RECEIVED](entity:TransferOrderStatus) status. Any unreceived quantities will no longer be receivable and will be immediately returned to the source [Location](entity:Location)'s inventory. Common reasons for cancellation: - Items no longer needed at destination - Source location needs the inventory - Order created in error Creates a [transfer_order.updated](webhook:transfer_order.updated) webhook event.

    POST /v2/transfer-orders/{transfer_order_id}/cancel

Vendors

  • Read

    BulkRetrieveVendors

    Retrieves one or more vendors of specified [Vendor](entity:Vendor) IDs.

    POST /v2/vendors/bulk-retrieve

  • Read

    SearchVendors

    Searches for vendors using a filter against supported [Vendor](entity:Vendor) properties and a supported sorter.

    POST /v2/vendors/search

  • Read

    RetrieveVendor

    Retrieves the vendor of a specified [Vendor](entity:Vendor) ID.

    GET /v2/vendors/{vendor_id}

  • Write

    BulkCreateVendors

    Creates one or more [Vendor](entity:Vendor) objects to represent suppliers to a seller.

    POST /v2/vendors/bulk-create

  • Write

    CreateVendor

    Creates a single [Vendor](entity:Vendor) object to represent a supplier to a seller.

    POST /v2/vendors/create

  • Destructive

    BulkUpdateVendors

    Updates one or more of existing [Vendor](entity:Vendor) objects as suppliers to a seller.

    PUT /v2/vendors/bulk-update

  • Destructive

    UpdateVendor

    Updates an existing [Vendor](entity:Vendor) object as a supplier to a seller.

    PUT /v2/vendors/{vendor_id}

Webhook Subscriptions

  • Read

    ListWebhookEventTypes

    Lists all webhook event types that can be subscribed to.

    GET /v2/webhooks/event-types

  • Read

    ListWebhookSubscriptions

    Lists all webhook subscriptions owned by your application.

    GET /v2/webhooks/subscriptions

  • Read

    RetrieveWebhookSubscription

    Retrieves a webhook subscription identified by its ID.

    GET /v2/webhooks/subscriptions/{subscription_id}

  • Write

    CreateWebhookSubscription

    Creates a webhook subscription.

    POST /v2/webhooks/subscriptions

  • Write

    UpdateWebhookSubscriptionSignatureKey

    Updates a webhook subscription by replacing the existing signature key with a new one.

    POST /v2/webhooks/subscriptions/{subscription_id}/signature-key

  • Write

    TestWebhookSubscription

    Tests a webhook subscription by sending a test event to the notification URL.

    POST /v2/webhooks/subscriptions/{subscription_id}/test

  • Destructive

    DeleteWebhookSubscription

    Deletes a webhook subscription.

    DELETE /v2/webhooks/subscriptions/{subscription_id}

  • Destructive

    UpdateWebhookSubscription

    Updates a webhook subscription.

    PUT /v2/webhooks/subscriptions/{subscription_id}

See How connections work for access and permissions, or browse all integrations.