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.
- Shipment Create mutation
- Inventory Remove mutation
- 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_remove
mutation.
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_
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.