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

# Core Concepts & Data Models

> How Companies, Accounts, Campaigns, Gifts, Orders, Recipients, and the marketplace and swag catalogs fit together in the Snappy platform.

Before diving into individual API endpoints, it helps to understand how Snappy's core objects relate to one another. Most API calls either create one of these objects or retrieve its current state - so a clear mental model will save you time when designing your integration.

## Account Structure

### Company

Your top-level account in Snappy. It holds your API keys, global configuration, and your recipient list. All accounts, campaigns, and gifts are ultimately scoped to a Company.

### Account

An Account lives within a Company and lets you separate and organize gifting activity for different teams, departments, or budget owners - each with its own campaigns and billing method.

<Tip>
  If your organization has multiple departments sending gifts independently, each should operate through its own Account.
</Tip>

→ See the full schema in [Accounts Overview](/modules/api/v3/accounts/overview).

### Billing Method

A Billing Method is the financial funding source used to pay for gifts and associated fees. It must be specified when creating a campaign and is verified when sending a gift - it must have sufficient funds or credit at the time of the request, otherwise the gift will not be processed.

Billing Methods are set at the **Account** level. One Billing Method per Account can be set as the default. This default is applied automatically to any Campaign created via the API. Campaigns created through the Dashboard allow you to select a Billing Method explicitly at the time of creation.

Snappy supports several billing method types. Note that **credit card (EXP) cannot currently be used to send gifts via the API**.

<Note>
  Billing Methods can currently be defined and managed through the Snappy Dashboard.
</Note>

***

## The Gift Pipeline

### Campaign

A Campaign is an **organizational object** for configuring and sending gifts. It represents a single gifting activity or occasion and acts as a template for all settings that apply to it - including the selected Collection or Product, budget, branding, and notification messages.

Think of it as: a reusable send configuration. Campaigns can be created via the Dashboard or directly through the API. When created via the API, the Account's default Billing Method is applied automatically.

<Note>
  For **Triggered Gifting** (`POST /gifts`), a Campaign ID is required. For **Embedded Marketplace** (`POST /orders`), Snappy auto-selects or auto-creates a Campaign based on the supplied `fundingSourceId` when `campaignId` is omitted.
</Note>

→ See the full schema in [Campaigns Overview](/modules/api/v2/campaigns/overview).

### Gift

A Gift represents the entire gifting experience for a single recipient within a Campaign - from creation through to final delivery. The Gift is the **primary integration object for Triggered Gifting**: you create it, Snappy notifies the recipient, they claim it, and an Order is generated downstream.

The Gift goes through the following lifecycle:

| Stage                | What happens                                                                  |
| :------------------- | :---------------------------------------------------------------------------- |
| **Creation**         | Gift is initiated and linked to a recipient and Campaign                      |
| **Notification**     | Recipient is notified via email or other channels                             |
| **Selection**        | Recipient chooses their item and variation, 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                     |

Once the Order is generated, its delivery progress is reflected back in the Gift's status - webhook events like `gift-delivery-status-changed` cover the full lifecycle through to `delivered`, so you can continue tracking via the Gift you originally created.

<Tip>
  Use Webhooks to track Gift status changes in real time rather than polling.
</Tip>

→ See the full schema in [Gifts Overview](/modules/api/v2/gifts/overview).

### Order

An Order represents the physical fulfillment event.

* For **Embedded Marketplace** an Order is the **primary integration object**.
* For **Triggered Gifting** the Order is the point at which a gift becomes a shipment.

The Order is the **primary integration object for Embedded Marketplace**: you create it via a single call to `POST /orders` with the recipient and variant details.

It is created either:

* **Automatically** by Snappy once a recipient selects their item and variant and enters their shipping address in the Snappy Recipient Experience (**Triggered Gifting model**) - downstream of the Gift.
* **Directly** by your system using the V3 `POST /orders` endpoint, passing the selected variant ID and recipient details in a single idempotent call (**Embedded Marketplace model**).

