Data Model

In this section, we'll provide an overview of the data model used in the Order Fulfillment API and webhooks. Additionally, we'll introduce enumeration values associated with order and fulfillment statuses to help you navigate the system.

Order Model

An order is a customer's request to purchase one or more items via the Spresso Storefront. It contains one or more fulfillments, as well as important metadata about the order.

{
    id: "65820634daf0b556858ed591",
    orderNo: 19618657, // This is the order number a customer will see
    createdAt: "2023-12-19T21:08:06.162Z",
    status: "sent_to_fulfiller",
    statusHistory: [{
        status: "created",
        updatedAt: "2023-12-19T21:08:06.162Z",
    }, {
        status: "on_fulfillment_queue",
        updatedAt: "2023-12-19T21:08:07.281Z",
    }, {
        status: "sent_to_fulfiller",
        updatedAt: "2023-12-19T21:11:08.119Z",
    }],
    financialStatus: "authorized",
    user: {
        id: "6132b96601ceceabe344dcad",
        email: "[email protected]",
        telephoneNumber: "01234567890",
    },
    shippingAddress: {
        firstName: "Elena",
        lastName: "Wu",
        addressLine1: "1460 Broadway",
        addressLine2: "",
        city: "New York",
        state: "NY",
        postalCode: "10036",
        country: "USA",
        telephoneNumber: "01234567890",
    },
    orderVariants: [{
        id: "658205f64570533aa7548cac",
        quantity: 2,
        fulfilledQuantity: 2,
        variant: {
            id: "65698ded25d03cf922c80f93",
            sku: "MY120123A",
            upc: "9090008008883",
            name: "Bounty Paper Towels",
        }
    }],
    fulfillments: [{
        id: "6582063809abb2706f670f36",
        createdAt: "2023-12-19T21:11:08.124Z",
        fulfillmentMethod: "carrier_delivery",
        fulfillerLocation: "60d56d8e7c88cefd11e7dfc6",
        fulfillmentVariants: [{
            quantity: 1,
            variant: "65698ded25d03cf922c80f93",
        }],
        status: "in_transit",
        statusHistory: [{
            status: "order_placed",
            updatedAt: "2023-12-19T21:11:08.124Z",
        }, {
            status: "received_by_fulfiller",
            updatedAt: "2023-12-19T21:11:08.134Z",
        }, {
            status: "preparing_items",
            updatedAt: "2023-12-19T21:11:09.124Z",
        }, {
            status: "preparing_items_complete",
            updatedAt: "2023-12-19T21:11:18.124Z",
        }, {
            status: "in_transit",
            updatedAt: "2023-12-19T21:12:58.124Z",
        }],

        externalOrderId: "21396", // This is the id in your system for this fulfillment
        externalOrderStatus: "Being Delivered", // This is the fulfillment status in your status (free text)

        shipments: [{
            id: "6397b522b9b3365dba35c62d",
            carrier: "ups",
            carrierReferenceId: "UPS1234567",
            trackingNumber: "123456666",
            trackingUrl: "https://www.ups.com/track?loc=en_US&tracknum=123456666&requester=ST/",
            shippingDate: "2023-12-19T21:11:08.119Z",
            shipmentVariants: [{
                quantity: 1,
                variant: "65698ded25d03cf922c80f93",
            }],
        }],
    }],
}

Enumeration Values

This section provides enumeration values linked to different statuses. These encompass order status, financial status, fulfillment status, and fulfillment method types.

order.status

Order status represents the current status of the overall order placed in the Spresso storefront. The flow of order status in a lifecycle of an order is illustrated below.

created
on_fulfillment_queue
on_fraud_queue
sent_to_fulfiller
completed
cancelled
error

order.financialStatus

Financial status represents the status of payments associated with the order.

created
pending
deferred
error
authorized
authorization_unsuccessful
no_transaction
submitted_for_settlement
voided
settlement_declined
settled

order.fulfillment.status

Fulfillment Status represents the status of an individual fulfillment.

order_placed
received_by_fulfiller
in_transit
delivered
cancelled

order.fulfillment.fulfillmentMethod

Fulfillment Method defines how an item is fulfilled to a customer.

carrier_delivery
local_delivery
in_store_pickup
electronic
none

Shipping Carrier

Shipping Carrier defines which shipping carrier is used to send a shipment.

Note: Please contact the Spresso team if you are using a carrier that is not listed and we can add support.

ups
fedex
usps