Reference for all OAuth permissions (scopes) needed to call Square API endpoints with an OAuth access token.
OAuth API

OAuth Permissions Reference

To get a scoped OAuth access token used in calling a Square API endpoint, you need to specify the permissions that your application needs to access Square account resources. The permissions you specify are shown to the user in an authorization dialog box that lets the user grant access to your application.

The following sections list and describe all the Square API services, their endpoints, and the OAuth scopes (permissions) needed to access them.

The Bank Accounts API lets developers retrieve information about the bank accounts linked to a Square account.

API
Permission
GetBankAccountBANK_ACCOUNTS_READ
ListBankAccountsBANK_ACCOUNTS_READ
GetBankAccountByV1IdBANK_ACCOUNTS_READ

The Bookings API creates and maintains service appointments.

API
Permission
CreateBookingAPPOINTMENTS_WRITE (buyer-level). APPOINTMENTS_WRITE and APPOINTMENTS_ALL_WRITE (seller-level).
SearchAvailabilityAPPOINTMENTS_READ (buyer-level). APPOINTMENTS_READ and APPOINTMENTS_ALL_READ (seller-level).
RetrieveBusinessBookingProfileAPPOINTMENTS_BUSINESS_SETTINGS_READ
ListTeamMemberBookingProfilesAPPOINTMENTS_BUSINESS_SETTINGS_READ
RetrieveTeamMemberBookingProfileAPPOINTMENTS_BUSINESS_SETTINGS_READ
ListBookingsAPPOINTMENTS_READ (buyer-level). APPOINTMENTS_READ and APPOINTMENTS_ALL_READ (seller-level).
RetrieveBookingAPPOINTMENTS_READ (buyer-level). APPOINTMENTS_READ and APPOINTMENTS_ALL_READ (seller-level).
UpdateBookingAPPOINTMENTS_WRITE(buyer-level). APPOINTMENTS_WRITE and APPOINTMENTS_ALL_WRITE (seller-level).
CancelBookingAPPOINTMENTS_WRITE (buyer-level). APPOINTMENTS_WRITE and APPOINTMENTS_ALL_WRITE (seller-level).

The Booking Custom Attributes API lets you create and manage custom attributes for bookings.

API
Permission
CreateBookingCustomAttributeDefinitionBuyer-level: APPOINTMENTS_WRITE
Seller-level: APPOINTMENTS_WRITE and APPOINTMENTS_ALL_WRITE
UpdateBookingCustomAttributeDefinitionBuyer-level: APPOINTMENTS_WRITE
Seller-level: APPOINTMENTS_WRITE and APPOINTMENTS_ALL_WRITE
ListBookingCustomAttributeDefinitionsBuyer-level: APPOINTMENTS_READ
Seller-level: APPOINTMENTS_READ and APPOINTMENTS_ALL_READ
RetrieveBookingCustomAttributeDefinitionBuyer-level: APPOINTMENTS_READ
Seller-level: APPOINTMENTS_READ and APPOINTMENTS_ALL_READ
DeleteBookingCustomAttributeDefinitionBuyer-level: APPOINTMENTS_WRITE
Seller-level: APPOINTMENTS_WRITE and APPOINTMENTS_ALL_WRITE
UpsertBookingCustomAttributeBuyer-level: APPOINTMENTS_WRITE
Seller-level: APPOINTMENTS_WRITE and APPOINTMENTS_ALL_WRITE
BulkUpsertBookingCustomAttributesBuyer-level: APPOINTMENTS_WRITE
Seller-level: APPOINTMENTS_WRITE and APPOINTMENTS_ALL_WRITE
ListBookingCustomAttributesBuyer-level: APPOINTMENTS_READ
Seller-level: APPOINTMENTS_READ and APPOINTMENTS_ALL_READ
RetrieveBookingCustomAttributeBuyer-level: APPOINTMENTS_READ
Seller-level: APPOINTMENTS_READ and APPOINTMENTS_ALL_READ
DeleteBookingCustomAttributeBuyer-level: APPOINTMENTS_WRITE
Seller-level: APPOINTMENTS_WRITE and APPOINTMENTS_ALL_WRITE

The Cards API provides endpoints to access a payment card stored on file.

