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 lists show all the Square API services, their endpoints, and the OAuth scopes (permissions) needed to access them.

BankAccounts
Permalink Get a link to this section

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

API
Permissions
GetBankAccountBANK_ACCOUNTS_READ
ListBankAccountsBANK_ACCOUNTS_READ
GetBankAccountByV1IdBANK_ACCOUNTS_READ

Catalog
Permalink Get a link to this section

Sync items to Square POS to itemize payments consistently across all channels.

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

CashDrawerShifts
Permalink Get a link to this section

Get details about cash drawer shifts.

API
Permissions
ListCashDrawerShiftsCASH_DRAWER_READ
ListCashDrawerShiftEventsCASH_DRAWER_READ
RetrieveCashDrawerShiftCASH_DRAWER_READ

Checkout
Permalink Get a link to this section

Accept itemized payments on a Square-hosted web page. No frontend experience required.

API
Permissions
CreateCheckoutORDERS_WRITE
PAYMENTS_WRITE
PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS

Customers
Permalink Get a link to this section

Save cards on file for customers and sync CRM systems with Square.

API
Permissions
AddGroupToCustomerCUSTOMERS_WRITE
CreateCustomerCUSTOMERS_WRITE
CreateCustomerCardCUSTOMERS_WRITE
DeleteCustomerCUSTOMERS_WRITE
DeleteCustomerCardCUSTOMERS_WRITE
ListCustomersCUSTOMERS_READ
RemoveGroupFromCustomerCUSTOMERS_WRITE
RetrieveCustomerCUSTOMERS_READ
SearchCustomersCUSTOMERS_READ
UpdateCustomerCUSTOMERS_WRITE

CustomerGroups
Permalink Get a link to this section

Manage Customers by Groups.

API
Permissions
CreateCustomerGroupCUSTOMERS_WRITE
DeleteCustomerGroupCUSTOMERS_WRITE
ListCustomerGroupsCUSTOMERS_READ
RetrieveCustomerGroupCUSTOMERS_READ
UpdateCustomerGroupCUSTOMERS_READ
CUSTOMERS_WRITE

CustomerSegments
Permalink Get a link to this section

Manage Customers by Segments.

API
Permissions
ListCustomerSegmentsCUSTOMERS_READ
RetrieveCustomerSegmentCUSTOMERS_READ

Devices
Permalink Get a link to this section

Use the Devices API to configure a Square Terminal.

API
Permissions
CreateDeviceCodeDEVICE_CREDENTIAL_MANAGEMENT
GetDeviceCodeDEVICE_CREDENTIAL_MANAGEMENT
ListDeviceCodesDEVICE_CREDENTIAL_MANAGEMENT

Disputes
Permalink Get a link to this section

Use the Disputes API to manage disputes (chargebacks).

API
Permissions
AcceptDisputePAYMENTS_WRITE
CreateDisputeEvidenceFilePAYMENTS_WRITE
CreateDisputeEvidenceTextPAYMENTS_WRITE
ListDisputeEvidencePAYMENTS_READ
ListDisputesPAYMENTS_READ
RemoveDisputeEvidencePAYMENTS_WRITE
RetrieveDisputePAYMENTS_READ
RetrieveDisputeEvidencePAYMENTS_READ
SubmitEvidencePAYMENTS_WRITE

Employees
Permalink Get a link to this section

Provides a query endpoint to get a list of the employees for a seller.

API
Permissions
ListEmployeesEMPLOYEES_READ
RetrieveEmployeeEMPLOYEES_READ

Inventory
Permalink Get a link to this section

Keep an inventory of catalog items in sync across all commerce channels.

API
Permissions
BatchChangeInventoryINVENTORY_WRITE
BatchRetrieveInventoryCountsINVENTORY_READ
BatchRetrieveInventoryChangesINVENTORY_READ
RetrieveInventoryAdjustmentINVENTORY_READ
RetrieveInventoryChangesINVENTORY_READ
RetrieveInventoryCountINVENTORY_READ
RetrieveInventoryPhysicalCountINVENTORY_READ

Labor
Permalink Get a link to this section

Manage shifts, breaks, and wages for employees in Square POS.

