Square Connect API

Tools (202)

Extracted live via the executor SDK.

• applePay.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.

  To learn more about Web Apple Pay, see Add the Apple Pay on the Web Button.

• bankAccounts.getBankAccount

  Returns details of a BankAccount linked to a Square account.

• bankAccounts.getBankAccountByV1Id

  Returns details of a BankAccount identified by V1 bank account ID.

• bankAccounts.listBankAccounts

  Returns a list of BankAccount objects linked to a Square account.

• bookings.cancelBooking

  Cancels an existing booking.

• bookings.createBooking

  Creates a booking.

• bookings.listTeamMemberBookingProfiles

  Lists booking profiles for team members.

• bookings.retrieveBooking

  Retrieves a booking.

• bookings.retrieveBusinessBookingProfile

  Retrieves a seller's booking profile.

• bookings.retrieveTeamMemberBookingProfile

  Retrieves a team member's booking profile.

• bookings.searchAvailability

  Searches for availabilities for booking.

• bookings.updateBooking

  Updates a booking.

• cards.createCard

  Adds a card on file to an existing merchant.

• cards.disableCard

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

• cards.listCards

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

• cards.retrieveCard

  Retrieves details for a specific Card.

• cashDrawers.listCashDrawerShiftEvents

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

• cashDrawers.listCashDrawerShifts

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

• cashDrawers.retrieveCashDrawerShift

  Provides the summary details for a single cash drawer shift. See ListCashDrawerShiftEvents for a list of cash drawer shift events.

• catalog.batchDeleteCatalogObjects

  Deletes a set of CatalogItems 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 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.

• catalog.batchRetrieveCatalogObjects

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

• catalog.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.

• catalog.catalogInfo

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

• catalog.deleteCatalogObject

  Deletes a single 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 will also delete all of its CatalogItemVariation children.

• catalog.listCatalog

  Returns a list of CatalogObjects that includes all objects of a set of desired types (for example, all CatalogItem and CatalogTax objects) in the catalog. The types parameter is specified as a comma-separated list of valid CatalogObject types: ITEM, ITEM_VARIATION, MODIFIER, MODIFIER_LIST, CATEGORY, DISCOUNT, TAX, IMAGE.

  Important: ListCatalog does not return deleted catalog items. To retrieve deleted catalog items, use SearchCatalogObjects and set the include_deleted_objects attribute value to true.

• catalog.retrieveCatalogObject

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

• catalog.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 expressions.

  This (SearchCatalogItems) endpoint differs from the 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.
• catalog.searchCatalogObjects

  Searches for 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 expressions.

  This (SearchCatalogObjects) endpoint differs from the 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.
• catalog.updateItemModifierLists

  Updates the CatalogModifierList objects that apply to the targeted CatalogItem without having to perform an upsert on the entire item.

• catalog.updateItemTaxes

  Updates the CatalogTax objects that apply to the targeted CatalogItem without having to perform an upsert on the entire item.

• catalog.upsertCatalogObject

  Creates or updates the target CatalogObject.

• checkout.createCheckout

  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.

• customerGroups.createCustomerGroup

  Creates a new customer group for a business.

  The request must include the name value of the group.

• customerGroups.deleteCustomerGroup

  Deletes a customer group as identified by the group_id value.

• customerGroups.listCustomerGroups

  Retrieves the list of customer groups of a business.

• customerGroups.retrieveCustomerGroup

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

• customerGroups.updateCustomerGroup

  Updates a customer group as identified by the group_id value.

• customers.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.

• customers.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
• customers.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.

• customers.deleteCustomer

  Deletes a customer profile from a business. This operation also unlinks any associated cards on file.

  As a best practice, you should include the version field in the request to enable optimistic concurrency control. The value must be set to the current version of the customer profile.

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

• customers.deleteCustomerCard

  Removes a card on file from a customer.

• customers.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.

• customers.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.

• customers.retrieveCustomer

  Returns details for a single customer.

• customers.searchCustomers

  Searches the customer profiles associated with a Square account using a supported query filter.

  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.

