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.
24

Hi @Kevin_A ,

That was it! Can’t thank you enough!

But to be honest, I don’t really understand this concept of “merchant-managed locations” vs other kinds of locations (fulfillment service managed?), even though I have read through lots of documentation pages about locations. Is there anything you can suggest which clarifies this for me?

Thank you,

Gabe