Square Connect API

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

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

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.

CreateCard Adds a card on file to an existing merchant.

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.

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`

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

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

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

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

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.

CreateDisputeEvidenceText Uploads text to use as evidence for a dispute challenge.

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.

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.

CreateInventoryAdjustmentReason Creates a custom inventory adjustment reason.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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`

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

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

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

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

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

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

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.

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.

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

CreateWebhookSubscription Creates a webhook subscription.

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

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

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

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.

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.

DeleteCustomerCard Removes a card on file from a customer.

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

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.

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

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

DeleteInventoryAdjustmentReason Soft deletes a custom inventory adjustment reason.

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

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.