New Workflow for fulfilmentOrders with Tracking Information

[David_Luck]

With the order -> fulfilment workflow being deprecated I'm finding difficult to understand what the new fulfillmentOrder workflow is to add tracking information (number and link) to an order?

I'd be really grateful for some help and advice from anyone who has already done this please.

Thank you!

[garyrgilbert]

Hi David,

Yeah they made it a bit more complicated, but way more useful in my opinion.

So the workflow kind of goes like this:

1. get the fulfillmentorder(s) for the order id - there can be more than 1 depending on whether the shop has multiple locations.

2. the fulfillment order (if using the rest api) will also include all the line items that belong to that fulfillmentOrder along with quantity to be fulfilled.

3. build your post body.

{
    "fulfillment": {
        "notify_customer": true,
        "tracking_info": {
            "number": [tracking number],
            "url": "[tracking link]",
            "company": "[tracking company]"
        },
        "line_items_by_fulfillment_order": [
            {
                "fulfillment_order_id": [obtained in step 1],
                "fulfillment_order_line_items": [
                    {
                        "id": [obtained in step 1 under fulfillment_Order.line_items],
                        "quantity": 1
                    }
                ]
            }
        ]
    }
}

Hope this helps,

Cheers

Gary

[David_Luck]

Hi @garyrgilbert thanks for the explanation, however after making some new test orders when I (GET) request the fulfillmentOrders from the filfillmentOrderService I'm not actually getting any results and the API suggests these should be created automatically so I'm a bit stumped 😞

[garyrgilbert]

Hi @David_Luck 

Not fulfillmentOrderService Just fulfillmentOrder as in:

https://[shopname].myshopify.com/admin/api/2023-01/orders/[order.id]/fulfillment_orders.json

Doc:

https://shopify.dev/api/admin-rest/2023-01/resources/fulfillmentorder#get-orders-order-id-fulfillmen...

Doing a get request to the endpoint /orders/fulfillment_orders/{fulfillment_order_id}.json is something altogether different.  Fulfillment_order_id != order.id 

Cheers,

Gary

[David_Luck]

Thanks again @garyrgilbert for taking time to reply.

The issue I'm experiencing is if (for example) I request:
 admin/api/2023-01/orders/4564975779888/fulfillment_orders.json

I get a valid response but no fulfillment orders:

{

    "fulfillment_orders": []

}

The API documentation suggests there will always bee fulfillment orders automatically created when an order is made?

[garyrgilbert]

@David_Luck 

Ok, thats not right, even if the order is fulfilled you should still see the completed fulfillment order.

The only reason you should be receiving that response is if the order ID does not exist.  Instead of the normal response one would expect.

{"errors":"Not Found"}

we get the following which is totally misleading. I think someone @Shopify should correct this oversight.

{"fulfillment_orders":[]}

So check to make sure that admin/api/2023-01/orders/4564975779888.json exists as an order first before requesting the fulfillment_order

Cheers,

Gary

[David_Luck]

@garyrgilbert it gets better...

[garyrgilbert]

Yeah.. I think we deserve a proper response.. someone appears to have dropped the ball again

[David_Luck]

@garyrgilbert yep, I'm starting to get the same feeling 🙈

[David_Luck]

@garyrgilbert I don't suppose you know how we escalate these issues?

Thanks again for your help and input.

[PierreM]

Hi guys,

did you find out how we can create easily a Fulfillment (with tracking info) on an existing Order like we used to do it before it was deprecated ?

I found we could do it by creating a Fulfillment on the FulfillmentOrder.

I got to the same point as you: I thought the FulfillmentOrder will be automatically created when an Order is created but it is not the case.  Do you think it's a bug.

Then I found the dev doc "Migrate to fulfillment orders: https://shopify.dev/docs/apps/fulfillment/migrate

Where it is clearly specified that we have to use fulfillment orders to manage fulfillments and, to my understanding, it means we have to create a fullfilment service to declare we decide to opt in to the fulfillment order process. 

I hope I'm wrong because it becomes too complex for the need we have which is to fulfill an order and all its items with tracking info and customer notification.

If I'm not wrong, I need some help to creta the fulfillment service because I didn't succed so far.

Thank you.

[prg74]

I do not believe the Fulfillment Service is necessary but the correct scopes are in order to see the fulfillment orders.

Double check the scopes you have assigned.

Assigned fulfillment orders

Merchant-manged fulfillment orders

third-party fulfillment orders

