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

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

API	Permissions
GetBankAccount	`BANK_ACCOUNTS_READ`
ListBankAccounts	`BANK_ACCOUNTS_READ`
GetBankAccountByV1Id	`BANK_ACCOUNTS_READ`

Catalog

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

API	Permissions
BatchDeleteCatalogObjects	`ITEMS_WRITE`
BatchUpsertCatalogObjects	`ITEMS_WRITE`
BatchRetrieveCatalogObjects	`ITEMS_READ`
CatalogInfo	`ITEMS_READ`
CreateCatalogImage	`ITEMS_WRITE`
DeleteCatalogObject	`ITEMS_WRITE`
ListCatalog	`ITEMS_READ`
RetrieveCatalogObject	`ITEMS_READ`
SearchCatalogObjects	`ITEMS_READ`
UpdateItemTaxes	`ITEMS_WRITE`
UpdateItemModifierLists	`ITEMS_WRITE`
UpsertCatalogObject	`ITEMS_WRITE`

CashDrawerShifts

Get details about cash drawer shifts.

API	Permissions
ListCashDrawerShifts	`CASH_DRAWER_READ`
ListCashDrawerShiftEvents	`CASH_DRAWER_READ`
RetrieveCashDrawerShift	`CASH_DRAWER_READ`

Checkout

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

API	Permissions
CreateCheckout	`ORDERS_WRITE` `PAYMENTS_WRITE` `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS`

Customers

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

API	Permissions
AddGroupToCustomer	`CUSTOMERS_WRITE`
CreateCustomer	`CUSTOMERS_WRITE`
CreateCustomerCard	`CUSTOMERS_WRITE`
DeleteCustomer	`CUSTOMERS_WRITE`
DeleteCustomerCard	`CUSTOMERS_WRITE`
ListCustomers	`CUSTOMERS_READ`
RemoveGroupFromCustomer	`CUSTOMERS_WRITE`
RetrieveCustomer	`CUSTOMERS_READ`
SearchCustomers	`CUSTOMERS_READ`
UpdateCustomer	`CUSTOMERS_WRITE`

CustomerGroups

Manage Customers by Groups.

API	Permissions
CreateCustomerGroup	`CUSTOMERS_WRITE`
DeleteCustomerGroup	`CUSTOMERS_WRITE`
ListCustomerGroups	`CUSTOMERS_READ`
RetrieveCustomerGroup	`CUSTOMERS_READ`
UpdateCustomerGroup	`CUSTOMERS_READ` `CUSTOMERS_WRITE`

CustomerSegments

Manage Customers by Segments.

API	Permissions
ListCustomerSegments	`CUSTOMERS_READ`
RetrieveCustomerSegment	`CUSTOMERS_READ`

Devices

Use the Devices API to configure a Square Terminal.

API	Permissions
CreateDeviceCode	`DEVICE_CREDENTIAL_MANAGEMENT`
GetDeviceCode	`DEVICE_CREDENTIAL_MANAGEMENT`
ListDeviceCodes	`DEVICE_CREDENTIAL_MANAGEMENT`

Disputes

Use the Disputes API to manage disputes (chargebacks).

API	Permissions
AcceptDispute	`PAYMENTS_WRITE`
CreateDisputeEvidenceFile	`PAYMENTS_WRITE`
CreateDisputeEvidenceText	`PAYMENTS_WRITE`
ListDisputeEvidence	`PAYMENTS_READ`
ListDisputes	`PAYMENTS_READ`
RemoveDisputeEvidence	`PAYMENTS_WRITE`
RetrieveDispute	`PAYMENTS_READ`
RetrieveDisputeEvidence	`PAYMENTS_READ`
SubmitEvidence	`PAYMENTS_WRITE`

Employees

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

API	Permissions
ListEmployees	`EMPLOYEES_READ`
RetrieveEmployee	`EMPLOYEES_READ`

Inventory

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

API	Permissions
BatchChangeInventory	`INVENTORY_WRITE`
BatchRetrieveInventoryCounts	`INVENTORY_READ`
BatchRetrieveInventoryChanges	`INVENTORY_READ`
RetrieveInventoryAdjustment	`INVENTORY_READ`
RetrieveInventoryChanges	`INVENTORY_READ`
RetrieveInventoryCount	`INVENTORY_READ`
RetrieveInventoryPhysicalCount	`INVENTORY_READ`

Labor

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

