An Order represents the physical fulfillment event. It is created directly by your system in the Embedded Marketplace model, or automatically by Snappy when a recipient claims their gift in the Triggered Gifting model.
This page focuses on the Embedded Marketplace model, where your system places orders directly. If you’re working with the Triggered Gifting model, Orders are created automatically when recipients claim their gift - see Gifts for details The Order Object
The Order object is returned as part of the Gift object. A Gift can hold multiple Orders - for example if an original Order was cancelled and a new one was placed. The active Order’s delivery details are always surfaced at the top level of the Gift object for convenience.
Core Fields
| Field | Type | Description |
|---|
id | string | Unique identifier for the Order |
status | string | Current status of the Order. See Order Statuses below |
orderRecipient | object | The recipient details used for this specific Order. Contains firstName, lastName, and country |
orderedProducts | array | The products included in this Order. See Ordered Products below |
Ordered Products
| Field | Type | Description |
|---|
orderedProducts[].selectedProduct.variantId | string | The Variant ID of the product ordered |
orderedProducts[].selectedProduct.title | string | The title of the ordered product |
orderedProducts[].selectedProduct.type | string | The product type (e.g. physicalGift, digital) |
orderedProducts[].selectedProduct.orderStatus | string | The fulfillment status of this specific product within the Order |
orderedProducts[].deliveryDetails | object | Delivery details for this product. See Delivery Details below |
Delivery Details
| Field | Type | Description |
|---|
deliveryDetails.status | string | Current delivery status. See Delivery Statuses below |
deliveryDetails.carrier | string | The shipping carrier handling the delivery |
deliveryDetails.trackingNumber | string | The carrier’s tracking number |
deliveryDetails.trackingLink | string | A direct link to the carrier’s tracking page |
deliveryDetails.deliveryDates.outForDelivery | string | ISO 8601 timestamp of when the item was marked out for delivery |
deliveryDetails.deliveryDates.estimated | string | ISO 8601 timestamp of the estimated delivery date |
deliveryDetails.deliveryDates.deliveredAt | string | ISO 8601 timestamp of when the item was delivered |
Order Statuses
| Status | Description |
|---|
active | The Order is active and being processed |
cancelled | The Order has been cancelled |
Delivery Statuses
| Status | Description |
|---|
orderReceived | The fulfillment request has been received |
processing | The item is being prepared for shipment |
inTransit | The item has been picked up by the carrier |
outForDelivery | The item is expected to be delivered today |
delivered | The item has reached its final destination |
Use Webhooks to track delivery status changes in real time rather than polling. See Webhooks & Events.
Key Concepts & Business Rules
An Order is a sub-entity of a Gift
Even in the Embedded Marketplace model where your system places the order directly, a Gift object is created internally. The Order lives within that Gift and cannot exist independently.
Variants are required - not Products
When placing an order, you must always specify the variantId, not the productId. Every Product has at least one Variant, even if it has no variations. See Products & Variants.
Orders can only be cancelled before processing
Once an Order has been picked up by the fulfillment partner and is in transit, it can no longer be cancelled. Use the order-out-of-stock and order-canceled webhook events to handle edge cases proactively.
A Gift can have multiple Orders
If an Order is cancelled, a new one can be placed against the same Gift. The Gift’s top-level deliveryDetails always reflects the active Order. The orders array on the Gift object contains the full Order history including cancelled ones.
Address validation reduces fulfillment failures
Invalid or incomplete shipping addresses are a common cause of fulfillment failures. We recommend calling POST /orders/addresses/validate before placing any order, especially when addresses are entered by end users in your platform UI.
Billing is triggered at Order creation
The Billing Method is debited when an Order is successfully placed. If the Billing Method has insufficient funds at the time of the request, the order will not be processed.
Order Status vs. Delivery Status
The top-level Order status indicates the validity of the transaction active vs. cancelled). The actual shipping progress is tracked inside the deliveryDetails.status of each ordered product.
How to Work with Orders
Place Order (Embedded Marketplace)
Placing an order in the Embedded Marketplace model requires two sequential API calls:
- Create the Gift - Call POST /gifts with the Campaign ID and recipient details. At this stage you only need to provide the Campaign and recipient information - no variant or shipping address is required yet.
Required fields:
companyId - the Company placing the ordercampaignId - the Campaign under which the gift and order will be createdrecipients - the recipient’s details including name and email
- Claim the Gift - Call POST /gifts//claim with the Gift ID returned in the previous step, along with the selected variant ID and the recipient’s shipping address. This finalizes the Gift and places the Order immediately.
POST /gifts/{giftId}/claim
- variantId - the specific product Variant to order
- recipient - the order recipient and their shipping address
Use the giftid from Step 1 to track order delivery status via GET /gifts/ or Webhooks.
A dedicated POST /orders endpoint is coming soon, which will allow you to create a gift and place an order in a single API call. See Embedded Marketplace Recipe for details. POST /gifts/{giftId}/cancel
Orders can only be cancelled before they have been processed or shipped. Once a shipment is in transit, cancellation is no longer possible.
POST /orders/addresses/validate
We recommend calling this endpoint as part of your order placement flow, especially when addresses are entered by end users in your platform UI.
Autocomplete Order Address
Retrieve address suggestions based on a partial input string. Useful for building address input fields in your platform UI that help users enter accurate shipping addresses:
GET /orders/addresses/autocomplete
