A Gift is the core transactional object in Snappy. It represents the entire gifting experience for a single recipient within a Campaign - from creation through notification, selection, and final delivery.
This page focuses on the Triggered Gifting model, where the recipient is notified and selects their own gift. In the Embedded Marketplace model, a Gift object is still created internally, but the developer primarily interacts with the Order object. See Orders for details.
The Gift Lifecycle
The Gift object moves through the following stages in the Triggered Gifting model:
| Stage | Description |
|---|
| Creation | Gift is initiated and linked to a recipient and Campaign |
| Notification | Recipient is notified via email, SMS, or other channels |
| Selection | Recipient clicks the claim link, opens the Snappy Recipient Experience, browses the Collection, selects a Variant, and enters their shipping address |
| Order Generation | An Order is created based on the selected Variant and shipping address |
| Delivery | The physical product is shipped and tracked to completion |
Use Webhooks to track Gift status changes in real time rather than polling. See Webhook Event Types.
The Gift Object
Core Fields
| Field | Type | Description |
|---|
id | string | Unique identifier for the Gift |
campaignId | string | The ID of the Campaign this Gift was created under |
companyId | string | The ID of the Company this Gift belongs to |
status | string | Current status of the Gift. See Gift Statuses below |
link | string | The recipient’s unique claim URL. Share this link to notify recipients manually, or let Snappy send it automatically based on the Campaign’s Notification Policy |
success | boolean | Indicates whether the Gift was created successfully. Relevant for both single and batch gift creation |
createdAt | string | ISO 8601 timestamp of when the Gift was created |
Recipient
The recipient object contains the details of the person this Gift was sent to.
| Field | Type | Description |
|---|
recipient.firstname | string | Recipient’s first name |
recipient.lastname | string | Recipient’s last name |
recipient.email | string | Recipient’s email address |
recipient.phone | string | Recipient’s phone number (E.164 format) |
recipient.externalId | string | Your internal ID for this recipient, used to map Snappy recipients to records in your own system |
recipient.key | string | The unique idempotency key provided at gift creation. See Duplicate Detection |
Cost
Snappy returns cost information in two fields depending on the Gift’s current stage:
| Field | Type | Description |
|---|
estimatedCost | object | The projected cost at the time of gift creation, before the recipient has selected a product. Contains budget, estimatedFee, estimatedTax, and estimatedTotalCost |
finalCost | object | The actual cost after the recipient has claimed the gift and an Order has been placed. Contains cost, finalFee, finalTax, and totalFinalCost. Populated only after the gift is claimed |
estimatedCost is available immediately after gift creation. finalCost is populated once the recipient claims the gift and an Order is generated.
Delivery Details
The top-level deliveryDetails object represents the delivery status of the active order associated with this Gift.
| 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.outForDeliveryDate | string | ISO 8601 timestamp of when the item was marked out for delivery |
deliveryDetails.deliveredAt | string | ISO 8601 timestamp of when the item was delivered |
A Gift can hold multiple Orders - for example if an original Order was cancelled and a replacement was placed. The top-level deliveryDetails always reflects the active Order. See the Orders API for the full Order detail.
Orders
The orders array contains all Orders associated with this Gift, including cancelled ones. See Orders API (V2) for the full Order schema documentation.
| Field | Type | Description |
|---|
orders[].id | string | Unique identifier for the Order |
orders[].status | string | Current status of the Order (active or cancelled) |
orders[].orderRecipient | object | The recipient details used for this specific Order. Contains firstName, lastName, and country |
orders[].orderedProducts | array | The products included in this Order |
Customization
The customization object on the Gift represents the effective Gift Customization settings applied to this specific Gift - including any overrides made at the Gift level on top of the Campaign defaults.
| Field | Type | Description |
|---|
customization.giftProperties | object | Budget range, expiration, and other core gift settings |
customization.recipientNotifications | object | Notification channels (mail, sms, etc.) and reminder settings |
customization.recipientExperience | object | Visual and interactive settings for the recipient claim experience, including reveal animation, greeting, and post-claim redirect |
Thank You Note
After claiming a gift, recipients have the option to leave a thank you note for the sender. Thank you notes are delivered to the sender by email and are also displayed in the Gratitude Wall in the Snappy Dashboard.
| Field | Type | Description |
|---|
tyn | string | The thank you note left by the recipient after claiming the gift. null if no note has been submitted |
To be notified when a recipient submits a thank you note, listen for the thank-you-note-created webhook event. See Webhook Event Types.
Gift Statuses
| Status | Description |
|---|
unopened | Gift has been sent but the recipient has not clicked the claim link yet |
unwrapped | Recipient has clicked the link but has not yet viewed the gift options |
opened | Recipient has viewed the available gift options |
claimed | Recipient has selected a gift and provided their shipping details |
expired | Gift reached its expiration date without being claimed |
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 |
Key Concepts & Business Rules
Every Gift must belong to a Campaign
A Gift cannot be created without a Campaign. The Campaign provides the configuration context - budget, collection or product, branding, and notification settings - that the Gift inherits.
The Gift is the Triggered Gifting experience
In the Triggered Gifting model, the Gift object represents the full recipient journey from notification through selection to delivery. A Gift is essentially an “intent to send” until the recipient actually claims it. No physical item is reserved, and no final billing occurs until the status changes to claimed and an Order is generated.
One Gift per recipient per send
Each Gift represents the experience for a single recipient. To send to multiple recipients, include multiple entries in the recipients array - each will generate its own Gift object with its own unique link and key.
The claim link is single-use and recipient-specific
The link returned on the Gift object is a unique, personalized URL for that recipient. It should not be shared with other recipients or reused across sends.
Gift Customization overrides
Any customization settings provided at the Gift level override the Campaign defaults for that specific Gift only. The Campaign’s default settings are not affected.
Expiration
Gifts do not remain open indefinitely. They are governed by the expiration settings defined in their parent Campaign. If the window closes before the recipient makes a selection, the gift status becomes expired and the claim link is permanently deactivated.
Updating Gifts
As long as the gift is not claimed (meaning its status is unopened, unwrapped, or opened), you can update its Customization settings or manually expire it. Once a gift has been claimed, its settings are locked.
Duplicate detection
We strongly recommend including a unique key for every recipient in a gift creation request. While not strictly required, this key is permanent and does not expire even if the gift itself expires. Reusing a key will trigger a duplicate detection error, which protects your account from accidental double-billing.
Estimated vs. Final Cost
Because Snappy covers shipping and taxes, the exact cost of a gift isn’t known until the recipient provides their shipping address. Use estimatedCost to check your budget exposure, but rely on finalCost for your actual accounting once the gift is claimed.
How to Work with Gifts
Create Gifts
Create one or more gifts within a Campaign:
Retrieve Gifts
Retrieve a Gift by ID
Update Gift by ID
Expire a Gift
POST /v2/gifts/{giftId}/expire
POST /v2/webhooks/send-gifts
Claim a Gift and Cancel an Order on a Gift are documented under the Orders API (V2) since they sit on the Order side of the lifecycle. Both use /v2/gifts/{giftId}/claim and /v2/gifts/{giftId}/cancel paths respectively. 