API
Permissions
CreateBreakTypeTIMECARDS_SETTINGS_WRITE
CreateShiftTIMECARDS_WRITE
DeleteBreakTypeTIMECARDS_SETTINGS_WRITE
DeleteShiftTIMECARDS_SETTINGS_WRITE
GetBreakTypeTIMECARDS_SETTINGS_READ
GetEmployeeWageEMPLOYEES_READ
GetShiftTIMECARDS_READ
ListBreakTypesTIMECARDS_SETTINGS_READ
ListEmployeeWagesEMPLOYEES_READ
ListWorkweekConfigsTIMECARDS_SETTINGS_READ
SearchShiftsTIMECARDS_READ
UpdateShiftTIMECARDS_WRITE
TIMECARDS_READ
UpdateWorkweekConfigTIMECARDS_SETTINGS_READ
TIMECARDS_SETTINGS_WRITE
UpdateBreakTypeTIMECARDS_SETTINGS_READ
TIMECARDS_SETTINGS_WRITE

Locations
Permalink Get a link to this section

Get a list of a seller's locations.

API
Permissions
CreateLocationMERCHANT_PROFILE_WRITE
ListLocationsMERCHANT_PROFILE_READ
RetrieveLocationMERCHANT_PROFILE_READ
UpdateLocationMERCHANT_PROFILE_WRITE

Loyalty
Permalink Get a link to this section

Provides endpoints to access the buyer loyalty program.

API
Permissions
AccumulateLoyaltyPointsLOYALTY_WRITE
AdjustLoyaltyPointsLOYALTY_WRITE
CalculateLoyaltyPointsLOYALTY_READ
CreateLoyaltyAccountLOYALTY_WRITE
CreateLoyaltyOrderAssignmentLOYALTY_WRITE
ORDERS_READ
CreateLoyaltyRewardLOYALTY_WRITE
DeleteLoyaltyRewardLOYALTY_WRITE
ListLoyaltyProgramsLOYALTY_READ
RedeemLoyaltyRewardLOYALTY_WRITE
RetrieveLoyaltyAccountLOYALTY_READ
RetrieveLoyaltyProgramOrderAssignmentLOYALTY_READ
ORDERS_READ
RetrieveLoyaltyRewardLOYALTY_READ
SearchLoyaltyAccountsLOYALTY_READ
SearchLoyaltyEventsLOYALTY_READ
SearchLoyaltyRewardsLOYALTY_READ

Merchants
Permalink Get a link to this section

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

API
Permissions
ListMerchantsMERCHANT_PROFILE_READ
RetrieveMerchantMERCHANT_PROFILE_READ

Mobile Authorization
Permalink Get a link to this section

Provides an endpoint for getting a mobile authorization code for use in Reader SDK applications.

API
Permissions
CreateMobileAuthorizationCodePAYMENTS_WRITE_IN_PERSON

Orders
Permalink Get a link to this section

Get sales data for a Square seller, itemize payments, push orders to POS, and more.

API
Permissions
CalculateOrderN/A
CreateOrderORDERS_WRITE
BatchRetrieveOrdersORDERS_READ
PayOrderORDERS_WRITE
PAYMENTS_WRITE
SearchOrdersORDERS_READ
UpdateOrderORDERS_WRITE

Payments and Refunds
Permalink Get a link to this section

The Payments API lets developers take and manage payments.

API
Permissions
CancelPaymentPAYMENTS_WRITE
CancelPaymentByIdempotencyKeyPAYMENTS_WRITE
CompletePaymentPAYMENTS_WRITE
CreatePaymentPAYMENTS_WRITE
PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS
GetPaymentPAYMENTS_READ
GetPaymentRefundPAYMENTS_READ
ListPaymentsPAYMENTS_READ
ListPaymentRefundsPAYMENTS_READ
RefundPaymentPAYMENTS_WRITE
PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS

Teams
Permalink Get a link to this section

The Teams API lets developers manage team members and integrate Square with a 3rd party payroll system.

API
Permissions
BulkCreateTeamMembersEMPLOYEES_WRITE
BulkUpdateTeamMembersEMPLOYEES_WRITE
CreateTeamMemberEMPLOYEES_WRITE
UpdateTeamMemberEMPLOYEES_WRITE
RetrieveTeamMemberEMPLOYEES_READ
RetrieveWageSettingEMPLOYEES_READ
SearchTeamMembersEMPLOYEES_READ
UpdateWageSettingEMPLOYEES_READ

Terminal
Permalink Get a link to this section

The Terminal API lets developers request Square Terminal checkouts.

API
Permissions
CreateTerminalCheckoutPAYMENTS_WRITE
CancelTerminalCheckoutPAYMENTS_WRITE
GetTerminalCheckoutPAYMENTS_READ
SearchTerminalCheckoutsPAYMENTS_READ