API
Permissions
ListCardsPAYMENTS_READ
CreateCardPAYMENTS_WRITE
RetrieveCardPAYMENTS_READ
DisableCardPAYMENTS_WRITE

The Cash Drawer Shifts API provides details about cash drawer shifts.

API
Permission
ListCashDrawerShiftsCASH_DRAWER_READ
ListCashDrawerShiftEventsCASH_DRAWER_READ
RetrieveCashDrawerShiftCASH_DRAWER_READ

The Catalog API syncs items to Square Point of Sale to itemize payments consistently across all channels.

API
Permission
BatchDeleteCatalogObjectsITEMS_WRITE
BatchUpsertCatalogObjectsITEMS_WRITE
BatchRetrieveCatalogObjectsITEMS_READ
CatalogInfoITEMS_READ
CreateCatalogImageITEMS_WRITE
DeleteCatalogObjectITEMS_WRITE
ListCatalogITEMS_READ
RetrieveCatalogObjectITEMS_READ
SearchCatalogItemsITEMS_READ
SearchCatalogObjectsITEMS_READ
UpdateItemTaxesITEMS_WRITE
UpdateItemModifierListsITEMS_WRITE
UpsertCatalogObjectITEMS_WRITE

The Checkout API accepts itemized payments on a Square-hosted web page. No frontend experience is required.

API
Permission
CreatePaymentLinkORDERS_WRITE
ORDERS_READ
PAYMENTS_WRITE

The Customers API creates and manages customer profiles and syncs customer relationship management (CRM) systems with Square.

API
Permission
AddGroupToCustomerCUSTOMERS_WRITE
CreateCustomerCUSTOMERS_WRITE
CreateCustomerCard (deprecated)CUSTOMERS_WRITE
DeleteCustomerCUSTOMERS_WRITE
DeleteCustomerCard (deprecated)CUSTOMERS_WRITE
ListCustomersCUSTOMERS_READ
RemoveGroupFromCustomerCUSTOMERS_WRITE
RetrieveCustomerCUSTOMERS_READ
SearchCustomersCUSTOMERS_READ
UpdateCustomerCUSTOMERS_WRITE

The Customer Custom Attributes API lets you create and manage custom attributes for customer profiles.

API
Permission
CreateCustomerCustomAttributeDefinitionCUSTOMERS_WRITE
UpdateCustomerCustomAttributeDefinitionCUSTOMERS_WRITE
ListCustomerCustomAttributeDefinitionsCUSTOMERS_READ
RetrieveCustomerCustomAttributeDefinitionCUSTOMERS_READ
DeleteCustomerCustomAttributeDefinitionCUSTOMERS_WRITE
UpsertCustomerCustomAttributeCUSTOMERS_WRITE
BulkUpsertCustomerCustomAttributesCUSTOMERS_WRITE
ListCustomerCustomAttributesCUSTOMERS_READ
RetrieveCustomerCustomAttributeCUSTOMERS_READ
DeleteCustomerCustomAttributeCUSTOMERS_WRITE

The Customer Groups API manages customers by groups.

API
Permission
CreateCustomerGroupCUSTOMERS_WRITE
DeleteCustomerGroupCUSTOMERS_WRITE
ListCustomerGroupsCUSTOMERS_READ
RetrieveCustomerGroupCUSTOMERS_READ
UpdateCustomerGroupCUSTOMERS_WRITE

The Customer Segments API manages customers by segments.

API
Permission
ListCustomerSegmentsCUSTOMERS_READ
RetrieveCustomerSegmentCUSTOMERS_READ

Use the Devices API to configure a Square Terminal.

API
Permission
CreateDeviceCodeDEVICE_CREDENTIAL_MANAGEMENT
GetDeviceCodeDEVICE_CREDENTIAL_MANAGEMENT
ListDeviceCodesDEVICE_CREDENTIAL_MANAGEMENT

Use the Disputes API to manage disputes (chargebacks).

API
Permission
AcceptDisputeDISPUTES_WRITE
CreateDisputeEvidenceFileDISPUTES_WRITE
CreateDisputeEvidenceTextDISPUTES_WRITE
ListDisputeEvidenceDISPUTES_READ
ListDisputesDISPUTES_READ
DeleteDisputeEvidenceDISPUTES_WRITE
RetrieveDisputeDISPUTES_READ
RetrieveDisputeEvidenceDISPUTES_READ
SubmitEvidenceDISPUTES_WRITE

