> ## 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: 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                                                                                               |
| `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](/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 [Orders](#orders) below for the full Order history.
</Tip>

***

### Orders

The `orders` 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](#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 |

<Tip>
  For full Order object documentation, see [Orders](#orders).
</Tip>

***

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

<Tip>
  For a full explanation of Gift Customization and its inheritance model, see [Snappy's Core Concepts & Data Models → Gift Customization](/pages/snappy-core-concepts-and-data-models).
</Tip>

<Tip>
  For a concrete example of how Gift-level overrides work in practice, see [Core Concepts & Data Model → Inheritance & Overrides](/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. See [Customization](#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:

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

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.

<Tip>
  See [Duplicate Gift Detection](/pages/duplicate-gifts-detection) for details on the `key` field.
</Tip>

***

**Retrieve Gifts**

Retrieve a list of gifts based on your specified criteria:

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

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:

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

***

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

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

<Note>
  Changes will apply only to gifts that were not yet claimed.
</Note>

***

**Cancel an Order on a Gift** Cancel the order associated with a claimed gift, before it has been processed or shipped:

```http theme={null}
POST /gifts/{giftId}/cancel
```

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:

```text theme={null}
POST /gifts/{giftId}/claim
```

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:

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

***

**Create a Demo Gift**

Create a non-claimable demo gift to preview and test the full recipient experience without incurring any costs:

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

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

<Note>
  This endpoint is not yet available. It is documented here for planning purposes.
</Note>

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.

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

Common use cases include customer onboarding rewards, loyalty milestones, referral bonuses, and subscription renewals.