• customers.updateCustomer

  Updates a customer profile. To change an attribute, specify the new value. To remove an attribute, specify the value as an empty string or empty object.

  As a best practice, you should include the version field in the request to enable optimistic concurrency control. The value must be set to the current version of the customer profile.

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

  You cannot use this endpoint to change cards on file. To make changes, use the Cards API or Gift Cards API.

• customerSegments.listCustomerSegments

  Retrieves the list of customer segments of a business.

• customerSegments.retrieveCustomerSegment

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

• devices.createDeviceCode

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

• devices.getDeviceCode

  Retrieves DeviceCode with the associated ID.

• devices.listDeviceCodes

  Lists all DeviceCodes associated with the merchant.

• disputes.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.

• disputes.createDisputeEvidenceText

  Uploads text to use as evidence for a dispute challenge.

• disputes.deleteDisputeEvidence

  Removes specified evidence from a dispute.

  Square does not send the bank any evidence that is removed. Also, you cannot remove evidence after submitting it to the bank using SubmitEvidence.

• disputes.listDisputeEvidence

  Returns a list of evidence associated with a dispute.

• disputes.listDisputes

  Returns a list of disputes associated with a particular account.

• disputes.retrieveDispute

  Returns details about a specific dispute.

• disputes.retrieveDisputeEvidence

  Returns the evidence metadata specified by the evidence ID in the request URL path

  You must maintain a copy of the evidence you upload if you want to reference it later. You cannot download the evidence after you upload it.

• disputes.submitEvidence

  Submits evidence to the cardholder's bank.

  Before submitting evidence, Square compiles all available evidence. This includes evidence uploaded using the CreateDisputeEvidenceFile and CreateDisputeEvidenceText endpoints and evidence automatically provided by Square, when available.

• employees.getV2Employees
• employees.getV2EmployeesId
• giftCardActivities.createGiftCardActivity

  Creates a gift card activity. For more information, see GiftCardActivity and Using activated gift cards.

• giftCardActivities.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.

• giftCards.createGiftCard

  Creates a digital gift card or registers a physical (plastic) gift card. You must activate the gift card before it can be used for payment. For more information, see Selling gift cards.

• giftCards.linkCustomerToGiftCard

  Links a customer to a gift card

• giftCards.listGiftCards

  Lists all gift cards. You can specify optional filters to retrieve a subset of the gift cards.

• giftCards.retrieveGiftCard

  Retrieves a gift card using its ID.

• giftCards.retrieveGiftCardFromGan

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

• giftCards.retrieveGiftCardFromNonce

  Retrieves a gift card using a nonce (a secure token) that represents the gift card.

• giftCards.unlinkCustomerFromGiftCard

  Unlinks a customer from a gift card

• inventory.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.

• inventory.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.

• inventory.batchRetrieveInventoryCounts

  Returns current counts for the provided CatalogObjects at the requested Locations.

  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.

• inventory.deprecatedBatchChangeInventory

  Deprecated version of BatchChangeInventory after the endpoint URL is updated to conform to the standard convention.

• inventory.deprecatedBatchRetrieveInventoryChanges

  Deprecated version of BatchRetrieveInventoryChanges after the endpoint URL is updated to conform to the standard convention.

• inventory.deprecatedBatchRetrieveInventoryCounts

  Deprecated version of BatchRetrieveInventoryCounts after the endpoint URL is updated to conform to the standard convention.

• inventory.deprecatedRetrieveInventoryAdjustment

  Deprecated version of RetrieveInventoryAdjustment after the endpoint URL is updated to conform to the standard convention.

• inventory.deprecatedRetrieveInventoryPhysicalCount

  Deprecated version of RetrieveInventoryPhysicalCount after the endpoint URL is updated to conform to the standard convention.

• inventory.retrieveInventoryAdjustment

  Returns the InventoryAdjustment object with the provided adjustment_id.

• inventory.retrieveInventoryChanges

  Returns a set of physical counts and inventory adjustments for the provided CatalogObject at the requested Locations.

  You can achieve the same result by calling 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.

