Core Concepts & Data Models

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.

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

→ See the full schema in 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.

Billing Methods can currently be defined and managed through the Snappy Dashboard.

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.

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.

→ See the full schema in 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.

Use Webhooks to track Gift status changes in real time rather than polling.

→ See the full schema in 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.

Use Webhooks to track fulfillment and delivery status in real time rather than polling.

→ See the full schema in 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.

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.

→ See the full schema in 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.

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.

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.

When placing a marketplace Order you must specify the Variant ID, not the Product ID.

→ See the full schema in Products & Variants 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 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.

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

→ See the full schema in the Swag page.

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.

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.

You can explore recipient experience options and generate an API-ready payload at https://login.snappy.com/api/gift-customization.

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:

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:

{
  "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.

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

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.

Entity Relationship Diagram

A Campaign is configured with either a Collection or a specific Product - not both.

An Order specifies either a Variant (marketplace catalog) or a Base Variant (swag catalog), depending on what’s being ordered.

Embedded Marketplace auto-management: Every Gift is associated with a Campaign, and every Order is associated with a Gift in the data model. For Embedded Marketplace via POST /orders, both relationships are auto-managed by Snappy - the integrator interacts with the Order directly, without needing to specify a Campaign or manage a Gift.

Gift Customization follows a top-down inheritance model - defaults defined at the Company level flow down through Account and Campaign to the individual Gift, with each level able to override the one above it.

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

​Account Structure

​Company

​Account

​Billing Method

​The Gift Pipeline

​Campaign

​Gift

​Order

​Recipient

​The Gift Catalog

​Collection

​Product

​Product Variant

​Swag Base Product

​Swag Base Variant

​Gift Customization

​The Three Configuration Areas

​Gift Properties

​Notification Policy

​Recipient Experience

​Inheritance & Overrides

​Entity Relationship Diagram

​Quick Reference

Account Structure

Company

Account

Billing Method

The Gift Pipeline

Campaign

Gift

Order

Recipient

The Gift Catalog

Collection

Product

Product Variant

Swag Base Product

Swag Base Variant

Gift Customization

The Three Configuration Areas

Gift Properties

Notification Policy

Recipient Experience

Inheritance & Overrides

Entity Relationship Diagram

Quick Reference