Creating Fulfillments While Creating An Order With The Shopify API

Solved

Hey There,

   I've had some interactions with the Shopify dev support team in the past about creating fulfillments with the Order API.  I'm trying to create a Fulfillment while creating an order so merchants can adding tracking numbers and locations to their orders when the order is created.  However, I'm seeing some strange behavior with the Order API when doing so.  It's mainly around creating the fulfillment for partially fulfilled orders.

   For example, if I send an Order with two line items 1 is fulfilled and the other is unfulfilled the Order is created with a fulfillment and there is only one line item displayed.  If I look at the raw JSON on the order I can see two line items but only one is displayed.  I've tried sending the fulfillment with the line items that should be fulfilled as well and this seems to cause the same issue.  The only thing that seems to work is creating an order where all line items have a fulfillment status of unfulfilled in which the API will create a fulfillment with both line items associated with it.

   I've run into similar issues in the past and was told to provide the line item fulfillment_status and not the order fulfillment_status and this should solve any issues, but I can't seem to create an order that is partially fulfilled when sending the Order with Fulfillment data.  This seems like it could be a bug as the documentation doesn't seem to have any further details about how to properly do this.

I'm hoping someone can give me some guidance on using the Order API to create orders (all order types, e.g. fulfilled, partially fulfilled) with fulfillment data.

If you have any further questions, need me to run tests just let me know as I can easily reproduce this.

Ralph

Co-Founder / Developer at Highview Apps
Our Shopify Apps: EZ Exporter | EZ Inventory | EZ Importer | EZ Notify | EZ Fulfill
0 Likes
syf_
Shopify Staff
Shopify Staff
89 20 15

This is an accepted solution.

Hi Ralph,

Thanks for the detailed explanation on the issue you're experiencing. I'm hoping I'd be able to provide enough context that's useful to you regarding this issue.

With regard to using the Order API to fulfill orders, what works currently is to completely fulfill an order. We do not currently support partial fulfillments using the Order API while specifying additional info such as location and tracking; though it's a feature that could become available in the future. I am not able to say if or when such a feature might become available but our developers are investigating this behaviour.

To completely fulfill an order with the Order API , you do not need to pass the fulfillment_status field in the body of your request. See below for a minimum working example on how to achieve this.

POST /orders.json

{
  "order": {
    "email": "foo@example.com",
    "fulfillments": [
            {
                "tracking_company": "testing.com",
                "location_id": xxx,
                "tracking_number": "123456789",
                "tracking_url": "testing.com/track/123456789"
            }
    ],
    "line_items": [
      {
        "variant_id": xxx,
        "quantity": 1
      },
      {
        "variant_id": xxx,
        "quantity": 1
      }
    ]
  }
}

The constraints on achieving this are that:

 

  1. All order items must be fulfilled from the same location
  2. You can only create a single fulfillment within the order

It is possible to create a partially fulfilled order (this shows up in the Admin), but the caveat is you cannot specify any fulfillment data in your request body, and you'd have to include the fulfillment_status of the individual order_line_items. A simple call to do this is shown below. The downside to this is that since no location information was specified any location that has inventory for the product can be used (first choice is the default location specified in the Admin).

POST /orders.json

{
  "order": {
    "email": "foo@example.com",
    "line_items": [
      {
        "variant_id": xxx,
        "quantity": 1
        "fulfillment_status": "null"
      },
      {
        "variant_id": xxx,
        "quantity": 1
        "fulfillment_status": "fulfilled"
      }
    ]
  }
}

 

However, you can update the order with tracking info via the Fulfillment API with a PUT request to the /orders/{order_id}/fulfillments{fulfillment_id}.json endpoint and it shows up in the Admin. I gave a sample request below. It is important to note you cannot update the location after fulfillment is complete, hence you won't be able to update the location the system chooses.

{
  "fulfillment": {
    "tracking_number": "987654321",
    "id": xxx,
    "tracking_url": "me.com/987654321",
  }
}

 

Finally, to achieve what you want, the best way to do this to the best of my knowledge is to use at least two calls (one to create unfulfilled orders, and a second to create a fulfillment for the order_line_item of interest.

POST /orders.json

{
  "order": {
    "email": "foo@example.com",
    "line_items": [
      {
        "variant_id": xxx,
        "quantity": 1,
        "fulfillment_status": "null"
      },
      {
        "variant_id": xxx,
        "quantity": 1,
        "fulfillment_status": "null"
      }
    ]
  }
}

 

POST /orders/{order_id}/fulfillments.json

{
  "fulfillment": {
    "tracking_number": "987654321",
    "tracking_url": "test.com/987654321",
    "location_id": xxx,
    "line_items": [
      {
        "id": {order_line_item_id}
      }
    ]
  }
}

 

I hope this clarifies the question you had in terms of what's possible or not in using the Order API in fulfilling items. If you have any additional questions regarding this, don't hesitate to get back to me, and I'll do my best to answer them.

Thanks,
Seth.

 

syf_ | Developer Support @ Shopify 
 - Was my reply helpful? Click Like to let me know! 
 - Was your question answered? Mark it as an Accepted Solution
 - To learn more visit Shopify.dev or the Shopify Web Design and Development Blog

0 Likes

Hey @syf_ ,

   Thanks for the detailed response!  I was afraid you were going to say this.  I spent a lot of time playing with this behavior and came to this conclusion but wanted to make sure.  It would be fantastic if the API would be able to support adding location, tracking numbers, etc on partial fulfillments.  I think not supporting it makes the API a bit confusing on the development side and also makes the behavior inconsistent.  We have a lot of merchants that use our app that import a very large amount of orders so I'm doing my best to avoid the extra API calls as it will introduce the N + 1 problem which will slow down the import time significantly.  

Anyway, thank you for putting all this detail together.  If I have further questions about this I'll be sure to reach out and hopefully this gets added in a future release.

Ralph

Co-Founder / Developer at Highview Apps
Our Shopify Apps: EZ Exporter | EZ Inventory | EZ Importer | EZ Notify | EZ Fulfill
0 Likes