• inventory.retrieveInventoryCount

  Retrieves the current calculated stock count for a given CatalogObject at a given set of Locations. Responses are paginated and unsorted. For more sophisticated queries, use a batch endpoint.

• inventory.retrieveInventoryPhysicalCount

  Returns the InventoryPhysicalCount object with the provided physical_count_id.

• inventory.retrieveInventoryTransfer

  Returns the InventoryTransfer object with the provided transfer_id.

• invoices.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.

• invoices.createInvoice

  Creates a draft 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).

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

• invoices.getInvoice

  Retrieves an invoice by invoice ID.

• invoices.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.

• invoices.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 charge a card on file for a portion of the invoice amount.

• invoices.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.

• invoices.updateInvoice

  Updates an invoice by modifying fields, clearing fields, or both. For most updates, you can use a sparse Invoice object to add fields or change values and use the fields_to_clear field to specify fields to clear. However, some restrictions apply. For example, you cannot change the order_id or location_id field and you must provide the complete custom_fields list to update a custom field. Published invoices have additional restrictions.

• labor.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.

• labor.createShift

  Creates a new Shift.

  A Shift represents a complete workday for a single employee. You must provide the following values in your request to this endpoint:

  • location_id
  • employee_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 employee 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 employee.
  • 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.
• labor.deleteBreakType

  Deletes an existing BreakType.

  A BreakType can be deleted even if it is referenced from a Shift.

• labor.deleteShift

  Deletes a Shift.

• labor.getBreakType

  Returns a single BreakType specified by id.

• labor.getEmployeeWage

  Returns a single EmployeeWage specified by id.

• labor.getShift

  Returns a single Shift specified by id.

• labor.getTeamMemberWage

  Returns a single TeamMemberWage specified by id .

• labor.listBreakTypes

  Returns a paginated list of BreakType instances for a business.

• labor.listEmployeeWages

  Returns a paginated list of EmployeeWage instances for a business.

• labor.listTeamMemberWages

  Returns a paginated list of TeamMemberWage instances for a business.

• labor.listWorkweekConfigs

  Returns a list of WorkweekConfig instances for a business.

• labor.searchShifts

  Returns a paginated list of Shift records for a business. The list to be returned can be filtered by:

  • Location IDs.
  • Employee IDs.
  • Shift status (OPEN and CLOSED).
  • Shift start.
  • Shift end.
  • Workday details.

  The list can be sorted by:

  • start_at.
  • end_at.
  • created_at.
  • updated_at.
• labor.updateBreakType

  Updates an existing BreakType.

• labor.updateShift

  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.

• labor.updateWorkweekConfig

  Updates a WorkweekConfig.

• locations.createLocation

  Creates a location.

• locations.listLocations

  Provides information of all locations of a business.

  Many Square API endpoints require a location_id parameter. The id field of the Location objects returned by this endpoint correspond to that location_id parameter.

• locations.retrieveLocation

  Retrieves details of a location. You can specify "main" as the location ID to retrieve details of the main location.

• locations.updateLocation

  Updates a location.

• loyalty.accumulateLoyaltyPoints

  Adds points to a loyalty account.

  • If you are using the Orders API to manage orders, you only provide the order_id. The endpoint reads the order to compute points to add to the buyer's account.
  • If you are not using the Orders API to manage orders, you first perform a client-side computation to compute the points.
    For spend-based and visit-based programs, you can first call CalculateLoyaltyPoints to compute the points
    that you provide to this endpoint.

  Note: The country of the seller's Square account determines whether tax is included in the purchase amount when accruing points for spend-based and visit-based programs. For more information, see Availability of Square Loyalty.

• loyalty.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 to add points when a buyer pays for the purchase.

• loyalty.calculateLoyaltyPoints

  Calculates the points a purchase earns.

  • If you are using the Orders API to manage orders, you provide order_id in the request. The endpoint calculates the points by reading the order.
  • If you are not using the Orders API to manage orders, you provide the purchase amount in the request for the endpoint to calculate the points.

  An application might call this endpoint to show the points that a buyer can earn with the specific purchase.

  Note: The country of the seller's Square account determines whether tax is included in the purchase amount when accruing points for spend-based and visit-based programs. For more information, see Availability of Square Loyalty.

