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.

Bank Accounts

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

API	Permission
GetBankAccount	`BANK_ACCOUNTS_READ`
ListBankAccounts	`BANK_ACCOUNTS_READ`
GetBankAccountByV1Id	`BANK_ACCOUNTS_READ`

Catalog

Sync items to Square Point of Sale to itemize payments consistently across all channels.

API	Permission
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`

Cash Drawer Shifts

Get details about cash drawer shifts.

API	Permission
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	Permission
CreateCheckout	`ORDERS_WRITE` `PAYMENTS_WRITE` `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS`

Customers

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

API	Permission
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`

Customer Groups

Manage customers by groups.

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

Customer Segments

Manage customers by segments.

API	Permission
ListCustomerSegments	`CUSTOMERS_READ`
RetrieveCustomerSegment	`CUSTOMERS_READ`

Devices

Use the Devices API to configure a Square Terminal.

API	Permission
CreateDeviceCode	`DEVICE_CREDENTIAL_MANAGEMENT`
GetDeviceCode	`DEVICE_CREDENTIAL_MANAGEMENT`
ListDeviceCodes	`DEVICE_CREDENTIAL_MANAGEMENT`

Disputes

Use the Disputes API to manage disputes (chargebacks).

API	Permission
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	Permission
ListEmployees	`EMPLOYEES_READ`
RetrieveEmployee	`EMPLOYEES_READ`

Inventory

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

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

Invoices

Use the Invoices API to manage invoices.

API	Permissions
ListInvoices	`INVOICES_READ`
CreateInvoice	`INVOICES_WRITE` `ORDERS_WRITE`
SearchInvoices	`INVOICES_READ`
DeleteInvoice	`INVOICES_WRITE` `ORDERS_WRITE`
GetInvoice	`INVOICES_READ`
UpdateInvoice	`INVOICES_WRITE` `ORDERS_WRITE`
CancelInvoice	`INVOICES_WRITE` `ORDERS_WRITE`
PublishInvoice	`INVOICES_WRITE` `ORDERS_WRITE`

Labor

Manage shifts, breaks, and wages for employees in Square Point of Sale.

API	Permission
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	Permission
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	Permission
AccumulateLoyaltyPoints	`LOYALTY_WRITE`
AdjustLoyaltyPoints	`LOYALTY_WRITE`
CalculateLoyaltyPoints	`LOYALTY_READ`
CreateLoyaltyAccount	`LOYALTY_WRITE`
CreateLoyaltyReward	`LOYALTY_WRITE`
DeleteLoyaltyReward	`LOYALTY_WRITE`
ListLoyaltyPrograms	`LOYALTY_READ`
RedeemLoyaltyReward	`LOYALTY_WRITE`
RetrieveLoyaltyAccount	`LOYALTY_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	Permission
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	Permission
CreateMobileAuthorizationCode	`PAYMENTS_WRITE_IN_PERSON`

Orders

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

API	Permission
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	Permission
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`

Subscriptions

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

API	Permissions
CreateSubscription	`CUSTOMERS_READ` `PAYMENTS_WRITE` `SUBSCRIPTIONS_WRITE` `ITEMS_READ` `ORDERS_WRITE` `INVOICES_WRITE`
SearchSubscriptions	`SUBSCRIPTIONS_READ`
RetrieveSubscription	`SUBSCRIPTIONS_READ`
UpdateSubscription	`CUSTOMERS_READ` `PAYMENTS_WRITE` `SUBSCRIPTIONS_WRITE` `ITEMS_READ` `ORDERS_WRITE` `INVOICES_WRITE`
CancelSubscription	`SUBSCRIPTIONS_WRITE`
ListSubscriptionEvents	`SUBSCRIPTIONS_READ`

Team

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

API	Permission
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 and process Interac refunds.

API	Permission
CreateTerminalCheckout	`PAYMENTS_WRITE`
CancelTerminalCheckout	`PAYMENTS_WRITE`
GetTerminalCheckout	`PAYMENTS_READ`
SearchTerminalCheckouts	`PAYMENTS_READ`
CreateTerminalRefund	`PAYMENTS_WRITE`
CancelTerminalRefund	`PAYMENTS_WRITE`
GetTerminalRefund	`PAYMENTS_READ`
SearchTerminalRefunds	`PAYMENTS_READ`

Was this page helpful?

Still haven't found what you are looking for?

Contact Developer Support, or ask for help in the Developer Forums.

Permissions Reference

On this page

Still haven't found what you are looking for?