OAuth Permissions Reference

Applies to: OAuth API

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

Link to section

Overview

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

Link to section

Bookings

The Bookings API creates and maintains service appointments.

APIPermission
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).
Link to section

Booking Custom Attributes

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

APIPermission
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
Link to section

Catalog

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

Link to section

Checkout

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

APIPermission
CreatePaymentLinkORDERS_WRITE
ORDERS_READ
PAYMENTS_WRITE
Link to section

Customers

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

APIPermission
AddGroupToCustomerCUSTOMERS_WRITE
BulkCreateCustomersCUSTOMERS_WRITE
BulkDeleteCustomersCUSTOMERS_WRITE
BulkRetrieveCustomersCUSTOMERS_READ
BulkUpdateCustomersCUSTOMERS_WRITE
CreateCustomerCUSTOMERS_WRITE
CreateCustomerCard (deprecated)CUSTOMERS_WRITE
DeleteCustomerCUSTOMERS_WRITE
DeleteCustomerCard (deprecated)CUSTOMERS_WRITE
ListCustomersCUSTOMERS_READ
RemoveGroupFromCustomerCUSTOMERS_WRITE
RetrieveCustomerCUSTOMERS_READ
SearchCustomersCUSTOMERS_READ
UpdateCustomerCUSTOMERS_WRITE
Link to section

Customer Custom Attributes

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

Link to section

Employees

Retrieves employees for a seller. The Employees API is deprecated and replaced by the Team API.

APIPermission
ListEmployees (deprecated)EMPLOYEES_READ
RetrieveEmployee (deprecated)EMPLOYEES_READ
Link to section

Gift Cards

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

APIPermission
ListGiftCardsGIFTCARDS_READ
CreateGiftCardGIFTCARDS_WRITE
RetrieveGiftCardGIFTCARDS_READ
RetrieveGiftCardFromGANGIFTCARDS_READ
RetrieveGiftCardFromNonceGIFTCARDS_READ
LinkCustomerToGiftCardGIFTCARDS_WRITE
UnlinkCustomerFromGiftCardGIFTCARDS_WRITE
Link to section

Gift Card Activities

The Gift Card Activities API provides endpoints to create gift card activities, such as activating a gift card, adding funds to a gift card, and redeeming a gift card.

APIPermission
ListGiftCardActivitiesGIFTCARDS_READ
CreateGiftCardActivityGIFTCARDS_WRITE
Link to section

Invoices

Use the Invoices API to manage invoices.

APIPermissions
CreateInvoiceORDERS_WRITE
INVOICES_WRITE
PublishInvoiceORDERS_WRITE
INVOICES_WRITE
CUSTOMERS_READ and PAYMENTS_WRITE (for Square to charge cards on file)
GetInvoiceINVOICES_READ
ListInvoicesINVOICES_READ
SearchInvoicesINVOICES_READ
CreateInvoiceAttachmentORDERS_WRITE
INVOICES_WRITE
DeleteInvoiceAttachmentORDERS_WRITE
INVOICES_WRITE
UpdateInvoiceORDERS_WRITE
INVOICES_WRITE
DeleteInvoiceORDERS_WRITE
INVOICES_WRITE
CancelInvoiceORDERS_WRITE
INVOICES_WRITE
Link to section

Labor

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

APIPermission
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
Link to section

Location Custom Attributes

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

Link to section

Loyalty

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

APIPermission
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
Link to section

Merchant Custom Attributes

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

Link to section

Order Custom Attributes

The Order Custom Attributes API lets you create and manage custom attributes for orders.

Link to section

Payments and Refunds

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

APIPermission
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
Link to section

Payouts

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

APIPermission
ListPayoutsPAYOUTS_READ
GetPayoutPAYOUTS_READ
ListPayoutEntriesPAYOUTS_READ
Link to section

Sites

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

APIPermissions
ListSitesONLINE_STORE_SITE_READ
Link to section

Subscriptions

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

APIPermissions
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
Link to section

Terminal

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

APIPermission
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