> ## 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](/pages/snappy-core-concepts-and-data-models) page.
</Tip>

<Info>
  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](/modules/api/v2/orders/overview) for details.
</Info>

***

## 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](/pages/webhook-event-types).
</Tip>

***

## 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](/pages/duplicate-gifts-detection) |

<Note>
  Recipient fields may be masked depending on the permissions of your API key. See [Authentication & Security](/pages/authentication-and-security#data-privacy-pii-masking) for details.
</Note>

***

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

***

### 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](/modules/api/v2/orders/overview) for the full Order detail.
</Tip>

***

### Orders

The `orders` array contains all Orders associated with this Gift, including cancelled ones. See [Orders API (V2)](/modules/api/v2/orders/overview) 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](/pages/snappy-core-concepts-and-data-models).
</Tip>

***

### 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](/pages/webhook-event-types).
</Tip>

***

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

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

```text theme={null} theme={null}
POST /v2/webhooks/send-gifts
```

***

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