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

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

> Programmatically create, retrieve, update, and expire gifts. Magic-link claims, demo gifts, and webhook-triggered creation.

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.

> [!TIP]
>
> Want to understand how **Gifts** fit into the bigger picture? Check out the [Core Concepts & Data Models](https://docs.snappy.com/pages/snappy-core-concepts-and-data-models.md) page.

> [!NOTE]
>
> 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](https://docs.snappy.com/modules/api/v2/orders/overview.md) 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 |

> [!TIP]
>
> Use Webhooks to track Gift status changes in real time rather than polling. See [Webhook Event Types](https://docs.snappy.com/pages/webhook-event-types.md).

***

## 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](#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](https://docs.snappy.com/pages/duplicate-gifts-detection.md) |

> [!NOTE]
>
> Recipient fields may be masked depending on the permissions of your API key. See [Authentication & Security](https://docs.snappy.com/pages/authentication-and-security.md#data-privacy-pii-masking) 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 |

> [!TIP]
>
> `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](#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 |

> [!TIP]
>
> 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](https://docs.snappy.com/modules/api/v2/orders/overview.md) for the full Order detail.

***

### Orders

The `orders` array contains all Orders associated with this Gift, including cancelled ones. See [Orders API (V2)](https://docs.snappy.com/modules/api/v2/orders/overview.md) 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 |

> [!TIP]
>
> For a full explanation of Gift Customization and its inheritance model, see [Core Concepts & Data Models → Gift Customization](https://docs.snappy.com/pages/snappy-core-concepts-and-data-models.md).

***

### 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 |

> [!TIP]
>
> To be notified when a recipient submits a thank you note, listen for the `thank-you-note-created` webhook event. See [Webhook Event Types](https://docs.snappy.com/pages/webhook-event-types.md).

***

## 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:

```text theme={null} theme={null}
POST /v2/gifts
```

**Retrieve Gifts**

```text theme={null} theme={null}
GET /v2/gifts
```

**Retrieve a Gift by ID**

```text theme={null} theme={null}
GET /v2/gifts/{giftId}
```

**Update Gift by ID**

```text theme={null} theme={null}
PATCH /v2/gifts/{giftId}
```

**Expire a Gift**

```text theme={null} theme={null}
POST /v2/gifts/{giftId}/expire
```

**Create a Demo Gift**

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

```text theme={null} theme={null}
POST /v2/gifts/demo
```

***

> [!NOTE]
>
> **Claim a Gift** and **Cancel an Order on a Gift** are documented under the [Orders API (V2)](https://docs.snappy.com/modules/api/v2/orders/overview.md) since they sit on the Order side of the lifecycle. Both use `/v2/gifts/{giftId}/claim` and `/v2/gifts/{giftId}/cancel` paths respectively.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.