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.Documentation Index
Fetch the complete documentation index at: https://docs.snappy.com/llms.txt
Use this file to discover all available pages before exploring further.
This page focuses on the Triggered Gifting model, where the recipient is notified and selects their own gift. In the Direct Fulfillment 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 |
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
Therecipient 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 |
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 Gift 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 |
Delivery Details
The top-leveldeliveryDetails 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 |
Orders
Theorders array contains all Orders associated with this Gift, including cancelled ones.
| Field | Type | Description |
|---|---|---|
orders[].id | string | Unique identifier for the Order |
orders[].status | string | Current status of the Order (e.g. active, 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. See Orders below |
orders[].orderedProducts[].selectedProduct.variantId | string | The Variant ID of the product ordered |
orders[].orderedProducts[].selectedProduct.title | string | The title of the ordered product |
orders[].orderedProducts[].selectedProduct.type | string | The product type (e.g. physicalGift, digital) |
orders[].orderedProducts[].selectedProduct.orderStatus | string | The fulfillment status of this specific product within the order |
orders[].orderedProducts[].deliveryDetails | object | Delivery details specific to this product within this Order. Follows the same structure as the top-level deliveryDetails object |
Customization
Thecustomization 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 and other core gift settings |
customization.recipientNotifications | object | Notification channels (mail, sms) 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 |
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 thestatus 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 therecipients array — each will generate its own Gift object with its own unique link and key.
The claim link is single-use and recipient-specific
Thelink 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 becomesexpired and the claim link is permanently deactivated.
Updating Gifts
As long as the gift is not claimed (meaning its status isunopened, 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 uniquekey 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. UseestimatedCost 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:campaignId— the Campaign to send underrecipients— list of recipients including their details and a uniquekeyper recipient
- Gift Customization overrides — any settings provided here will override the Campaign defaults for this specific batch of gifts only
unopened and a link for each recipient.
Retrieve Gifts Retrieve a list of gifts based on your specified criteria:
- 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:
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:
variantId— the specific Variant to ordershippingAddress— 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:
- 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.