Roles and permissions

Your API key works with your role on the team in the request’s path. Most operations follow that role. Some don’t. A number of operations let any member of the team call them, whatever their role. They’re listed below, and each operation’s reference page states its permission.

How roles work

• The team owner can do everything on the team.
• Every other member has one role on each team. The web app calls roles Permission Groups, under team settings.
• A role is a set of permissions, such as creating orders, viewing all orders or only your own, seeing order finances, managing stock or managing settings.
• Manage Settings is the team permission (manage_setting) that grants administrative control over the shop’s setup. Members with this permission can edit team settings, configure integrations (QuickBooks, Shopify, payment gateways), set up webhooks, and read stored secrets (such as payment gateway API secrets and webhook signing secrets). On a plan with advanced permission management, they can also change permission groups. The team owner always has this permission.

New teams start with these roles: Super Admin, Shop Manager, Sales Team, Shop Floor Team and Accounting Team. Creating, changing or deleting a role needs a plan with advanced permission management. Moving a member to another role doesn’t.

To see the roles on a team and what each allows, list them:

GET List permission groups /v1/api/store/{team_slug}/setting/group

To see team members and their roles:

GET List team members /v1/api/store/{team_slug}/setting/user

Roles that see less

Some permissions come in two sizes:

Permission	Wider	Narrower
Orders	View or update all orders	View or update only your own orders
Customers	View or update all customers	View or update only customers assigned to you

A role with the narrower permission gets fewer records from lists, filters and searches. What “your own” means isn’t the same everywhere: the sales order and quote filters return only orders you created, while order search also includes orders you’re assigned to. Each reference page states its own rule.

For example, suppose another team member created Order #100 and assigned it to you, while you created Order #101 yourself. If your role can view only its own orders:

• List sales orders (the v2 sales order filter): returns only Order #101 (orders you created). It does not return Order #100.
• Search orders (GET /v2/api/store/your-team/search/orders?q=…): returns both Order #100 and Order #101 (orders you created plus orders assigned to you).
• Orders you neither created nor are assigned to are hidden from both.

Roles also differ in whether they can see order and customer finances.

Operations any member can call

These operations don’t check the caller’s role, or check less than the web app suggests. Any member’s key can call them. Don’t rely on a role to stop a key from doing any of this.

Area	What any member’s key can do
Customers	Create or update a customer by contact (upsert), even one not assigned to them. Upsert contacts. Change contacts, tags and external ids. Changing the email of a contact that gives someone Customer Portal access does check Manage Customers, on every customer the change covers.
Payments	Record, change, delete and refund payments. Charge a card through a payment gateway and refund it. Use Square Terminal. Create payment links (allocations). Moving money to and from customer credit does check the role: it needs View Sales Order Pricing and permission to edit the order.
Invoices	Create and delete invoices, and change their tax selection.
Shipping	Create shipments and change their status. Get rates. Record labels. Change packages.
Production	Change a job’s status and production dates. Create, change, assign and delete tasks. Read the job and task boards and calendars, whatever orders the role can see.
Approvals, comments and messages	Create and send approvals, which email the customer. Edit or delete any comment across the team (including comments written by other team members). Send a message template for any record.
Data exports	Export every type, including sales orders, invoices, payments and tax, whatever the role.

Caution

Give API keys only to people you’d trust with every operation above, and remove members who no longer need access. These are the documented cases. Each operation’s reference page has the exact rule.

Shipping labels and packages

These shipping actions check the order the shipment belongs to:

Action	Needs
Buy a GoShippo label	Permission to view that order: all orders, or your own and assigned ones.
Void or remove packages, one at a time or in bulk	Permission to view that order.
Delete a shipment	Permission to edit that order.

So a role that can view orders but not edit them, such as the default Shop Floor Team and Accounting Team roles, can still buy and void labels. Buying a label spends money. See Ship an order.

Integration actions

Running an integration’s actions needs Manage Settings. Two operations let members without it do a few things:

PUT Search QuickBooks, or sync records to it /v1/api/store/{team_slug}/setting/external_integration/{id}/public_action PUT Read Shopify orders through the integration /v1/api/store/{team_slug}/setting/external_integration/{id}/proxy_request

Action	Needs, without Manage Settings
QuickBooks sync of sales orders	Permission to view every order being synced.
QuickBooks sync of purchase orders	Permission to view every purchase order being synced.
QuickBooks customer lookup	Permission to view all customers.
QuickBooks vendor lookup	Permission to view vendors.
Shopify store order list	Permission to view all orders.

Anything else through these two, such as the QuickBooks invoice, bill and purchase order lookups, needs Manage Settings.

Stored secrets

Members without Manage Settings can read team and integration settings, but don’t get stored secrets: payment-gateway secret keys and webhook signing secrets come back only to the team owner and people who can manage settings. Stored provider tokens, such as Twilio’s or GoShippo’s, never come back in integration settings, whoever asks.

When your role doesn’t allow it

YoPrint answers 403 and changes nothing.

{
  "status": 403,
  "success": false,
  "error": {
    "code": "user_is_not_authorized",
    "message": "Your role does not allow this order action. Ask your team owner to review your sales order permissions."
  }
}

Other refusals can have a different code, or only a message, such as settings changes your role doesn’t allow, which answer 403 with { "message": "Insufficient Permission" }. Rely on the 403 status. See Errors.

To fix it, ask the team owner to change your role in the web app, or have a member whose role allows the operation run it with their own key.

Plan an integration around roles

• Use a key whose role matches what the integration does. An integration that only reads orders doesn’t need settings permissions.
• Don’t treat a narrow role as a safety net. Check the operations above, and limit who holds keys.
• If an integration’s reads look incomplete, check the role before you look for a bug.
• Changing a member’s role changes what their key can do at once. You don’t need a new key.