Overview
Spresso's Order Fulfillment APIs enable integration of your fulfillment systems with the Spresso Storefront. The APIs allow you to:
- Register webhooks which get called for certain events, e.g. when an order is ready for fulfillment
- Update fulfillments
- Update shipment and tracking information
Definitions
Order: An order is a customer's request to purchase one or more items via the Spresso Storefront
Fulfillment: A fulfillment is a set of items that will be fulfilled from the same location - an order can contain one or more fulfillments
Shipment: A shipment is a set of items sent via the same carrier and tracking number - a fulfillment can contain one or more shipments
Typical Order Fulfillment Integration Flow
-
Customer places an order in the Spresso Storefront.
-
The Spresso Storefront queues the order until the order is fulfillable. An order is considered fulfillable when it is paid [a] and a grace period has passed [b].
- If an order is cancelled before it is fulfillable, it will not be communicated to the fulfillment system
-
Once an order is considered fulfillable, the Spresso Order Fulfillment API emits an Order Fulfillable Webhook to the registered endpoint(s).
- You should record order information in your own system, particularly:
- Order Number (orderNo) - this is the order number a customer sees
- Fulfillment ID(s)
- Variant ID(s) for each Fulfillment ID - including quantity
- You should record order information in your own system, particularly:
-
At this point, proceed with your own fulfillment flow and send relevant updates to Spresso, an example flow should look like:
-
Provide shipment details for the fulfillment by updating the fulfillment’s shipments.
PUT /v1/fulfillments/{fulfillmentId}/shipments HTTP/1.1 Authorization: Bearer {token} Content-Type: application/json { "carrier": "ups", "carrierReferenceId": "UPS1234567", "trackingNumber": "123456666", "trackingUrl": "https://www.ups.com/track?loc=en_US&tracknum=123456666&requester=ST/", "shipmentVariants": [{ "quantity": 1, "variant": "6114950eb9b960697c78d098" }] }
-
When the fulfillment is shipped, update the fulfillment's status to
in_transit
with all fulfilled variants included.PUT /v1/fulfillments/{fulfillmentId} HTTP/1.1 Authorization: Bearer {token} Content-Type: application/json { "status": "in_transit", "fulfillmentVariants": [{ "fulfilledQuantity": 1, "variant": "6114950eb9b960697c78d098" }] }
Note:
Please be sure to include all variants within fulfilled variants when setting fulfillment status to
in_transit
. This is so that we can account for how many of each variant were actually fulfilled and only charge your customer accordingly when we settle the order.
-
When shipment has been delivered, update the fulfillment's status to
delivered
PUT /v1/fulfillments/{fulfillmentId} HTTP/1.1 Authorization: Bearer {token} Content-Type: application/json { "status": "delivered" }
-
Note on Order Cancellation
For an order to be cancelled after it is fulfillable, it must be cancelled in Foxtrot (the admin console) and then an order cancellation webhook will be emitted.
Important:
Fulfillments cancellations via API requests are not supported
Footnotes:
[a]: Excluding cash on delivery payments.
[b]: A grace period (configurable - 10 minutes by default) to allow the customer to cancel the order before the order goes to the fulfiller.
Updated 8 months ago