Square Connect API

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

ListChannels

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

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

ListCustomerGroups Retrieves the list of customer groups of a business.

ListCustomerSegments Retrieves the list of customer segments of a business.

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.

ListDeviceCodes Lists all DeviceCodes associated with the merchant.

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

ListDisputeEvidence Returns a list of evidence associated with a dispute.

ListDisputes Returns a list of disputes associated with a particular account.

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

ListEmployees

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

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.

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.

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

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.

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

ListLocationBookingProfiles Lists location booking profiles of a seller.

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

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

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

ListLoyaltyPrograms 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`.

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

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

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

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.

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

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

ListPaymentLinks Lists all payment links.

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.

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.

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

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.

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

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

ListTeamMemberBookingProfiles Lists booking profiles for team members.

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

ListTransactions 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

ListWebhookEventTypes Lists all webhook event types that can be subscribed to.

ListWebhookSubscriptions Lists all webhook subscriptions owned by your application.

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

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.

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

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.

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.

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.

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.

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.