Square Connect API

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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`

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

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

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

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

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

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

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

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.

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.

BulkRetrieveChannels

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

BulkRetrieveTeamMemberBookingProfiles Retrieves one or more team members' booking profiles.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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.

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

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

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

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.

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

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

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.

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

CreateBankAccount Store a bank account on file for a square account