All Tutorials

Fulfillment orders migration guide

All Tutorials

Fulfillment orders migration guide

Fulfillment orders migration guide

To migrate your app to managing fulfillments with the FulfillmentOrder resource, you need to request some additional permissions. The permissions that you need to request differ based on the type of app that you build.

For existing installations, you can request the additional permissions without the merchant needing to reinstall your app.

Update your app's permissions

  1. Determine which additional permissions you need to request. These differ depending on the type of app that you build:

  2. For new installations, include the additional scopes in the permissions that your app requests as part of the OAuth process.

  3. For existing installations, use the /admin/request_granular_access_scopes endpoint described below to request the additional scopes without merchants reinstalling your app.

After you've updated your app's permissions, you can manage fulfillments with the FulfillmentOrder resource.

Requesting additional scopes for existing installations

For existing installations of your app, you don't need to ask merchants to agree to new permissions if they have already granted read_fulfillments or write_fulfillments. Instead, you can use the following endpoint to request a subset of granular access scopes for an individual shop installation.

If you have read_fulfillments but not write_fulfillments, then you can request only the read_* scopes.

POST /admin/request_granular_access_scopes.json

Adds granular versions of an existing access scope to an existing installation. In the body of your request, you should include an array of the scopes from the list below:

  • read_assigned_fulfillment_orders
  • read_merchant_managed_fulfillment_orders
  • read_third_party_fulfillment_orders
  • write_assigned_fulfillment_orders
  • write_merchant_managed_fulfillment_orders
  • write_third_party_fulfillment_orders

Add a single granular access scope to an existing installation

POST /admin/request_granular_access_scopes.json
{
  "requested_scopes": [
    "write_assigned_fulfillment_orders"
  ]
}
View Response
HTTP/1.1 200 OK
{
  "access_scopes": [
    {
      "handle": "write_fulfillments"
    },
    {
      "handle": "write_assigned_fulfillment_orders"
    }
  ]
}