Error when read_marketplace_orders or read_marketplace_fulfillment_orders scope is added

Dev Platform
,
1

I added read_marketplace_orders and read_marketplace_fulfillment_orders scope to shopify.app.toml file, and it’s failing to start dev preview:

image
image863×236 5.3 KB

Also, when I try to deploy new app version, it fails as well:

image
image651×180 2.53 KB

The issue still happens when there is either one of the scopes, not both. When both scopes are removed, it works fine.

I’m using API version 2026-01.

2

Hi @xhdtlsid2! Those scopes are causing the failure because read_marketplace_orders is a restricted scope that isn’t available to standard third-party apps. It’s reserved for approved marketplace channel apps and you won’t find it listed on the access scopes documentation.

read_marketplace_fulfillment_orders is documented as part of the fulfillment order scope family, but it also has a very specific purpose tied to marketplace channel contexts.

For most order and fulfillment use cases, the standard scopes are what you want. read_orders and write_orders for order access, and then read_merchant_managed_fulfillment_orders, read_assigned_fulfillment_orders, or read_third_party_fulfillment_orders depending on your fulfillment workflow. Those are all covered in the fulfillment order migration guide.

Can you share a bit more about what you’re building? Knowing your use case will help me point you to the right scopes.

3

Hi @Donal-Shopify, thanks for the reply.

I’m building an app, and here is what I’m trying to do:

When an order is created and it contains a specific product, I need to edit the order to replace it with certain associated products.

However, if the order is created from an external sales channel, such as Facebook, it cannot be edited. In that case, I am trying to create a new order that includes those certain products, and assign the same location.

Would it be possible to implement this without the two scopes?

Thanks,

4

Yes, you should be able to do all of this without those marketplace scopes.

For the editing side, the scope you need is write_order_edits. One thing to be aware of is that the order editing API supports orders created by Shopify channels (Online Store, POS, draft orders) and orders your own app created, but external channel orders like Facebook may not be editable. You can check this per-order by querying merchantEditable on the Order object. If it returns false, merchantEditableErrors will tell you why.

For the fallback where an order can’t be edited, orderCreate is probably your best option since it accepts a fulfillment input with a locationId field, so you can assign the same location as the original order directly at creation time. That requires write_orders scope.

To decide which path to take for a given order, you can either use merchantEditable as the branch condition, or check the channelInformation field on the order to identify the originating sales channel.

So in terms of scopes, you’d need read_orders, write_order_edits, and write_orders. Hope this helps!

5

Just to make sure I’m understanding it correctly:

  • I can query external channel orders’ merchantEditable field, without read_marketplace_orders scope
  • I can query fulfillment orders of an external channel order without read_marketplace_fulfillment_orders scope

Sorry for making this thread long, thank you for looking into this.

6

Yes to both.

merchantEditable is a standard field on the Order object and only requires read_orders to access. The read_orders scope gives your app access to all orders on the store regardless of which sales channel created them, so you’ll be able to query merchantEditable (and merchantEditableErrors) on any order without needing marketplace-specific scopes.

For fulfillment orders, the three main scopes are documented as location-based rather than order-origin-based. read_merchant_managed_fulfillment_orders grants access to fulfillment orders assigned to merchant-managed locations, read_third_party_fulfillment_orders covers those at third-party fulfillment service locations, and so on. If your external channel orders are being fulfilled from a merchant-managed location, read_merchant_managed_fulfillment_orders should cover them. I’d recommend confirming this works in practice once you have your scopes set up, since the docs don’t explicitly address the cross-channel scenario for fulfillment orders, but the scope model is location-based so this is the expected behavior.

Let me know if you hit anything unexpected when you start testing.

1 Like