Skip to main content
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:
Use Webhooks to track Gift status changes in real time rather than polling. See Webhook Event Types.

​
The Gift Object

​
Core Fields

​
Recipient

The recipient object contains the details of the person this Gift was sent to.
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:
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.
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 Orders below for the full Order history.

​
Orders

The orders array contains all Orders associated with this Gift, including cancelled ones.
For full Order object documentation, see Orders.

​
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.
For a full explanation of Gift Customization and its inheritance model, see Snappy’s Core Concepts & Data Models → Gift Customization.
For a concrete example of how Gift-level overrides work in practice, see Core Concepts & Data Model → Inheritance & Overrides.

​
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.
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

​
Delivery Statuses

​
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 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. See Customization.

​
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. Snappy will notify recipients based on the Campaign’s Notification Policy:
Required fields:
  • campaignId - the Campaign to send under
  • recipients - list of recipients including their details and a unique key per recipient
Optional fields:
  • Gift Customization overrides - any settings provided here will override the Campaign defaults for this specific batch of gifts only
A successful request returns the Gift object with an initial status of unopened and a link for each recipient.
See Duplicate Gift Detection for details on the key field.
Retrieve Gifts Retrieve a list of gifts based on your specified criteria:
Filtering options:
  • Campaign ID
  • Status
  • Notification sending channels (mail, SMS)
Retrieve a Gift by ID Retrieve a specific gift by its ID. Useful for tracking delivery status or retrieving final gift cost:
Update Gift by ID Update the Gift Customization settings of a specific gift that has not yet been claimed. You can update gift properties (e.g. collection, budget), notification settings, and recipient experience settings:
Changes will apply only to gifts that were not yet claimed.
Cancel an Order on a Gift Cancel the order associated with a claimed gift, before it has been processed or shipped:
Cancellation is only possible while the order is still in orderReceived or processing status. Once the item is inTransit, the order can no longer be cancelled.
Claim a Gift Programmatically claim a gift on behalf of a recipient by providing the selected variantId and shippingAddress. This endpoint is intended for use cases where your system needs to place an order without recipient interaction - for example, automatically ordering a default product for gifts that remain unclaimed after a set period:
Required fields:
  • variantId - the specific Variant to order
  • shippingAddress - the delivery address for the order
Expire a Gift Manually expire a gift that has not yet been claimed, preventing the recipient from selecting a product and generating an order:
Create a Demo Gift Create a non-claimable demo gift to preview and test the full recipient experience without incurring any costs:
Key characteristics:
  • Cannot be redeemed for an actual product
  • Free - does not affect your account budget
  • Provides a fully interactive preview of the recipient experience including the unwrapping animation and gift collection browsing
Create Gifts by Webhook (Coming Soon)
This endpoint is not yet available. It is documented here for planning purposes.
A simplified webhook-style endpoint for creating and sending gifts, designed for easy integration with third-party systems such as CRMs and marketing automation platforms. Key features include simple authentication via API key query parameter and a streamlined payload requiring only essential recipient and gift information.
Common use cases include customer onboarding rewards, loyalty milestones, referral bonuses, and subscription renewals.
Last modified on June 18, 2026