API	Permissions
CreateBreakType	`TIMECARDS_SETTINGS_WRITE`
CreateShift	`TIMECARDS_WRITE`
DeleteBreakType	`TIMECARDS_SETTINGS_WRITE`
DeleteShift	`TIMECARDS_SETTINGS_WRITE`
GetBreakType	`TIMECARDS_SETTINGS_READ`
GetEmployeeWage	`EMPLOYEES_READ`
GetShift	`TIMECARDS_READ`
ListBreakTypes	`TIMECARDS_SETTINGS_READ`
ListEmployeeWages	`EMPLOYEES_READ`
ListWorkweekConfigs	`TIMECARDS_SETTINGS_READ`
SearchShifts	`TIMECARDS_READ`
UpdateShift	`TIMECARDS_WRITE` `TIMECARDS_READ`
UpdateWorkweekConfig	`TIMECARDS_SETTINGS_READ` `TIMECARDS_SETTINGS_WRITE`
UpdateBreakType	`TIMECARDS_SETTINGS_READ` `TIMECARDS_SETTINGS_WRITE`

Locations

Get a list of a seller's locations.

API	Permissions
CreateLocation	`MERCHANT_PROFILE_WRITE`
ListLocations	`MERCHANT_PROFILE_READ`
RetrieveLocation	`MERCHANT_PROFILE_READ`
UpdateLocation	`MERCHANT_PROFILE_WRITE`

Loyalty

Provides endpoints to access the buyer loyalty program.

API	Permissions
AccumulateLoyaltyPoints	`LOYALTY_WRITE`
AdjustLoyaltyPoints	`LOYALTY_WRITE`
CalculateLoyaltyPoints	`LOYALTY_READ`
CreateLoyaltyAccount	`LOYALTY_WRITE`
CreateLoyaltyOrderAssignment	`LOYALTY_WRITE` `ORDERS_READ`
CreateLoyaltyReward	`LOYALTY_WRITE`
DeleteLoyaltyReward	`LOYALTY_WRITE`
ListLoyaltyPrograms	`LOYALTY_READ`
RedeemLoyaltyReward	`LOYALTY_WRITE`
RetrieveLoyaltyAccount	`LOYALTY_READ`
RetrieveLoyaltyProgramOrderAssignment	`LOYALTY_READ` `ORDERS_READ`
RetrieveLoyaltyReward	`LOYALTY_READ`
SearchLoyaltyAccounts	`LOYALTY_READ`
SearchLoyaltyEvents	`LOYALTY_READ`
SearchLoyaltyRewards	`LOYALTY_READ`

Merchants

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

API	Permissions
ListMerchants	`MERCHANT_PROFILE_READ`
RetrieveMerchant	`MERCHANT_PROFILE_READ`

Mobile Authorization

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

API	Permissions
CreateMobileAuthorizationCode	`PAYMENTS_WRITE_IN_PERSON`

Orders

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

API	Permissions
CalculateOrder	N/A
CreateOrder	`ORDERS_WRITE`
BatchRetrieveOrders	`ORDERS_READ`
PayOrder	`ORDERS_WRITE` `PAYMENTS_WRITE`
SearchOrders	`ORDERS_READ`
UpdateOrder	`ORDERS_WRITE`

Payments and Refunds

The Payments API lets developers take and manage payments.

API	Permissions
CancelPayment	`PAYMENTS_WRITE`
CancelPaymentByIdempotencyKey	`PAYMENTS_WRITE`
CompletePayment	`PAYMENTS_WRITE`
CreatePayment	`PAYMENTS_WRITE` `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS`
GetPayment	`PAYMENTS_READ`
GetPaymentRefund	`PAYMENTS_READ`
ListPayments	`PAYMENTS_READ`
ListPaymentRefunds	`PAYMENTS_READ`
RefundPayment	`PAYMENTS_WRITE` `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS`

Teams

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

API	Permissions
BulkCreateTeamMembers	`EMPLOYEES_WRITE`
BulkUpdateTeamMembers	`EMPLOYEES_WRITE`
CreateTeamMember	`EMPLOYEES_WRITE`
UpdateTeamMember	`EMPLOYEES_WRITE`
RetrieveTeamMember	`EMPLOYEES_READ`
RetrieveWageSetting	`EMPLOYEES_READ`
SearchTeamMembers	`EMPLOYEES_READ`
UpdateWageSetting	`EMPLOYEES_READ`

Terminal

The Terminal API lets developers request Square Terminal checkouts.

API	Permissions
CreateTerminalCheckout	`PAYMENTS_WRITE`
CancelTerminalCheckout	`PAYMENTS_WRITE`
GetTerminalCheckout	`PAYMENTS_READ`
SearchTerminalCheckouts	`PAYMENTS_READ`

Was this page helpful?

Still haven't found what you are looking for?

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow.

Permissions Reference

On this page

Still haven't found what you are looking for?