The Employees API provides a query endpoint to get a list of the employees for a seller.

API
Permission
ListEmployeesEMPLOYEES_READ
RetrieveEmployeeEMPLOYEES_READ

The Gift Cards API provides endpoints to create and manage gift cards.

API
Permission
ListGiftCardsGIFTCARDS_READ
CreateGiftCardGIFTCARDS_WRITE
RetrieveGiftCardFromGANGIFTCARDS_READ
RetrieveGiftCardFromNonceGIFTCARDS_READ
LinkCustomerToGiftCardGIFTCARDS_WRITE
UnlinkCustomerFromGiftCardGIFTCARDS_WRITE
RetrieveGiftCardGIFTCARDS_READ

The Gift Card Activities API provides endpoints to create gift card activities, such as activate a gift card, add funds to a gift card, and redeem a gift card.

API
Permission
ListGiftCardActivitiesGIFTCARDS_READ
CreateGiftCardActivityGIFTCARDS_WRITE

The Inventory API keeps an inventory of catalog items in sync across all commerce channels.

API
Permission
BatchChangeInventoryINVENTORY_WRITE
BatchRetrieveInventoryCountsINVENTORY_READ
BatchRetrieveInventoryChangesINVENTORY_READ
RetrieveInventoryAdjustmentINVENTORY_READ
RetrieveInventoryChangesINVENTORY_READ
RetrieveInventoryCountINVENTORY_READ
RetrieveInventoryPhysicalCountINVENTORY_READ

Use the Invoices API to manage invoices.

API
Permissions
ListInvoicesINVOICES_READ
CreateInvoiceORDERS_WRITE
INVOICES_WRITE
SearchInvoicesINVOICES_READ
DeleteInvoiceORDERS_WRITE
INVOICES_WRITE
GetInvoiceINVOICES_READ
UpdateInvoiceORDERS_WRITE
INVOICES_WRITE
CancelInvoiceORDERS_WRITE
INVOICES_WRITE
PublishInvoiceORDERS_WRITE
INVOICES_WRITE

The Labor API manages shifts, breaks, and wages for employees in Square Point of Sale.

API
Permission
CreateBreakTypeTIMECARDS_SETTINGS_WRITE
CreateShiftTIMECARDS_WRITE
DeleteBreakTypeTIMECARDS_SETTINGS_WRITE
DeleteShiftTIMECARDS_WRITE
GetBreakTypeTIMECARDS_SETTINGS_READ
GetTeamMemberWageEMPLOYEES_READ
GetShiftTIMECARDS_READ
ListBreakTypesTIMECARDS_SETTINGS_READ
ListTeamMemberWagesEMPLOYEES_READ
ListWorkweekConfigsTIMECARDS_SETTINGS_READ
SearchShiftsTIMECARDS_READ
UpdateShiftTIMECARDS_WRITE
TIMECARDS_READ
UpdateWorkweekConfigTIMECARDS_SETTINGS_READ
TIMECARDS_SETTINGS_WRITE
UpdateBreakTypeTIMECARDS_SETTINGS_READ
TIMECARDS_SETTINGS_WRITE

The Locations API gets a list of a seller's locations.

API
Permission
CreateLocationMERCHANT_PROFILE_WRITE
ListLocationsMERCHANT_PROFILE_READ
RetrieveLocationMERCHANT_PROFILE_READ
UpdateLocationMERCHANT_PROFILE_WRITE

The Location Custom Attributes API lets you create and manage custom attributes for locations.