• loyalty.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.

• loyalty.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.

• loyalty.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), it updates the order by removing the reward and related discounts.

  You cannot delete a reward that has reached the terminal state (REDEEMED).

• loyalty.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.

  Replaced with RetrieveLoyaltyProgram when used with the keyword main.

• loyalty.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.

• loyalty.retrieveLoyaltyAccount

  Retrieves a loyalty account.

• loyalty.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.

• loyalty.retrieveLoyaltyReward

  Retrieves a loyalty reward.

• loyalty.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.

• loyalty.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.

• loyalty.searchLoyaltyRewards

  Searches for loyalty rewards in a loyalty account.

  In the current implementation, the endpoint supports search by the reward status.

  If you know a reward ID, use the RetrieveLoyaltyReward endpoint.

  Search results are sorted by updated_at in descending order.

• merchants.listMerchants

  Returns Merchant information for a given access token.

  If you don't know a Merchant ID, you can use this endpoint to retrieve the merchant ID for an access token. 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 you access.

  If you know the merchant ID, you can also use the RetrieveMerchant endpoint to get the merchant information.

• merchants.retrieveMerchant

  Retrieve a Merchant object for the given merchant_id.

• mobileAuthorization.createMobileAuthorizationCode

  Generates code to authorize a mobile application to connect to a Square card reader

  Authorization codes are one-time-use and expire 60 minutes after being issued.

  Important: The Authorization header you provide to this endpoint must have the following format:

  Authorization: Bearer ACCESS_TOKEN

  Replace ACCESS_TOKEN with a valid production authorization credential.

• oAuth.obtainToken

  Returns an OAuth access token.

  The endpoint supports distinct methods of obtaining OAuth access tokens. Applications specify a method by adding the grant_type parameter in the request and also provide relevant information.

  Note: Regardless of the method application specified, the endpoint always returns two items; an OAuth access token and a refresh token in the response.

  OAuth tokens should only live on secure servers. Application clients should never interact directly with OAuth tokens.

• oAuth.renewToken

  RenewToken is deprecated. For information about refreshing OAuth access tokens, see Migrate from Renew to Refresh OAuth Tokens.

  Renews an OAuth access token before it expires.

  OAuth access tokens besides your application's personal access token expire after 30 days. You can also renew expired tokens within 15 days of their expiration. You cannot renew an access token that has been expired for more than 15 days. Instead, the associated user must re-complete the OAuth flow from the beginning.

  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 Credentials page in the developer dashboard.

• oAuth.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. When an OAuth access token is revoked, all of the active subscriptions associated with that OAuth token are canceled immediately.

  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 in the developer dashboard.

• orders.batchRetrieveOrders

  Retrieves a set of orders by their IDs.

  If a given order ID does not exist, the ID is ignored instead of generating an error.

• orders.calculateOrder

  Enables applications to preview order pricing without creating an order.

• orders.createOrder

  Creates a new 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.

  You can modify open orders using the UpdateOrder endpoint.

• orders.getV2OrdersOrderId

  Retrieves an Order by ID.

• orders.payOrder

  Pay for an order using one or more approved payments 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. Any approved payments that reference the same order_id not specified in the payment_ids is canceled.
  • Be approved with delayed capture. Using a delayed capture payment with PayOrder completes the approved payment.
• orders.putV2OrdersOrderId

  Updates an open 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 containing only the fields to update and the version to which the update is being applied.
  • If deleting fields, the dot notation paths identifying the fields to clear.

  To pay for an order, see Pay for Orders.

• orders.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 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 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 created, not the time it was subsequently transmitted to Square.

• payments.cancelPayment

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

• payments.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.

• payments.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.

• payments.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.

• payments.getPayment

  Retrieves details for a specific payment.

• payments.getV2Payments

  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.

• payments.updatePayment

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

• refunds.getPaymentRefund

  Retrieves a specific refund using the refund_id.

• refunds.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.

• refunds.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.

