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

1. Customer places an order in the Spresso Storefront.

2. 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

3. 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

4. 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.

     HTTP

     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.

     HTTP

     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

     HTTP

     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.