Gifts API (V2): Create, Track, and Expire Gifts

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.

Want to understand how Gifts fit into the bigger picture? Check out the Core Concepts & Data Models page.

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

Recipient fields may be masked depending on the permissions of your API key. See Authentication & Security for details.

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

For a full explanation of Gift Customization and its inheritance model, see Core Concepts & Data Models → Gift Customization.

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:

POST /v2/gifts

Retrieve Gifts

GET /v2/gifts

Retrieve a Gift by ID

GET /v2/gifts/{giftId}

Update Gift by ID

PATCH /v2/gifts/{giftId}

Expire a Gift

POST /v2/gifts/{giftId}/expire

Create a Demo Gift A non-claimable gift used to preview the recipient experience without incurring any cost:

POST /v2/gifts/demo

Create Gifts by Webhook A simplified webhook-style endpoint designed for integration with third-party systems (CRMs, marketing automation platforms). Authentication is via API key as a query parameter:

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.

​The Gift Lifecycle

​The Gift Object

​Core Fields

​Recipient

​Cost

​Delivery Details

​Orders

​Customization

​Thank You Note

​Gift Statuses

​Delivery Statuses

​Key Concepts & Business Rules

​Every Gift must belong to a Campaign

​The Gift is the Triggered Gifting experience

​One Gift per recipient per send

​The claim link is single-use and recipient-specific

​Gift Customization overrides

​Expiration

​Updating Gifts

​Duplicate detection

​Estimated vs. Final Cost

​How to Work with Gifts

The Gift Lifecycle

The Gift Object

Core Fields

Recipient

Cost

Delivery Details

Orders

Customization

Thank You Note

Gift Statuses

Delivery Statuses

Key Concepts & Business Rules

Every Gift must belong to a Campaign

The Gift is the Triggered Gifting experience

One Gift per recipient per send

The claim link is single-use and recipient-specific

Gift Customization overrides

Expiration

Updating Gifts

Duplicate detection

Estimated vs. Final Cost

How to Work with Gifts