Each Order carries:

* **Line items** - what was ordered (variant, quantity, title)
* **Fulfillments** - shipments with carrier, tracking number, tracking URL, and status (`confirmed`, `processing`, `in_transit`, `out_for_delivery`, `delivered`)
* **`tags`** - caller-supplied labels for grouping orders in reports
* **`metadata`** - key-value passthrough for caller data (for example, your internal order ID or campaign reference)
* **`idempotencyKey`** - caller-supplied stable key that prevents duplicate orders on replay (Embedded Marketplace only)

Orders can be retrieved, listed, and cancelled programmatically via the [V3 Orders API](/modules/api/v3/orders/overview).

<Tip>
  Use Webhooks to track fulfillment and delivery status in real time rather than polling.
</Tip>

→ See the full schema in [Orders Overview](/modules/api/v3/orders/overview).

### Recipient

A Recipient is a person in your Snappy contact list. Once created, they can be referenced across multiple gift sends without re-submitting their details each time.

Each Recipient can carry an **`externalId`** - your own identifier for the same person in your CRM, HRIS, or other system. Snappy stores and returns it on every gift and order, so you can join Snappy data back to your records without maintaining a separate mapping.

<Tip>
  For one-off sends, you can pass contact details inline when creating a Gift. However, for recurring use cases - employee anniversaries, loyalty rewards - managing Recipients via the API keeps your integration clean and avoids duplicate contacts.
</Tip>

→ See the full schema in [Recipients Overview](/modules/api/v2/recipients/overview).

***

## The Gift Catalog

Snappy maintains **two parallel catalogs**:

* **Marketplace catalog** - curated gifts from third-party brands (physical items, digital items, gift cards, donations)
* **Swag catalog** - branded merchandise templates that you customize (t-shirts, mugs, notebooks, etc.)

Across both catalogs, the orderable unit is always the **variant** - never the product or base product.

### **Collection**

A Collection is a curated catalog of marketplace items tailored to a specific theme, budget range, and audience (e.g. "Wellness Gifts Under \$50"). Assign a Collection to a Campaign if you want the recipient to select their preferred item.

→ See the full schema in [Collections Overview](/modules/api/v3/collections/overview).

### **Product**

A Product is a single specific marketplace item - a curated gift, digital item, gift card, or donation. Assign a specific Product to a Campaign when you have a specific item in mind. If that Product has variants, the recipient will need to select the specific one (size, color, etc.).

→ See the full schema in [Products & Variants Overview](/modules/api/v3/products/overview).

### **Product Variant**

Many Products come in multiple variations - for example, a hoodie in different sizes and colors. Each variation is represented as a distinct **Variant**.

<Note>
  When placing a marketplace Order you must specify the Variant ID, not the Product ID.
</Note>

→ See the full schema in [Products & Variants Overview](/modules/api/v3/products/overview).

### **Swag Base Product**

A Base Product is a **swag template** - an unbranded item from which customized swag is derived (e.g. "standard cotton t-shirt", "ceramic mug"). Base Products are the swag-catalog counterpart to standard Products and are browsed via the V3 `/v3/base-products` endpoints.

→ See the full schema in the [Swag](/modules/api/v3/base-products/overview) page.

### **Swag Base Variant**

A Base Variant is a specific orderable version of a Base Product (e.g. "standard cotton t-shirt, Medium, Navy"). Base Variants are the swag-catalog counterpart to standard Variants.

<Note>
  When placing a swag Order you must specify the Base Variant ID, not the Base Product ID.
</Note>

→ See the full schema in the [Swag](/modules/api/v3/base-products/overview) page.

<Tip>
  **Where do Collections, Products, and Base Products come from?**

  * **Collections** can be curated in the Snappy Dashboard, letting you assemble themed gift sets from Snappy's catalog.
  * **Products** are available from Snappy's curated marketplace catalog.
  * **Base Products** are swag templates browsable via the V3 `/v3/base-products` endpoints. For custom-branded swag setup (logos, designs, mockups), contact your Snappy account manager.
