FulfillbotDocs
Menu
MarkdownDownload

From order to delivery

This guide follows one dropship order from your store to your buyer's door.

1. Make sure your products match

List GET /v1/products and keep our id for each of your products. Map each of your SKUs once with POST /v1/sku-mappings; afterwards your order lines can carry just your SKU. Check stock with GET /v1/inventory.

2. Check the order

Send the order to POST /v1/orders/preview. The preview tells you whether it would go straight to fulfilment (willReserve), which problems it has, which shipping options it can use and at what price, how much it would hold in your wallet and which products are short. Nothing is saved, so you can call it as often as you need.

3. Create it

Send the same body to POST /v1/orders with a new Idempotency-Key, stored with the order so that a retry reuses it (Idempotency). Keep the returned id.

  • If the order has no problems and all its stock is available, the stock is reserved and the estimated shipping and handling fee is held in your wallet (Charges and your wallet). If some products are short, the order waits as BACKORDERED and the hold is placed once its stock is fully reserved.
  • If it has problems, its status is NEEDS_ATTENTION. Fix it with PATCH /v1/orders/{id}, sending the whole order again, or cancel it with POST /v1/orders/{id}/cancel.

4. Follow it

Subscribe to order.status_changed and order.awaiting_payment (Webhook events) and fetch the order with GET /v1/orders/{id} when an event arrives.

  • BACKORDERED: some products are short. backorder lists them and the purchase orders bringing them. With auto purchase on, those purchase orders are paid from your wallet automatically when the balance covers them.
  • RESERVED with payment set (and order.awaiting_payment): the parcel is weighed but your balance was short. payment shows the amount due; top up in the portal.
  • WEIGHED: the parcel is weighed and the fee charged.
  • SHIPPED: fulfilment.trackingNo is set, and trackingUrl when the carrier has one. Pass them on to your buyer and your store.

5. When something goes wrong

  • 409 order_not_editable: the order has moved on and can't be changed through the API. Contact your account manager.
  • 422 order_product_not_allowed: a line points to a product that isn't yours.
  • 409 store_order_no_taken: you already have an order with that storeOrderNo. Look it up before creating another.
  • A network error or timeout on create: send the same request again with the same Idempotency-Key.
  • A saved 5xx on create: list your orders and look for your storeOrderNo before you retry with a new key.