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. → 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, including Express.Billing Methods can currently be defined and managed through the Snappy Dashboard.
The Catalog
Snappy maintains two parallel catalogs:- Marketplace catalog - curated gifts from third-party brands (physical items, digital cards, donations)
- Swag catalog - branded merchandise templates that you customize (t-shirts, mugs, notebooks, etc.)
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 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.
Digital Card
A Digital Card is a type of marketplace product — gift cards, prepaid cards, and similar card-based rewards. Digital card variants live in a dedicated catalog (GET /v3/products?filter[catalog]=digitalCards) and are ordered through the same POST /v3/orders endpoint as physical products, with a lighter address requirement (only countryCode needed since delivery is by email).
When an order is placed for a digital card variant, Snappy automatically creates a Digital Card entity that captures the card-specific details: the redemption URL, authentication method, face value, recipient, and brand. The Order records the transaction amount charged to the billing method; the Digital Card records the face value (amount) — the denomination loaded onto the card. These two figures may differ due to discounts, promotions, or Snappy fees.
Digital cards are not created directly. The digital card entity is created as part of the order flow and retrieved via the Digital Cards API.
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/swag/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.
Ordering
Order
An Order represents a fulfillment request — it is the primary integration object for Embedded Marketplace. It is created either:- Directly by your system using the V3
POST /ordersendpoint, passing the selected variant ID and recipient details in a single idempotent call (Embedded Marketplace model). - Automatically by Snappy once a recipient selects their item and enters their shipping address in the Snappy Recipient Experience (Triggered Gifting model) — downstream of the Gift.
- Line items - what was ordered (variant, quantity, title), including the transaction amount charged to the billing method
- Fulfillments - shipments with carrier, tracking number, tracking URL, and status (
confirmed,processing,in_transit,out_for_delivery,delivered) - Shipping address - for physical variants (
shippingRequired: true), the full address is required. For digital variants (shippingRequired: false), onlycountryCodeis required — delivery is by email. tags- caller-supplied labels for grouping orders in reportsmetadata- 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)
Recipient
A Recipient is a person in your Snappy contact list. Once created, they can be referenced across multiple order or gift sends without re-submitting their details each time. Each Recipient can carry anexternalId - 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.
→ See the full schema in Recipients Overview.
Triggered Gifting
The objects in this section are specific to the Triggered Gifting integration model — where Snappy notifies the recipient and manages the selection and fulfillment flow on your behalf. If you are using the Embedded Marketplace model (POST /v3/orders directly), you don’t need these objects.
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. Snappy auto-selects or auto-creates a Campaign for Embedded Marketplace orders when campaignId is omitted.Gift
A Gift represents the entire gifting experience for a single recipient within a Campaign - from creation through to final delivery. You create it, Snappy notifies the recipient, they claim it, and an Order is generated downstream. The Gift goes through the following lifecycle:
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.
→ See the full schema in Gifts Overview.
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 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.Inheritance & Overrides
Gift Customization follows a top-down inheritance model: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.