Square Connect API

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

RetrieveTeamMemberBookingProfile Retrieves a team member's booking profile.

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

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.

RetrieveTransaction Retrieves details for a single transaction.

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)

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

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.

RetrieveWebhookSubscription Retrieves a webhook subscription identified by its ID.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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

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.

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.

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

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.

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.

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`

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)

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

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.

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.

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

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

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

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

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

UpdateBreakType Updates an existing `BreakType`.

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.

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.

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

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

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

UpdateInventoryAdjustmentReason Updates a custom inventory adjustment reason.

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.

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.

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.

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.

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

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.