POST /fulfillments.json returns permission error – what am I missing?

[Varshika]

Hi Team,

I’ve built a custom app and connected a store (riwaajbyshruti.myshopify.com).
Through OAuth, I’m getting the Admin API token with these scopes:

read_orders, write_orders, read_fulfillments, write_fulfillments

• I can successfully fetch orders and fulfillment orders.

• But when I try:

POST https://riwaajbyshruti.myshopify.com/admin/api/2025-07/fulfillments.json

with this payload:

{
  "fulfillment": {
    "line_items_by_fulfillment_order": [
      { "fulfillment_order_id": 123456789 }
    ],
    "tracking_info": {
      "number": "TRACK123",
      "url": "https://tracking-url.com"
    }
  }
}

I get the error:

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

My understanding is that since my app has write_fulfillments, it should be able to create fulfillments.

What to do if my app just needs to add tracking numbers and mark orders fulfilled.

Thanks and regards,

Varshika Dadhich

[PieLab]

Hi @Varshika

This is a common permission error that occurs when using an older, deprecated fulfillment endpoint. The solution is to use the modern Fulfillment Order workflow, which will work with your existing write_fulfillments scope. Instead of a single call, it is a two-part process.

First, you must fetch the specific fulfillment_order_id for the items you wish to ship by making a GET request to /admin/api/2025-07/orders/{order_id}/fulfillment_orders.json.

Once you have the fulfillment_order_id from that request, you can create the fulfillment.

You will make a POST request to the new, correct endpoint: /admin/api/2025-07/fulfillment_orders/{fulfillment_order_id}/fulfillments.json. The JSON payload for this request should be structured as follows:

{
  "fulfillment": {
    "line_items_by_fulfillment_order": [
      {
        "fulfillment_order_id": "YOUR_FULFILLMENT_ORDER_ID_FROM_STEP_1"
      }
    ],
    "tracking_info": {
      "number": "YOUR_TRACKING_NUMBER"
    }
  }
}

By switching to this process of first fetching the fulfillment_order_id and then posting to the new endpoint, you will align with Shopify’s modern API practices, and the permission error will be resolved.

Hope this helps!

[Varshika]

Hi,

I was able to retrieve the order_id using the following URL:

https://riwaajbyshruti.myshopify.com/admin/api/2024-10/orders.json?name=%232567-RIW

I then used that order_id in the following curl request:

curl --location "https://riwaajbyshruti.myshopify.com/admin/api/2025-10/orders/6202064076847/fulfillment_orders.json" \
--header "X-Shopify-Access-Token: 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" \
--header "Content-Type: application/json"

However, I received the following response:

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

The access token I’m using was generated with the following scopes:

write_fulfillments
read_fulfillments

Could you please help me understand why this permission error is occurring and what additional scope or configuration might be required?

Thanks,
Varshika