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.
On this page
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 |