How to migrate to fulfillment orders as a middleman

Retired Boards Appdev Fulfillment Api
6

Fulfillment Service

As you do not create a fulfillment service entity for every shop your app work with, your app is not a fulfillment service. In terms of permissions and interactions with client shops, you are an order management app. You manage orders from merchant-managed locations, take care of them being fulfilled, and close them. So you do not need assigned_fulfillment_orders access scope. I see you have managed to get merchant_managed_fulfillment_orders access scope with request_granular_access_scopes based on the read/write_orders access scope you have had. That’s it. I’ll think about how we can improve steps 1-2 in the migration guide to make it more clear.

Your app could be a fulfillment service app and offer the same service. Merchants communicate with fulfillment service apps via fulfillment and cancellation requests, and the fulfillment service app has an option to reject requests.

Can (should) we continue to use the fulfillments/create webhook to get fulfillment notifications from wholesale? Even the latest API version still includes this webhook topic, so it doesn’t appear to be deprecated.

That’s right. The Fulfillment resource and fulfillment webhooks remain. When some or all of order line items are fulfilled, you will receive fulfillments/create webhook.

The [POST] orders/{order_id}/fulfillments endpoint has been deprecated. It appears that the [POST] /fulfillments endpoint is the closest replacement for this action. Is this the best method?

Right. FulfillmentOrder entity stays in the middle of orders and fulfillments, and now we granularly fulfill fulfillment orders rather then orders directly.

The [POST] /fulfillments endpoint requires passing fulfilled line items by FulfillmentOrderID. At what point is a FulfillmentOrder created? Who creates it and how?

Shopify creates fulfillment orders automatically when an order is created. It is not possible to manually create fulfillment orders.

Correct me if I’m wrong, but neither the fulfillments/create payload nor the Fulfillments resource via the REST API include the ID of the parent FulfillmentOrder resource.

Fulfillment entity does not contain fulfillment_order_id. The thing here is, the relationship between Fulfillments and FulfillmentOrders on the same order is many-to-many. One FulfillmentOrder may be fulfilled via several partial Fulfillments. One Fulfillment can contain line items from several fulfillment orders on the same order. See

FulfillmentV2Input.lineItemsByFulfillmentOrder (same for the REST api).

So the question you ask is “How do I map line items from the client store order to the items fulfilled by the wholesale store”.

  1. You receive the “fulfillments/create” webhook from the wholesale site. The webhook gives you the fulfillment_id and order_id.

  2. You map this order_id to the client’s order_id (you keep this mapping in your DB). Your query GET /order/<client_shop_order_id>/fulfillment_orders on the client shop.

  3. If there is only one FulfillmentOrder in the client’s shop on this order and in the wholesale store has fulfilled the entire order at once, you can fulfill the whole order on the client site with POST /fulfillments

{
  "fulfillment": {
    "line_items_by_fulfillment_order": [
      {
        "fulfillment_order_id": <client_site_fulfillment_order_id>
      }
    ]
  }
}