• sites.listSites

  Lists the Square Online 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.

• snippets.deleteSnippet

  Removes your snippet from a Square Online site.

  You can call 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.

• snippets.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 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.

• snippets.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 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.

• subscriptions.cancelSubscription

  Sets the canceled_date field to the end of the active billing period. After this date, the status changes from ACTIVE to CANCELED.

• subscriptions.createSubscription

  Creates a subscription for a customer to a subscription plan.

  If you provide a card on file in the request, Square charges the card for the subscription. Otherwise, Square bills 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.

• subscriptions.listSubscriptionEvents

  Lists all events for a specific subscription. In the current implementation, only START_SUBSCRIPTION and STOP_SUBSCRIPTION (when the subscription was canceled) events are returned.

• subscriptions.resumeSubscription

  Resumes a deactivated subscription.

• subscriptions.retrieveSubscription

  Retrieves a subscription.

• subscriptions.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.

  For more information, see Retrieve subscriptions.

• subscriptions.updateSubscription

  Updates a subscription. You can set, modify, and clear the subscription field values.

• team.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.

• team.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.

• team.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.

• team.retrieveTeamMember

  Retrieves a TeamMember object for the given TeamMember.id. Learn about Troubleshooting the Team API.

• team.retrieveWageSetting

  Retrieves a WageSetting object for a team member specified by TeamMember.id. Learn about Troubleshooting the Team API.

• team.searchTeamMembers

  Returns a paginated list of TeamMember objects for a business. The list can be filtered by the following:

  • location IDs
  • status
• team.updateTeamMember

  Updates a single TeamMember object. The TeamMember object is returned on successful updates. Learn about Troubleshooting the Team API.

• team.updateWageSetting

  Creates or updates a WageSetting object. The object is created if a WageSetting with the specified team_member_id does not exist. Otherwise, it fully replaces the WageSetting object for the team member. The WageSetting is returned on a successful update. Learn about Troubleshooting the Team API.

• terminal.cancelTerminalCheckout

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

• terminal.cancelTerminalRefund

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

• terminal.createTerminalCheckout

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

• terminal.createTerminalRefund

  Creates a request to refund an Interac payment completed on a Square Terminal.

• terminal.getTerminalCheckout

  Retrieves a Terminal checkout request by checkout_id.

• terminal.getTerminalRefund

  Retrieves an Interac Terminal refund object by ID.

• terminal.searchTerminalCheckouts

  Retrieves a filtered list of Terminal checkout requests created by the account making the request.

• terminal.searchTerminalRefunds

  Retrieves a filtered list of Interac Terminal refund requests created by the seller making the request.

• transactions.captureTransaction

  Captures a transaction that was created with the Charge endpoint with a delay_capture value of true.

  See Delayed capture transactions for more information.

