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
Ordered Products
Delivery Details
Order Statuses
Delivery Statuses
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 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
If an Order is cancelled, a new one can be placed against the same Gift. 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 /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 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.
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.
- variantId - the specific product Variant to order
- recipient - the order recipient and their shipping address
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.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: