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
Ordered Products
Delivery Details
Order Statuses
Delivery Statuses
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 byorderId.
Variants are required - not Products
When placing an order, you must always specify thevariantId, 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 theorder-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-leveldeliveryDetails 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 callingPOST /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 Orderstatus 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.variantId- the specific product Variant to orderrecipient- the order recipient’s contact details and shipping address
- 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/giftsand immediately claims it on the recipient’s behalf, placing the Order in a single flow inside your UI.
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.