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.

JSON

{
    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