API
Permission
CreateLocationCustomAttributeDefinitionMERCHANT_PROFILE_WRITE
UpdateLocationCustomAttributeDefinitionMERCHANT_PROFILE_WRITE
ListLocationCustomAttributeDefinitionsMERCHANT_PROFILE_READ
RetrieveLocationCustomAttributeDefinitionMERCHANT_PROFILE_READ
DeleteLocationCustomAttributeDefinitionMERCHANT_PROFILE_WRITE
UpsertLocationCustomAttributeMERCHANT_PROFILE_WRITE
BulkUpsertLocationCustomAttributesMERCHANT_PROFILE_WRITE
ListLocationCustomAttributesMERCHANT_PROFILE_READ
RetrieveLocationCustomAttributeMERCHANT_PROFILE_READ
DeleteLocationCustomAttributeMERCHANT_PROFILE_WRITE
BulkDeleteLocationCustomAttributesMERCHANT_PROFILE_WRITE

The Loyalty API provides endpoints to work with loyalty programs, loyalty promotions, loyalty accounts, loyalty points, loyalty rewards, and loyalty events.

API
Permission
RetrieveLoyaltyProgramLOYALTY_READ
ListLoyaltyPrograms (deprecated)LOYALTY_READ
CreateLoyaltyPromotionLOYALTY_WRITE
ListLoyaltyPromotionsLOYALTY_READ
RetrieveLoyaltyPromotionLOYALTY_READ
CancelLoyaltyPromotionLOYALTY_WRITE
CreateLoyaltyAccountLOYALTY_WRITE
RetrieveLoyaltyAccountLOYALTY_READ
SearchLoyaltyAccountsLOYALTY_READ
AccumulateLoyaltyPointsLOYALTY_WRITE
AdjustLoyaltyPointsLOYALTY_WRITE
CalculateLoyaltyPointsLOYALTY_READ
CreateLoyaltyRewardLOYALTY_WRITE
RedeemLoyaltyRewardLOYALTY_WRITE
RetrieveLoyaltyRewardLOYALTY_READ
SearchLoyaltyRewardsLOYALTY_READ
DeleteLoyaltyRewardLOYALTY_WRITE
SearchLoyaltyEventsLOYALTY_READ

Use the Merchants API to retrieve information about a Square merchant account.

API
Permission
ListMerchantsMERCHANT_PROFILE_READ
RetrieveMerchantMERCHANT_PROFILE_READ

The Merchant Custom Attributes API lets you create and manage custom attributes for merchants.

API
Permission
CreateMerchantCustomAttributeDefinitionMERCHANT_PROFILE_WRITE
UpdateMerchantCustomAttributeDefinitionMERCHANT_PROFILE_WRITE
ListMerchantCustomAttributeDefinitionsMERCHANT_PROFILE_READ
RetrieveMerchantCustomAttributeDefinitionMERCHANT_PROFILE_READ
DeleteMerchantCustomAttributeDefinitionMERCHANT_PROFILE_WRITE
UpsertMerchantCustomAttributeMERCHANT_PROFILE_WRITE
BulkUpsertMerchantCustomAttributesMERCHANT_PROFILE_WRITE
ListMerchantCustomAttributesMERCHANT_PROFILE_READ
RetrieveMerchantCustomAttributeMERCHANT_PROFILE_READ
DeleteMerchantCustomAttributeMERCHANT_PROFILE_WRITE
BulkDeleteMerchantCustomAttributesMERCHANT_PROFILE_WRITE

The Mobile Authorization API provides an endpoint for getting a mobile authorization code for use in Reader SDK applications.

API
Permission
CreateMobileAuthorizationCodePAYMENTS_WRITE_IN_PERSON

The Orders API gets sales data for a Square seller, itemize payments, push orders to Point of Sale, and more.

API
Permission
CalculateOrderN/A
CloneOrderORDERS_WRITE
CreateOrderORDERS_WRITE
BatchRetrieveOrdersORDERS_READ
PayOrderORDERS_WRITE
PAYMENTS_WRITE
RetrieveOrderORDERS_WRITE
ORDERS_READ
SearchOrdersORDERS_READ
UpdateOrderORDERS_WRITE

The Payments API lets developers take and manage payments. The Refunds API lets developers refund payments.

API
Permission
CancelPaymentPAYMENTS_WRITE
CancelPaymentByIdempotencyKeyPAYMENTS_WRITE
CompletePaymentPAYMENTS_WRITE
CreatePaymentPAYMENTS_WRITE
PAYMENTS_WRITE_SHARED_ONFILE
PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS
GetPaymentPAYMENTS_READ
GetPaymentRefundPAYMENTS_READ
ListPaymentsPAYMENTS_READ
ListPaymentRefundsPAYMENTS_READ
RefundPaymentPAYMENTS_WRITE
PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS

Use the Payouts API to see a list of deposits and withdrawals from a seller’s external bank account, a Square checking or savings account (available only in the United States), or a debit card (for instant transfers).

API
Permission
ListPayoutsPAYOUTS_READ
GetPayoutPAYOUTS_READ
ListPayoutEntriesPAYOUTS_READ

Use the Sites API to list the Square Online sites for a seller account.

API
Permissions
ListSitesONLINE_STORE_SITE_READ

Use the Snippets API to manage snippets on Square Online sites.

API
Permissions
UpsertSnippetONLINE_STORE_SNIPPETS_WRITE
RetrieveSnippetONLINE_STORE_SNIPPETS_READ
DeleteSnippetONLINE_STORE_SNIPPETS_WRITE

Use the Subscriptions API to manage subscriptions. For more information about required permissions to create and update subscriptions, see Requirements and limitations.

API
Permissions
CreateSubscriptionCUSTOMERS_READ
PAYMENTS_WRITE
SUBSCRIPTIONS_WRITE
ITEMS_READ
ORDERS_WRITE
INVOICES_WRITE
SearchSubscriptionsSUBSCRIPTIONS_READ
RetrieveSubscriptionSUBSCRIPTIONS_READ
UpdateSubscriptionCUSTOMERS_READ
PAYMENTS_WRITE
SUBSCRIPTIONS_WRITE
ITEMS_READ
ORDERS_WRITE
INVOICES_WRITE
CancelSubscriptionSUBSCRIPTIONS_WRITE
ListSubscriptionEventsSUBSCRIPTIONS_READ
ResumeSubscriptionCUSTOMERS_READ
PAYMENTS_WRITE
SUBSCRIPTIONS_WRITE
ITEMS_READ
ORDERS_WRITE
INVOICES_WRITE
PauseSubscriptionCUSTOMERS_READ
PAYMENTS_WRITE
SUBSCRIPTIONS_WRITE
ITEMS_READ
ORDERS_WRITE
INVOICES_WRITE
SwapPlanCUSTOMERS_READ
PAYMENTS_WRITE
SUBSCRIPTIONS_WRITE
ITEMS_READ
ORDERS_WRITE
INVOICES_WRITE
DeleteSubscriptionActionSUBSCRIPTIONS_WRITE

The Team API lets developers manage team members and integrate Square with a third-party payroll system.

API
Permission
BulkCreateTeamMembersEMPLOYEES_WRITE
BulkUpdateTeamMembersEMPLOYEES_WRITE
CreateTeamMemberEMPLOYEES_WRITE
UpdateTeamMemberEMPLOYEES_WRITE
RetrieveTeamMemberEMPLOYEES_READ
RetrieveWageSettingEMPLOYEES_READ
SearchTeamMembersEMPLOYEES_READ
UpdateWageSettingEMPLOYEES_WRITE

The Terminal API lets developers request Square Terminal checkouts and process Interac refunds.

API
Permission
CreateTerminalCheckoutPAYMENTS_WRITE
CancelTerminalCheckoutPAYMENTS_WRITE
GetTerminalCheckoutPAYMENTS_READ
SearchTerminalCheckoutsPAYMENTS_READ
CreateTerminalRefundPAYMENTS_WRITE
CancelTerminalRefundPAYMENTS_WRITE
GetTerminalRefundPAYMENTS_READ
SearchTerminalRefundsPAYMENTS_READ
CreateTerminalActionPAYMENTS_WRITE
CancelTerminalActionPAYMENTS_WRITE
GetTerminalActionPAYMENTS_READ
CUSTOMERS_READ
SearchTerminalActionPAYMENTS_READ

The Vendors API supports managing a seller's suppliers in an application.

API
Permission
BulkCreateVendorsVENDOR_WRITE
BulkRetrieveVendorsVENDOR_READ
BulkUpdateVendorsVENDOR_WRITE
CreateVendorVENDOR_WRITE
SearchVendorsVENDOR_READ
RetrieveVendorVENDOR_READ
UpdateVendorsVENDOR_WRITE