https://community.shopify.com/c/shopify-apis-and-sdks/fulfillment-orders-returns-empty-array-no-matt...

https://community.shopify.com/c/shopify-apis-and-sdks/required-scope-s-for-updating-fulfillment-trac...

[PierreM]

Thank you @prg74  !

I was missing Merchant-manged fulfillment orders and now I'm getting the Fulfillment orders related to my order.

You should solve this ticket with your answer.

Thank you so much. 

[prg74]

Glad to help. Seems the response is a bug as it should warn of scope assignment issue but does not do so.

[prg74 · Accepted solution]

Doesn't this have something to do with the assigned scopes?

Its either Assigned fulfillment orders or Merchant-manged fulfillment orders or third-party fulfillment orders.

[David_Luck]

Thanks! The Merchant management fulfillment permission was the answer... The documentation is vague but searching for that permission on google I came across this article and I wish I had seen it sooner.

Your guide to the Fulfillment Orders API migration (2023) - Shopify UK

[prg74]

Glad that worked out and hope it helps everyone else making this change.

I reckon it has to do with not setting up as a fulfillment service. That would make the fulfillment orders generated merchant managed.

[jpirola]

What exactly is the endpoint for this post?  I tried "--store--/admin/api/2023-01/orders/fulfillment_orders/{internal_order_id}"  and got a blank response and the order wasn't fulfilled.

[prg74]

It should be /admin/api/2023-01/orders/{internal_order_id}fulfillment_orders/

I think you should get a 404 with /admin/api/2023-01/orders/fulfillment_orders/{internal_order_id} or perhaps its blank due to needing the correct scope.

[jpirola]

Unfortunately, that made no difference 😞

I believe I have the proper scopes:
write_inventory
read_locations
write_orders
read_inventory
read_orders
write_assigned_fulfillment_orders
read_assigned_fulfillment_orders
write_fulfillments
read_fulfillments
write_merchant_managed_fulfillment_orders
read_merchant_managed_fulfillment_orders

But I was a little confused at the idea of a fulfillment service. the
format of my post to
/admin/api/2023-01/orders/{internal_order_id}fulfillment_orders/
looks correct...Is there another step somewhere? (I am correctly using the
fulfillment order IDs and item IDs in the POST)

The old "orders/{internal_order_id}/fulfillments.json" endpoint was SOO
much easier!

Thank you for any direction you have!

[garyrgilbert]

the correct url is:

/admin/api/2023-01/orders/{internal_order_id}fulfillment_orders.json

Cheers,

Gary

[jpirola]

Thanks. My URL is good and I'm still getting NOTHING returned from my POST.

I've got every possible permission:
write_inventory
read_locations
write_orders
read_inventory
read_orders
write_assigned_fulfillment_orders
read_assigned_fulfillment_orders
write_fulfillments
read_fulfillments
write_merchant_managed_fulfillment_orders
read_merchant_managed_fulfillment_orders
write_third_party_fulfillment_orders
read_third_party_fulfillment_orders
write_custom_fulfillment_services ? Do I even need this?
read_custom_fulfillment_services ?

Here's something curious though. When I paste the POST URL into my
browser I get:
{"errors":"The api_client does not have the required permission(s)."}
Is that just because it's the browser or is something still lacking?

THANK YOU!

[prg74]

Are you using /admin/api/2023-01/order/{internal_order_id}fulfillment_orders.json

When I replied I copied and mistakenly just moved the order_id parameter .

/admin/api/2023-01/orders/{internal_order_id}fulfillment_orders/ = bad url

/admin/api/2023-01/orders/{internal_order_id}fulfillment_orders.json = good url

And using that url in the browser will not work. You can use Postman or similar utility.

[jpirola]

Yes, I am using "
/admin/api/2023-01/orders/4961628160182/fulfillment_orders.json" and still
getting nothing returned from my post. Did you see my message that if I
use the URL in my browser I get:
{"errors":"The api_client does not have the required permission(s)."}
?
Could it be because when I look at the fulfillment orders info it tells me
that the 'support_actions' are only 'create_fulfillment' and 'hold'? Am I
missing something there?

Everything looks perfect, but something is wrong somewhere and I'm beyond
frustrated
Thanks!

[prg74]

Are you trying to see the fulfillment_orders for a particular order? If so that would be GET not POST.

If you are trying to take some action on a fulfillment_order the  use the documentation below for the various endpoints for a fulfillment_order

