An Order represents the physical fulfillment event. In V2, Orders are not first-class API resources - they’re created as a side effect of the Gifts flow. An Order can be created either directly by your system in the Direct Fulfillment model (via the two-step gift-claim flow), or automatically by Snappy when a recipient claims their gift in the Triggered Gifting model.
Looking for the V3 endpoints? See Orders (V3). V3 introduces Orders as first-class resources with a dedicated POST /v3/orders endpoint that replaces the V2 two-step flow - and adds direct order retrieval, listing, and cancellation by orderId. Both V2 and V3 are supported in parallel. This page focuses on the Direct Fulfillment 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
In V2, 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 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 Webhook Event Types.
Key Concepts & Business Rules
An Order is a sub-entity of a Gift
In V2, the Order lives within a Gift - even when your system places the order directly via the Direct Fulfillment flow, a Gift object is created internally and the Order is attached to it. V3 changes this: Orders are first-class resources you can retrieve, list, and cancel directly by orderId.
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 but only one is active
A Gift maintains a history of all Orders placed against it. If an Order is cancelled, a new one can be placed against the same Gift - but only one Order is active at any time. 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 /v2/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 lifecycle 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 (V2)
Claim a Gift
Claiming a Gift programmatically places an Order on behalf of the recipient. Provide the selected variant and shipping address - Snappy creates the Order, debits the Billing Method, and begins fulfillment.
POST /v2/gifts/{giftId}/claim
variantId - the specific product Variant to orderrecipient - the order recipient’s contact details and shipping address
Common use cases:
- Auto-claim fallback - a Gift sent through Triggered Gifting hasn’t been claimed by the recipient within a defined window. Your system auto-claims with a pre-selected variant and a known shipping address, ensuring the gift still goes out.
- Embedded Marketplace - your platform creates a Gift via
POST /v2/gifts and immediately claims it on the recipient’s behalf, placing the Order in a single flow inside your UI.
Use the giftId to track order delivery status via GET /v2/gifts/{giftId} or Webhooks.
V3 introduces POST /v3/orders as a single-call alternative for placing orders without the Gift-and-claim pattern. If you’re starting a new integration, consider V3 Orders. POST /v2/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 /v2/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.
GET /v2/orders/addresses/autocomplete