• transactions.charge

  Charges a card represented by a card nonce or a customer's card on file.

  Your request to this endpoint must include either:

  • A value for the card_nonce parameter (to charge a card payment token generated with the Web Payments SDK)
  • Values for the customer_card_id and customer_id parameters (to charge a customer's card on file)

  In order for an eCommerce payment to potentially qualify for Square chargeback protection, you must provide values for the following parameters in your request:

  • buyer_email_address
  • At least one of billing_address or shipping_address

  When this response is returned, the amount of Square's processing fee might not yet be calculated. To obtain the processing fee, wait about ten seconds and call RetrieveTransaction. See the processing_fee_money field of each Tender included in the transaction.

• transactions.getV2LocationsLocationIdRefunds

  Lists refunds for one of a business's locations.

  In addition to full or partial tender refunds processed through Square APIs, refunds may result from itemized returns or exchanges through Square's Point of Sale applications.

  Refunds with a status of PENDING are not currently included in this endpoint's response.

  Max results per page: 50

• transactions.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: 50

• transactions.postV2LocationsLocationIdTransactionsTransactionIdRefund

  Initiates a refund for a previously charged tender.

  You must issue a refund within 120 days of the associated payment. See this article for more information on refund behavior.

  NOTE: Card-present transactions with Interac credit cards cannot be refunded using the Connect API. Interac transactions must refunded in-person (e.g., dipping the card using POS app).

• transactions.retrieveTransaction

  Retrieves details for a single transaction.

• transactions.voidTransaction

  Cancels a transaction that was created with the Charge endpoint with a delay_capture value of true.

  See Delayed capture transactions for more information.

• v1Employees.createEmployee

  Use the CreateEmployee endpoint to add an employee to a Square account. Employees created with the Connect API have an initial status of INACTIVE. Inactive employees cannot sign in to Square Point of Sale until they are activated from the Square Dashboard. Employee status cannot be changed with the Connect API.

  Employee entities cannot be deleted. To disable employee profiles, set the employee's status to INACTIVE

• v1Employees.createEmployeeRole

  Creates an employee role you can then assign to employees.

  Square accounts can include any number of roles that can be assigned to employees. These roles define the actions and permissions granted to an employee with that role. For example, an employee with a "Shift Manager" role might be able to issue refunds in Square Point of Sale, whereas an employee with a "Clerk" role might not.

  Roles are assigned with the V1UpdateEmployee endpoint. An employee can have only one role at a time.

  If an employee has no role, they have none of the permissions associated with roles. All employees can accept payments with Square Point of Sale.

• v1Employees.listEmployeeRoles

  Provides summary information for all of a business's employee roles.

• v1Employees.listEmployees

  Provides summary information for all of a business's employees.

• v1Employees.retrieveEmployee

  Provides the details for a single employee.

• v1Employees.retrieveEmployeeRole

  Provides the details for a single employee role.

• v1Employees.updateEmployee
• v1Employees.updateEmployeeRole

  Modifies the details of an employee role.

• v1Transactions.createRefund

  Issues a refund for a previously processed payment. You must issue a refund within 60 days of the associated payment.

  You cannot issue a partial refund for a split tender payment. You must instead issue a full or partial refund for a particular tender, by providing the applicable tender id to the V1CreateRefund endpoint. Issuing a full refund for a split tender payment refunds all tenders associated with the payment.

  Issuing a refund for a card payment is not reversible. For development purposes, you can create fake cash payments in Square Point of Sale and refund them.

• v1Transactions.listOrders

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

• v1Transactions.listPayments

  Provides summary information for all payments taken for a given Square account during a date range. Date ranges cannot exceed 1 year in length. See Date ranges for details of inclusive and exclusive dates.

  Note*: Details for payments processed with Square Point of Sale while in offline mode may not be transmitted to Square for up to 72 hours. Offline payments have a created_at value that reflects the time the payment was originally processed, not the time it was subsequently transmitted to Square. Consequently, the ListPayments endpoint might list an offline payment chronologically between online payments that were seen in a previous request.***

• v1Transactions.listRefunds

  Provides the details for all refunds initiated by a merchant or any of the merchant's mobile staff during a date range. Date ranges cannot exceed one year in length.

• v1Transactions.listSettlements

  Provides summary information for all deposits and withdrawals initiated by Square to a linked bank account during a date range. Date ranges cannot exceed one year in length.

  Note*: the ListSettlements endpoint does not provide entry information.***

• v1Transactions.retrieveOrder

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

• v1Transactions.retrievePayment

  Provides comprehensive information for a single payment.

• v1Transactions.retrieveSettlement

  Provides comprehensive information for a single settlement.

  The returned Settlement objects include an entries field that lists the transactions that contribute to the settlement total. Most settlement entries correspond to a payment payout, but settlement entries are also generated for less common events, like refunds, manual adjustments, or chargeback holds.

  Square initiates its regular deposits as indicated in the Deposit Options with Square help article. Details for a regular deposit are usually not available from Connect API endpoints before 10 p.m. PST the same day.

  Square does not know when an initiated settlement completes, only whether it has failed. A completed settlement is typically reflected in a bank account within 3 business days, but in exceptional cases it may take longer.

• v1Transactions.updateOrder

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

• openapi.previewSpec

  Preview an OpenAPI document before adding it as a source

• openapi.addSource

  Add an OpenAPI source and register its operations as tools