Covers all questions related to inventory management, order fulfillment, and shipping.
In the 2022-04 release, we deprecate a number of legacy Fulfillment API endpoints that interact with fulfillments at the order level. The Fulfillment Order API was introduced in the 2020-01 API version to replace these legacy endpoints. To help you in your migration, we’ve put together answers to questions you may have about how to use Fulfillment Orders, how it differs from Fulfillments and why it creates a better fulfillment and order management experience for merchants.
Why is Shopify deprecating some endpoints on the Fulfillment API?
While using Fulfillment and Order resources to fulfill orders was once considered standard, this legacy behavior is no longer compatible with modern workflows. This holds apps back from a better, more accurate, way to fulfill and manage orders and makes it difficult for merchants to have visibility and control over their inventory and fulfillment. Fulfillment Orders API helps apps model the entire fulfillment process more accurately into its sub-pieces and unlocks access to new features like local delivery & pickup, fulfillment holds, subscriptions and more. The Fulfillment API will still exist and will still be used for some actions.
Does Fulfillment Orders do more than the Fulfillments APIs does today?
Yes! Using Fulfillment Orders allows your app to do more than using the Fulfillment API alone does today! In fact, the Fulfillment Orders API models the end-to-end fulfillment process into its sub-pieces, so fulfillment data can sync more accurately between Shopify and an order management app or a 3PL. The Fulfillment Order API tracks the lifecycle of fulfillment work, including open, in-progress, closed, canceled or incomplete, so merchants have a more granular and complete view of their order data in Shopify. It also represents the exact items that need to be fulfilled in a location for a given order, improving the accuracy of order fulfillment.
What fields and endpoints are being deprecated with this release?
You will still be able to see the fulfillment relationship at the order level, however apps will not be able to fulfill orders unless using Fulfillment Orders. To provide more detail, here are the endpoints/mutations that are going away.
REST
GraphQL
When should apps start using Fulfillment Orders?
Some of the Fulfillment API endpoints are being deprecated in the Shopify 2022-04 release. Apps will have until the 2023-06-30 date to start using Fulfillment Orders. The original 2023-03-31 deadline of 2022-04 API version was postponed to 2023-06-30with this public notice. Please follow the migration guide or visit our community forums to ask questions.
How do I move to Fulfillment Orders?
To help you seamlessly migrate, we’ve crafted a migration guide that walks you through the process of moving to Fulfillment Orders. If you’re wondering what it might look like once updated, take a look at our sample application detailing how fulfillment and order management is done before and after Fulfillment Orders.
How will current installs be impacted by moving to Fulfillment Orders?
If merchants using your app have already granted read_fulfillments or write_fulfillments, rest easy, as they will not have to agree to new permissions. Instead, you can request granular access scopes for an individual shop installation. Refer to our migration guide for more details.
How can Fulfillment Orders help to fulfill orders with sales channels?
If a merchant is selling a product on a third party marketplace or sales channel, your app will get the most up to date information on the status of the order and help you to accurately fulfill orders at the right time. Previously, legacy fulfillment services would automatically create pending fulfillments for the fulfillment service when fulfillment is requested. As merchants expand their business to capture orders on various sales channels, this has created issues in cases where orders should not be fulfilled immediately and instead placed on a temporary hold until payment is captured. With Fulfillment Orders, apps no longer need to rely on webhooks to update fulfillment fields. Instead, Shopify will create successful fulfillments in place of pending fulfillments for the fulfillment service when a fulfilled order is imported.
How can Fulfillment Orders help to manage inventory across multiple locations?
Fulfillment orders are always an accurate representation of where an item should be fulfilled from. Shopify now allows variants to be stocked at third-party locations and merchant managed locations at the same time, yet the fulfillment_service on variants is no longer an accurate representation of the service that is exclusively responsible for fulfillment. Your app must use the “assigned location ID” on any open fulfillment orders to understand definitively who is responsible for fulfilling any given order.
- To learn more visit the Shopify Help Center or the Shopify Blog
Yes, there are new fulfillment order webhooks coming. You can find a list here: https://shopify.dev/apps/fulfillment/order-management-apps/manage-fulfillments#webhooks
To learn more visit the Shopify Help Center or the Community Blog.
Woohoo anyone here?
@Shopifythe migration docs are very incomplete (please add something about tracking - right now, it is misleading and makes us think we can't use the tracking endpoints - particularly when paired with the deprecation message in the fulfillment api resource documentation) and the example repository is using tons of deprecated APIs.
Please check out the thread in Discord about this - lots of folks are concerned and confused.
Same here. The documentation and the migration guide are both not clear about how to actually fulfill orders using the FulfillmentOrders API. We still have to use the Fulfillment API to create a fulfillment.
That is correct, you still use the fulfillment API to create a fulfillment. The fulfillment order indicates the items to be fulfilled from a location. The fulfillment represents the actual physical shipment with a tracking number.
To learn more visit the Shopify Help Center or the Community Blog.
Some additional examples have been added. https://shopify.dev/apps/fulfillment/order-management-apps/manage-fulfillments#create-a-fulfillment
To learn more visit the Shopify Help Center or the Community Blog.
Hi @RobZone , We are moving our API to the new endpoints but we have not find a way to fulfill two items from same order from diferent locations, that was very easy in old endpoint as you could send location_id on fulfillment request, but now the entire FulfillmentOrder has only one location attached, you cannot send location_id on Fulfillment request and there is no REST or GraphQL Endpoint to create a new FulfillmentOrder for an existing order. Please help us to complete the migration before deadline.
Normally such an order would have multiple fulfillment orders. A fulfillment order is created for each location with the item in stock. This situation should not be common unless inventory is not in sync with Shopify. It is a valid use case and we are looking into it. In the meantime, you can create a fulfillment for the items in the first location, then move the fulfillment order to the second location to create a second fulfillment.
To learn more visit the Shopify Help Center or the Community Blog.
I create an order with an item in several locations and only one FulfillmentOrder gets created. About your solution is possible to move a FulfillmentOrder that has Fulfillments already created?
@develop Yes, you can move a fulfillment order after you have created a fulfillment. I think we should work through your specific use case via a support request instead of this community topic.
To learn more visit the Shopify Help Center or the Community Blog.
@RobZone thanks for your clarification I could solve the use case and now I think we´re ready to implement in code, but just checked the flow using CURL and I solved our issue with how to generate two tracking codes from two different locations for one order, in case anyone is looking for something similar the key is to call move.json endpoint and it returns you a new FufillmentOrder on field moved_fulfillment_order.
Thanks a lot!
Hello Shopify
I have a private app installed and using basic Authentication on postman I can get the fullfillment orders
https://lacodemo.myshopify.com/admin/api/2023-04/orders/4903607894204/fulfillment_orders.json with the request status "Unsubmitted". How do I change it to submitted?
Result:
Question, I have a legacy PRIVATE app, using shopify_api gem version 9.51. Can I stay on that version and use the new FulfillmentOrder endpoint, or do I need to move to the new(er) versions of the Gem ?
If I have to move to anything past 9.51 a lot of the legacy code will break, and have to be rewritten. So it is important to know if I must go to the later versions. [Example, the configuration to set the Shopify connection changes significantly, as does pagination, resources are no longer ActiveSupport wrapped but just Httparty JSON resources, etc.].
Any guidance on the required gem version will be very helpful.
I took a quick look at the 9.5.1 code. It does support fulfillment orders, but it was built for API version 2020-01, which was out of date two years ago. It might work, but it is unsupported.
To learn more visit the Shopify Help Center or the Community Blog.
Hi @RobZone
To be clear
This endpoint is being retired
/orders/{order_id}/fulfillments.json
we need to configure the new POST endpoint below, but the description says "fulfilment order as incomplete", should is say "fulfilment order as complete" or is fulfilment order complete a different end point?
POST /admin/api/2023-01/fulfillment_orders/{fulfillment_order_id}/close.json
Description- Marks a fulfillment order as incomplete
The text is correct, if a fulfillment service cannot satisfy the request even though they accepted it, they call this endpoint to indicate that the order will not be fulfilled.
To learn more visit the Shopify Help Center or the Community Blog.
Thank you @RobZone
So which one of these POST API end points do we use to fulfill a satisfied order in the new
FulfillmentOrder API's below?
None of them. You use use this endpoint to create a fulfillment for a fulfillment order: https://shopify.dev/api/admin-rest/2023-01/resources/fulfillment#post-fulfillments
To learn more visit the Shopify Help Center or the Community Blog.
Thank you very much, this helps quite a bit in evaluating what I have to do.
It says in this article it supports all and more than the deprecated API. Can you show the JSON Body needed with 2023-01/fulfillments.json to populate tracking_numbers and tracking_urls with more than one number and more than one url? Our customers order one line item that ships in multiple boxes. The deprecated API supported multiple tracking numbers per line item.
This is not currently supported by the REST API. It is supported by GraphQL.
https://shopify.dev/api/admin-graphql/2023-01/mutations/fulfillmentCreateV2
https://shopify.dev/api/admin-graphql/2023-01/mutations/fulfillmentTrackingInfoUpdateV2
To learn more visit the Shopify Help Center or the Community Blog.
Hi @RobZone ,
Like Fwallace, I have a lot of code that will break if I have to use the newer gem versions
Right now I am using a 9 version gem, and I am fulfilling my orders this way:
-Getting the order via the REST API (ShopifyAPI::Order.find(...))
-looping through the order to get all the fulfillment_order_id into an array
o.fulfillment_orders.each do |fo|
fulfillment_order_ids << {:fulfillment_order_id => fo.id}
end
-And fulfilling with the following line :
ShopifyAPI::Fulfillment.new(:notify_customer => notify_customer, :tracking_info => tracking_info, :line_items_by_fulfillment_order => fulfillment_order_ids, :location_id => location_id)
Will this method still work after March 31st ?
Yes, this API has not changed in the deprecation. If the gem works now, this code will still work in April.
To learn more visit the Shopify Help Center or the Community Blog.
Thanks a lot !
I had an email on 2nd Feb saying that my custom app uses Fulfillments API but I'm using fulfillmentCreateV2 with API version 2023-01. That's the new version isn't it? Is there any way of checking to pinpoint why I'm getting this warning? The shop name is official-car-mats
@Ashley_Kennerle the orders query made by your private app is accessing the line_item field on fulfillment order. This was deprecated in API version 2023-01, so there is no immediate need to update. If you are having trouble adapting your app, please start a new thread in this community and we will try to help.
To learn more visit the Shopify Help Center or the Community Blog.
Hi RobZone, I started a new thread but haven't had any replies, would you be able to have a look please?
Any Idea how if Shopify have a test environment to test the new end point?
Question @Shopify: Is fulfillment/create and fulfillment/update webhooks being deprecated (now or near future)?
@munawwarfiroz No, fulfillments are still created and can be updated in the API. We are only removing the order-based fulfillment creation endpoint and fulfillments in PENDING state.
To learn more visit the Shopify Help Center or the Community Blog.
@Shopify @RobZone We are moving our API to the new endpoints, however. Some endpoints are going away which makes the previous endpoints below difficult to get well replaced.
POST /admin/api/2021-01/orders/{order_id}/fulfillments.json
PUT /admin/api/2021-01/orders/{order_id}/fulfillments/{fulfillment_id}.json
POST /admin/api/2021-01/orders/{order_id}/fulfillments/{fulfillment_id}/complete.json
POST /admin/api/2021-01/orders/{order_id}/fulfillments/{fulfillment_id}/open.json
POST /admin/api/2021-01/orders/{order_id}/fulfillments/{fulfillment_id}/cancel.json
Really appreciated if you point out the corresponding new endpoints for each one of the five. Thank you!
@DevFuns1
Please take a look at https://shopify.dev/docs/api/admin-rest/2022-07/resources/fulfillment
You will see that some Fulfillment API end points have been removed after the 2022-04 API Version, but not all. E.g. Cancel and Create still exist.
The other end points have moved to https://shopify.dev/docs/api/admin-rest/2022-07/resources/fulfillmentorder as you should now be completing, cancelling, closing, holding, opening fulfillment_orders.
It is worth noting that the simplest workflow with Fulfillment orders is:
- Shopify will auto create fulfillment orders for all orders.
- You then get fulfillment_orders for each order. (e.g.
/admin
- call fulfillment for each fulfillment order to fufill those fulfillment orders (e.g.
/admin/api/2022-07/fulfillments.json). You can fulfill all or part of each fulfillment_order with each fulfillment.
The above requires write_third_party_fulfillment_orders access scope which may not be ideal though.
If the store enables auto fulfill, then the fulfillment_requests will be sent automatically to the fulfillment_service, and the fulfillment_request will need to be accepted. That is the next shortest workflow.
More details as an order management system
https://shopify.dev/docs/apps/fulfillment/order-management-apps/manage-fulfillments
More details as a fulfillment service
https://shopify.dev/docs/apps/fulfillment/fulfillment-service-apps/manage-fulfillments
To learn more visit the Shopify Help Center or the Community Blog.
@rob @alexc_shopify
Hello!
I am a developer at a large Sport Brand using Shopify as their platform, selling globally with Shopify Plus. I am trying to figure out how to migrate to the new API, but in spite of reading all the guides and documentation, I'm a still a bit unclear. Messages in this thread though shed some light into the mist of my confusion though, so I'm grateful for that.
Would you mind if I just briefly summarize my use case, and then you can tell me the high level way I should think about migrating over?
Here is our set up (created by another dev and then handed over to me), which we have used for a long time:
A lot is happening in here, but the point of the backend process is to get the order, perform some checks and transformations, and ultimately -> create an XML file which we are handing to our ERP system Microsoft Dynamics AX.
We are also calling this endpoint in this backend process:
So, my question is if anyone could be kind enough to explain what (in a very high level way, just step-by-step in the abstract) what I need to change and what I don't need to change?
Some confusions I have are, for example:
Will I need to kind of... create a new "FulfillmentService" instead of using this warehouse like we always have?
So, soon the new month is here which means the way we have done things now for many years will probably break if I am not actively fixing this. This is obviously causing some stress, so if there is any help at all that I could get from this from the Shopify API team or someone with some knowledge on this, would be greatly appreciated.
Thank you so much! 😃🙏
Hi @Dawid_Umain
I should first mention that the removal of some of the 2022-04 Fulfillment API end points has now moved to the end of June 2023. You can also request an additional grace period for your app IDs of 60 days taking the date you need to be compliant to August 30th. Let us know if you wish to do this.
For your questions about how to update your current process:
To learn more visit the Shopify Help Center or the Community Blog.
Hello, @alexc_shopify! Thank you so much for your response. I will check out all the resources you shared.
Your response is still very general. Would it be possible to be more specific for my specific use case that I outlined in my 6 points? (I'm sure there are other people out there who have similar use cases, too.)
For example:
Any help would be greatly appreciated.
(That said, I will now read through everything you wrote. Thank you so much! 🙏)
Our developers rolled out our switch to the Fulfillment Orders API on March 16. We received an email on March 29 warning us that we were still using the deprecated Fulfillment API. Is there any way to tell if that email is accurate (and we missed something) or if it based on usage earlier in the month (and we can ignore it)?
@RB The email was likely triggered by earlier usage. With the REST API, you can also check for X-Shopify-API-Deprecated-Reason headers in the responses.
To learn more visit the Shopify Help Center or the Community Blog.
Cross post from Admin REST API
We have an Order Management App that stores use to pull in open orders and create fulfillments of these orders.
We see line items on orders, creating separate Fulfillment Orders that are not physical objects or digital assets but just extra charges - "Route Protection" in this case. And we've seen the same with Gift Cards. Stores are unsure what to do with these separate Fulfillment Orders when they think of this as one Fulfillment since they aren't shipping from multiple locations.
The supported actions on the Fulfillment Order for this example item is [ "create_fulfillment", "hold" ]
I want to help stores resolve these Fulfillment Orders, so my questions are about choosing the best solution:
Option 1: Ignore any Order line items with value of "requires_shipment": false
We could ignore these associated Fulfillment Orders & leave them "unfulfilled" ( in your reply above you mentioned looking at the possible actions: the supported actions on these are [ "create_fulfillment", "hold" ])
Can you leave unfulfilled Fulfillment Orders of this type (not a deliverable item) on an account indefinitely?
Option 2: Automatically Fulfill Order line items with value of "requires_shipment": false
For order items like route protection, we could automatically "fulfill" the associated Fulfillment Order. We could have our app send this via the API. The other option is if there is a setting in Shopify per product to have certain items auto-fulfill - is this possible?
Your response above says:
| They may have auto-fulfillment already setup for certain items.
The linked document refers to auto-fulfilling entire orders. Can specific items/products within one order be auto-fulfilled & others manually? Or is this a per order/per store setting?
Option 3: Configure a product to not need any fulfillment/ not generate a Fulfillment Order
Is this possible?
The example of Route Protection paid on an item seems like a good candidate if possible.
Option 4: Configure these Route Protection products to not generate separate Fulfillment Orders
This option has worked because then the Shopify store pulling orders from the API sees the Route Protection line item on their Fulfillment Order AND when they fulfill this via the API all fulfillment orders are closed (since there is only one in this case)
One downside to this is that warehouses & 3PLs might try to pack this non-physical/non-digital product when they see it on the Fulfillment Order.
This is also complicated when a store is shipping physical items from multiple locations - which FO would this line item end up on? Maybe not important as we haven't seen this yet.
Thanks for reviewing!
Ideal solutions seem to be having the ability to have certain items/products not generate any FulfillmentOrder OR if certain items can be marked as fulfilled automatically in the Shopify Platform.
If we do solve this by instead having our app auto-fulfill when we see a line item that doesn't require shipping we'd need a way to distinguish between non-deliverable items like Route Protection or a digital item that a customer needs delivered but not shipped.
To auto fulfill certain items, you would stock them at the manual merchant managed (shopify) location and not at any fulfillment service location.
With auto fulfill on, the items (route protection in your case) stocked at the merchant managed location will auto fulfill.
The items stocked at fulfillment services will auto request fulfillment from the relevant fulfillment service location.
It isn't possible for for some items to not generate a fulfillment order. Any item with a different shipping profile or location to other items in the order will be in their own fulfillment order.
You could also never fulfill non shippable items, but that would leave the 'unfulfilled' status on the order for ever. So I would not recommend that.
To learn more visit the Shopify Help Center or the Community Blog.
Hi there,
We are still receiving an email saying our app is leveraging the soon to be deprecated fulfillment process, but we went through the migration steps and to our knowledge switched everything over as it is supposed to be? Everything appears to be working. I am concerned we are missing something. I went through the migration guide and api docs once again and don't see any reference to the old api?
"TL;DR: Please note that your custom app(s) are leveraging deprecated Fulfillment API endpoints. To minimize disruptions we’re giving you an additional 3 months to update your app(s) to the new Fulfillment Order API. Read the migration guide and migrate to the new Fulfillment Order API by June 30, 2023 to avoid breaking changes."
How to change location using graphql fulfillmentcreate API
As I can see its not possible
in our case multiple tracking number and fulfillment location change frequently
so we have changed REST API to GraphQL but not facing location issue
Can anyone guide on it?