Developer Resources > Examples

Order Fulfillment

 

When fulfilling an order using the ShipHero app, there are several tasks going on.

First, a shipment gets created, with its respective label, then the inventory gets removed based on the items shipped and finally, the order status gets changed to fulfilled.

To be able to mimic this behavior using the Public API there isn’t just one mutation to do all of this, instead, you will have to use three mutations.

  1. Shipment Create mutation
  2. Inventory Remove mutation
  3. Order Update Fulfillment Status mutation

In the case of a 3PL-Child account relationship, shipments must be created at the 3PL level without using the customer_account_id field

Shipment Create mutation

With the shipment_create mutation, you will be creating a shipment, sending with it the label and triggering the notification to the store (Shopify for example, or any other regular store, not an API Store)

For example:

mutation {
  shipment_create(
    data: {
      order_id: "T3JkZXI6MTQzNDE2NDY3"
      warehouse_id: "V2FyZWhvdXNlOjExNzkw"
      address: {
        name: "John"
        address1: "2543 Johnson St."
        address2: "Apt. 2"
        city: "Oklahoma"
        state: "Oklahoma"
        zip: "73008"
        country: "US"
        phone: "5555555555"
      }
      line_items: { line_item_id: "TGluZUl0ZW06NDA5MjA2ODkw", quantity: 1 }
      labels: {
        address: {
          name: "John"
          address1: "2543 Johnson St."
          address2: "Apt. 2"
          city: "Oklahoma"
          state: "Oklahoma"
          zip: "73008"
          country: "US"
          phone: "5555555555"
        }
        carrier: "UPS"
        shipping_name: "UPS - Ground"
        shipping_method: "Ground"
        cost: "0.00"
        dimensions: { weight: "12", height: "12", width: "12", length: "12" }
        label: {
          paper_pdf_location: "https://d2kghplsj0vn8x.cloudfront.net/prod/shipping-labels/2020/08/21/6ea5c0ba88f63dbf3eb8d7e6380f1811491d39da902d1d63a4f13af81bd98040/143071030/2fiu8_3c.pdf"
        }
        line_item_ids: "TGluZUl0ZW06NDA5MjA2ODkw"
        tracking_number: "1234434242444444434"
      }
      notify_customer_via_shiphero: true
      notify_customer_via_store: true
    }
  ) {
    request_id
    complexity
  }
}

NOTES:

  • The label URL needs to be specified here, a valid URL
  • The line items you are going to ship should be included in the mutation
  • You don’t need to send the created_at value, it will pick up the current date, the mutation was sent

Inventory Remove mutation

After creating the shipment you will need to remove inventory for each of the items shipped because the inventory_remove won’t remove inventory.

To be able to do this, you will have to use the inventory_removemutation.

For example:

mutation {
  inventory_remove(
    data: {
      sku: "1122334509"
      warehouse_id: "V2FyZWhvdXNlOjExNzkw"
      quantity: 1
      reason: "Order Nr.123 shipped via Public API"
    }
  ) {
    request_id
    complexity
  }
}

NOTES:

  • sku, warehouse_id & quantity are the required fields
  • If the product doesn’t have stock, the mutation won’t affect the inventory, so to avoid inventory discrepancies you will have to make sure there is inventory available to remove.
  • The reason field will show on the inventory log in the UI, allowing you to see why the inventory was deducted.
  • You can also see the location_id from which you will be deducting inventory. This is useful for Dynamic Slotting accounts. To be able to know the location please visit this section.

Order Update Fulfillment Status mutation

Finally, using the order_update_fulfillment_status mutation you set the fulfillment status to Fulfilled and also the line items inside.

For example:

mutation {
  order_update_fulfillment_status(
    data: {
      order_id: "T3JkZXI6MTQzNDE2NDY3"
      fulfillment_status: "fulfilled"
      reason: "Order fulfilled outside of ShipHero"
    }
  ) {
    request_id
    complexity
  }
}

NOTE:

  • If the order is partially shipped, then you will need to update the fulfillment status using the order_update_line_items mutation instead, and change the status for the line items you shipped only.

Order Update Line Items mutation

Using the order_update_line_items mutation, you can set as Fulfilled those line items that were actually shipped.

For example:

mutation{
  order_update_line_items(data:{
    order_id:"5442355525"
    line_items:[{
      id:"25324524524"
      fulfillment_status:"fulfilled"
      quantity_pending_fulfillment:0
    }{
      id:"25324524525"
      fulfillment_status:"fulfilled"
      quantity_pending_fulfillment:0      
    }]
  }){
    request_id
  }
}