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 |
Bookings
The Bookings API creates and maintains service appointments.
API | Permission |
---|---|
CreateBooking | • APPOINTMENTS_WRITE (buyer-level). • APPOINTMENTS_WRITE , APPOINTMENTS_ALL_WRITE (seller-level). |
SearchAvailability | • APPOINTMENTS_READ (buyer-level). • APPOINTMENTS_READ , APPOINTMENTS_ALL_READ (seller-level). |
RetrieveBusinessBookingProfile | APPOINTMENTS_BUSINESS_SETTINGS_READ |
ListTeamMemberBookingProfiles | APPOINTMENTS_BUSINESS_SETTINGS_READ |
RetrieveTeamMemberBookingProfile | APPOINTMENTS_BUSINESS_SETTINGS_READ |
ListBookings | • APPOINTMENTS_READ (buyer-level). • APPOINTMENTS_READ , APPOINTMENTS_ALL_READ (seller-level). |
RetrieveBooking | • APPOINTMENTS_READ (buyer-level). • APPOINTMENTS_READ , APPOINTMENTS_ALL_READ (seller-level). |
UpdateBooking | • APPOINTMENTS_WRITE (buyer-level). • APPOINTMENTS_WRITE , APPOINTMENTS_ALL_WRITE (seller-level). |
CancelBooking | • APPOINTMENTS_WRITE (buyer-level). • APPOINTMENTS_WRITE , APPOINTMENTS_ALL_WRITE (seller-level). |
Cards
The Cards API provides endpoints to access a payment card stored on file.
API | Permissions |
---|---|
ListCards | PAYMENTS_READ |
CreateCard | PAYMENTS_WRITE |
RetrieveCard | PAYMENTS_READ |
DisableCard | PAYMENTS_WRITE |
Cash Drawer Shifts
The Cash Drawer Shifts API provides details about cash drawer shifts.
API | Permission |
---|---|
ListCashDrawerShifts | CASH_DRAWER_READ |
ListCashDrawerShiftEvents | CASH_DRAWER_READ |
RetrieveCashDrawerShift | CASH_DRAWER_READ |
Catalog
The Catalog API syncs items to Square Point of Sale in order 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 |
SearchCatalogItems | ITEMS_READ |
SearchCatalogObjects | ITEMS_READ |
UpdateItemTaxes | ITEMS_WRITE |
UpdateItemModifierLists | ITEMS_WRITE |
UpsertCatalogObject | ITEMS_WRITE |
Checkout
The Checkout API accepts itemized payments on a Square-hosted web page. No frontend experience required.
API | Permission |
---|---|
CreateCheckout | ORDERS_WRITE PAYMENTS_WRITE PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS |
Customers
The Customers API creates and manages customer profiles and syncs customer relationship management (CRM) systems with Square.
API | Permission |
---|---|
AddGroupToCustomer | CUSTOMERS_WRITE |
CreateCustomer | CUSTOMERS_WRITE |
CreateCustomerCard (deprecated) | CUSTOMERS_WRITE |
DeleteCustomer | CUSTOMERS_WRITE |
DeleteCustomerCard (deprecated) | CUSTOMERS_WRITE |
ListCustomers | CUSTOMERS_READ |
RemoveGroupFromCustomer | CUSTOMERS_WRITE |
RetrieveCustomer | CUSTOMERS_READ |
SearchCustomers | CUSTOMERS_READ |
UpdateCustomer | CUSTOMERS_WRITE |
Customer Custom Attributes
The Customer Custom Attributes API lets you create and manage custom attributes for customer profiles.
API | Permission |
---|---|
CreateCustomerCustomAttributeDefinition | CUSTOMERS_WRITE |
UpdateCustomerCustomAttributeDefinition | CUSTOMERS_WRITE |
ListCustomerCustomAttributeDefinitions | CUSTOMERS_READ |
RetrieveCustomerCustomAttributeDefinition | CUSTOMERS_READ |
DeleteCustomerCustomAttributeDefinition | CUSTOMERS_WRITE |
UpsertCustomerCustomAttribute | CUSTOMERS_WRITE |
BulkUpsertCustomerCustomAttributes | CUSTOMERS_WRITE |
ListCustomerCustomAttributes | CUSTOMERS_READ |
RetrieveCustomerCustomAttribute | CUSTOMERS_READ |
DeleteCustomerCustomAttribute | CUSTOMERS_WRITE |
Customer Groups
The Customer Groups API manages customers by groups.
API | Permission |
---|---|
CreateCustomerGroup | CUSTOMERS_WRITE |
DeleteCustomerGroup | CUSTOMERS_WRITE |
ListCustomerGroups | CUSTOMERS_READ |
RetrieveCustomerGroup | CUSTOMERS_READ |
UpdateCustomerGroup | CUSTOMERS_WRITE |
Customer Segments
The Customer Segments API manages 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 | DISPUTES_WRITE |
CreateDisputeEvidenceFile | DISPUTES_WRITE |
CreateDisputeEvidenceText | DISPUTES_WRITE |
ListDisputeEvidence | DISPUTES_READ |
ListDisputes | DISPUTES_READ |
DeleteDisputeEvidence | DISPUTES_WRITE |
RetrieveDispute | DISPUTES_READ |
RetrieveDisputeEvidence | DISPUTES_READ |
SubmitEvidence | DISPUTES_WRITE |
Employees
The Employees API provides a query endpoint to get a list of the employees for a seller.
API | Permission |
---|---|
ListEmployees | EMPLOYEES_READ |
RetrieveEmployee | EMPLOYEES_READ |
Gift Cards
The Gift Cards API provides endpoints to create and manage gift cards.
API | Permission |
---|---|
ListGiftCards | GIFTCARDS_READ |
CreateGiftCard | GIFTCARDS_WRITE |
RetrieveGiftCardFromGAN | GIFTCARDS_READ |
RetrieveGiftCardFromNonce | GIFTCARDS_READ |
LinkCustomerToGiftCard | GIFTCARDS_WRITE |
UnlinkCustomerFromGiftCard | GIFTCARDS_WRITE |
RetrieveGiftCard | GIFTCARDS_READ |
Gift Card Activities
The Gift Card Activities API provides endpoints to create gift card activities, such as activate a gift card, add funds to a gift card, and redeem a gift card.
API | Permission |
---|---|
ListGiftCardActivities | GIFTCARDS_READ |
CreateGiftCardActivity | GIFTCARDS_WRITE |
Inventory
The Inventory API keeps 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 | ORDERS_WRITE INVOICES_WRITE |
SearchInvoices | INVOICES_READ |
DeleteInvoice | ORDERS_WRITE INVOICES_WRITE |
GetInvoice | INVOICES_READ |
UpdateInvoice | ORDERS_WRITE INVOICES_WRITE |
CancelInvoice | ORDERS_WRITE INVOICES_WRITE |
PublishInvoice | ORDERS_WRITE INVOICES_WRITE |
Labor
The Labor API manages 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_WRITE |
GetBreakType | TIMECARDS_SETTINGS_READ |
GetTeamMemberWage | EMPLOYEES_READ |
GetShift | TIMECARDS_READ |
ListBreakTypes | TIMECARDS_SETTINGS_READ |
ListTeamMemberWages | 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
The Locations API gets 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
The Loyalty API provides endpoints to access the buyer loyalty program, creates and manages loyalty accounts, and creates and manages loyalty rewards.
API | Permission |
---|---|
AccumulateLoyaltyPoints | LOYALTY_WRITE |
AdjustLoyaltyPoints | LOYALTY_WRITE |
CalculateLoyaltyPoints | LOYALTY_READ |
CreateLoyaltyAccount | LOYALTY_WRITE |
CreateLoyaltyReward | LOYALTY_WRITE |
DeleteLoyaltyReward | LOYALTY_WRITE |
RetrieveLoyaltyProgram | LOYALTY_READ |
ListLoyaltyPrograms (deprecated) | 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
The Mobile Authorization API provides an endpoint for getting a mobile authorization code for use in Reader SDK applications.
API | Permission |
---|---|
CreateMobileAuthorizationCode | PAYMENTS_WRITE_IN_PERSON |
Orders
The Orders API gets sales data for a Square seller, itemize payments, push orders to Point of Sale, and more.
API | Permission |
---|---|
CalculateOrder | N/A |
CloneOrder | ORDERS_WRITE |
CreateOrder | ORDERS_WRITE |
BatchRetrieveOrders | ORDERS_READ |
PayOrder | ORDERS_WRITE PAYMENTS_WRITE |
RetrieveOrder | ORDERS_WRITE ORDERS_READ |
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 |
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).
API | Permission |
---|---|
ListPayouts | PAYOUTS_READ |
GetPayout | PAYOUTS_READ |
ListPayoutEntries | PAYOUTS_READ |
Snippets
Use the Snippets API to manage snippets on Square Online sites.
API | Permissions |
---|---|
UpsertSnippet | ONLINE_STORE_SNIPPETS_WRITE |
RetrieveSnippet | ONLINE_STORE_SNIPPETS_READ |
DeleteSnippet | ONLINE_STORE_SNIPPETS_WRITE |
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 |
ResumeSubscription | CUSTOMERS_READ PAYMENTS_WRITE SUBSCRIPTIONS_WRITE ITEMS_READ ORDERS_WRITE INVOICES_WRITE |
PauseSubscription | CUSTOMERS_READ PAYMENTS_WRITE SUBSCRIPTIONS_WRITE ITEMS_READ ORDERS_WRITE INVOICES_WRITE |
SwapPlan | CUSTOMERS_READ PAYMENTS_WRITE SUBSCRIPTIONS_WRITE ITEMS_READ ORDERS_WRITE INVOICES_WRITE |
DeleteSubscriptionAction | SUBSCRIPTIONS_WRITE |
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_WRITE |
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 |
CreateTerminalAction | PAYMENTS_WRITE |
CancelTerminalAction | PAYMENTS_WRITE |
GetTerminalAction | PAYMENTS_READ CUSTOMERS_READ |
SearchTerminalAction | PAYMENTS_READ |
Vendors
The Vendors API supports managing a seller's suppliers in an application.
API | Permission |
---|---|
BulkCreateVendors | VENDOR_WRITE |
BulkRetrieveVendors | VENDOR_READ |
BulkUpdateVendors | VENDOR_WRITE |
CreateVendor | VENDOR_WRITE |
SearchVendors | VENDOR_READ |
RetrieveVendor | VENDOR_READ |
UpdateVendors | VENDOR_WRITE |
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.