Skip to content
Flows
Order Fulfillment

Order Fulfillment

Fulfilling an order in the ShipHero app involves several steps.

First, a shipment and its label are created. Then inventory is removed for the shipped items, and the order status is updated to fulfilled.

The Public API does not provide a single mutation for this workflow. Use these three mutations instead:

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

Warning

In a 3PL-child account relationship, create shipments at the 3PL level without using the customer_account_id field.

Shipment Create mutation

Use the shipment_create mutation to create the shipment, attach the label, and trigger the store notification (for example, Shopify or another standard store integration, 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
  }
}

Note

  • The label URL must be a valid URL.
  • Include the line items being shipped in the mutation.
  • You do not need to send created_at; the mutation uses the current date.

Inventory Remove mutation

After creating the shipment, remove inventory for each shipped item. shipment_create does not deduct inventory.

Use the inventory_remove mutation for this step.

For example:

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

Note

  • sku, warehouse_id, and quantity are required.
  • If the product has no available stock, the mutation will not affect inventory. Check availability first to avoid discrepancies.
  • The reason field appears in the inventory log in the UI.
  • You can also specify the location_id to deduct inventory from a specific location. This is useful for Dynamic Slotting accounts. See this section for details.

Order Update Fulfillment Status mutation

Finally, use order_update_fulfillment_status to set the order and included line items to fulfilled.

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, use order_update_line_items instead and update only the shipped line items.

Order Update Line Items mutation

Use order_update_line_items to mark only the shipped line items as fulfilled.

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
  }
}
ReturnsPurchase Orders