</Tip>

***

## Gift Customization

Gift Customization is not a standalone entity you create independently - it is a **configuration layer** that controls how a gift looks and behaves for the recipient. It is unique in that it can be defined at multiple levels of your account hierarchy and is **inherited downward**, with each level able to override the one above it.

### The Three Configuration Areas

#### **Gift Properties**

The core characteristics of the gift: type (Collection or specific Product), budget, expiration period, and similar settings.

#### **Notification Policy**

Controls how and when recipients are notified - through which channels, with what content, and at what timing.

#### **Recipient Experience**

Defines the interactive journey recipients go through when claiming their gift: the unwrapping animation, greeting message, and address collection flow.

<Tip>
  You can explore recipient experience options and generate an API-ready payload at [https://login.snappy.com/api/gift-customization](https://login.snappy.com/api/gift-customization).
</Tip>

### Inheritance & Overrides

Gift Customization follows a top-down inheritance model. Defaults set at a higher level flow down automatically, but can be overridden at any level below:

```text theme={null}
Company defaults → Account defaults → Campaign settings → Individual Gift
```

**Example:** Your Account has a default gift expiration of 30 days. You create a Campaign that overrides this to 14 days. When creating an individual Gift, you can override it again - for example, to give a high-value recipient more time:

```json theme={null}
{
  "campaignId": "cmp_12345",
  "recipients": [
    {
      "firstname": "Jane",
      "lastname": "Doe",
      "email": "jane@example.com",
      "key": "jane-vip-2026"
    }
  ],
  "customization": {
    "giftProperties": {
      "expiration": {
        "type": "daysFromSend",
        "numberOfDays": 60
      }
    }
  }
}
```

In this example, even though the Campaign default is 14 days, this specific Gift will expire after 60 days. The Campaign default is not affected - all other gifts created under this Campaign will still use the 14-day expiration.

<Note>
  Overrides at the Gift level apply only to **that specific Gift**. They do not modify the Campaign, Account, or Company defaults.
</Note>

<Note>
  Via the API, Gift Customization can only be set at the **Campaign level and below**. Company and Account level defaults must be configured through the Snappy Dashboard.
</Note>

***

## Quick Reference

| Entity                      | Lives inside                        | Created via                        | Notes                                                                                                                                      |
| :-------------------------- | :---------------------------------- | :--------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| Company                     | -                                   | Snappy onboarding                  | Root of everything                                                                                                                         |
| Account                     | Company                             | Dashboard or API                   | Organizes campaigns by team or department                                                                                                  |
| Billing Method              | Account                             | Dashboard                          | Must be funded; debited on gift creation. Referenced in V3 APIs as `fundingSourceId`.                                                      |
| Campaign                    | Account                             | Dashboard or API                   | Inherits the Account's default Billing Method when created via API. Required for Triggered Gifting; auto-managed for Embedded Marketplace. |
| Collection                  | Account                             | Snappy catalog or Dashboard        | Recipient chooses from it                                                                                                                  |
| Product / Variant           | Account                             | Snappy catalog or Dashboard        | Marketplace catalog; Variant required for marketplace orders                                                                               |
| Base Product / Base Variant | Account                             | Snappy catalog                     | Swag catalog (templates); Base Variant required for swag orders                                                                            |
| Recipient                   | Company                             | API or Dashboard                   | Can be passed inline for one-off sends; can carry an `externalId`                                                                          |
| Gift                        | Campaign                            | API or Dashboard                   | **Primary integration object for Triggered Gifting**; one per recipient per send                                                           |
| Order                       | Gift                                | Automatically or direct API call   | **Primary integration object for Embedded Marketplace**; created on recipient selection (Triggered) or via single-call placeOrder (DF)     |
| Gift Customization          | Company / Account / Campaign / Gift | Dashboard or API (Campaign & Gift) | Inherited and overridable at each level                                                                                                    |