Fulfillment orders returning {"errors":"The api_client does not have the required permission(s)."}

Retired Boards Appdev Fulfillment Api

Topic summary

Main issue: Calls to the Fulfillment Orders API return {“errors”:“The api_client does not have the required permission(s).”} or an empty list.

Key findings:

  • Browser-originated requests inherit staff account permissions and fail. Using a dedicated API client or basic auth with app key:secret resolves this.
  • Scopes matter by fulfillment origin:
    • Merchant-managed locations require read_merchant_managed_fulfillment_orders (and write_merchant_managed_fulfillment_orders for writes).
    • Fulfillment service–managed orders require read_assigned_fulfillment_orders or read_third_party_fulfillment_orders.
  • Having only read_assigned_fulfillment_orders can yield empty responses when orders are merchant-managed.

Outcome:

  • After switching to an API client and adding read_merchant_managed_fulfillment_orders, one developer confirmed success.
  • Shopify staff clarified the difference between merchant-managed vs fulfillment service–managed fulfillment orders and shared relevant docs.

Open items and guidance:

  • Some users still report errors and asked how to add the merchant-managed scopes.
  • One user reported success after adding broader scopes (e.g., read_all_orders, read_locations, write_merchant_managed_fulfillment_orders).
  • For unresolved cases, provide the x-request-id from response headers so Shopify can investigate. The thread remains partially open.
Summarized with AI on December 27. AI used: gpt-5.
30

I had all the suggested permissions and was still getting the error. I ended up scraping the permissions page and added a bunch until it worked. One of these did the trick:

read_all_orders
read_inventory
write_inventory
read_locations
write_merchant_managed_fulfillment_orders