https://shopify.dev/docs/api/admin-rest/2023-04/resources/fulfillmentorder

[jpirola]

I am trying to SET the shipment info on an order. So I'm doing a POST to
/admin/api/2023-01/orders/4961628160182/fulfillment_orders.json
and this is exactly it...

Array
(
[fulfillment] => Array
(
[notify_customer] => 1
[tracking_info] => Array
(
[number] => 9241990108294708904279
[company] => USPS
)

[line_items_by_fulfillment_order] => Array
(
[fulfillment_order_id] => 5981129310390
[fulfillment_order_line_items] => Array
(
[0] => Array
(
[id] => 12465625792694
[quantity] => 1
)

[1] => Array
(
[id] => 12465625759926
[quantity] => 1
)

[2] => Array
(
[id] => 12465625727158
[quantity] => 1
)

[3] => Array
(
[id] => 12465625694390
[quantity] => 1
)

)

)

)

)
Where the fulfillment order ID is correct as are the item IDs with their
qtys

[prg74]

You want to create a fulfillment. You should be POSTing to /admin/api/2023-01/fulfillments.json

https://shopify.dev/docs/api/admin-rest/2023-04/resources/fulfillment

[jpirola]

Ah ha! Thank you! That - almost - worked! It finally returned something:

Array
(
[errors] => Array
(
[line_items_by_fulfillment_order] => expected Hash to be a Array
)

)

Which makes no sense to me...

[garyrgilbert]

Hi there, 

Firstly if you are getting {"errors":"The api_client does not have the required permission(s)."} when you call that from the browser that has nothing to do with your app or private app permissions but the user permissions you are logged in with on the shop. This happens to me when I am logged into a client shop but not when logged into a dev shop as owner.

Secondly, the expected hash to be an array is because you have an error in your json document when posting to the fulfillment endpoint. I would double check that the json that your code is producing is correct. .

Cheers

Gary

[prg74]

I'm also struggling a bit to wrap my head around the fulfillment orders and which way to implement handling them.

Currently, we have subscribed to the orders/created, edit, paid and cancelled webhooks and build the order for our end using the order data. Once we ship we POST a fulfillment and the line items that were shipped.

It seems one could just pull the fulfillment orders (open I assume) for an order and then create fulfillments associated with the fulfillment order. Or would using assigned_fulfillment_orders make more sense?

The FulfillmentService route appears to be more complex but not necessarily a prerequisite to using fulfillment orders. Is a FulfillmentService and all it entails required to properly handle fulfillment orders?

[MozzoERP]

I'm curious too. I'm thinking the same approach as you for now. We act as an order management app so we still need the regular order, not just the fulfillment order, but for all our clients, they are one to one....i.e. one order has just one fulfillment order. Today we store the Order Line Item Id so we can use it when posting line item level fulfillments. Maybe we just need to store the Fulfillment Order's Line item Id as well (as a short cut for now) so we can post the fulfillment correctly.

We also use the order webhook as the workflow start point. So the new flow would be:

- receive order webhook

- create order in our system

- pull the Fulfillment Order (FO)

- match Oder Line IDs to the FO's line IDs and store them in a new column in our order detail record

- pick/pack/ship order

-post FO fulfillment using new column where we saved the FO line item id

[prg74]

Your proposed new flow seems close to what I'm starting to arrive at.

We're a bit of order management but more a 3PL. While we might technically be a candidate to implement the entire FulfillmentService workflow it is a bit more than we tend to need to meet the needs of our clients.

We're doing similar storing the order line item id and regardless of new workflow will need to inspect the order data along with the fulfillment order(s). I'm thinking that using the assigned_fulfillment_orders endpoint with our location id will give us the FOs we need to handle. It would be nice to have the order line item id in the fulfillment order.

Now need to figure the fulfillment_orders webhook topics to subscribe to so that we can handle for changes and such.

Another wrinkle (at least for us) - our current workflow gathers the order line items and builds the order on our end matching the SKU in our system with the order data. Fulfillment Orders allows for getting away from SKU matching by using the inventory_item_id. The downside, which has always existed I suppose, is now a shop owner can create 2 products with the same SKU and 2 different inventory_item_ids will be assigned. On our end we'll need to figure a way to store multiple inventory_item_ids for a single SKU. But that's a bit off topic...

[prg74]

Strike using assigned_fulfillment_orders - it requires a Fulfillment Service.

[garyrgilbert]

@prg74  yep, unless you are an actual fulfillment service I would stick with the simpler approach