Skip to main content

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.

“Your platform displays the catalog and collects the order, Snappy handles the fulfillment.” Use this recipe when you want to embed Snappy’s product catalog inside your own platform and let your users select items directly. Your system handles the UI, collects the shipping address, and places the order. Snappy handles fulfillment. Common use cases include:
  • Swag stores
  • Procurement portals
  • Rewards redemption platforms

​
Overview

In this model, your system handles catalog display, product selection, and address collection. Once your user has made their selection, you pass all the required information to Snappy in two sequential API calls and Snappy processes the order immediately. Your integration only needs to handle three things: retrieving products, placing orders, and listening for status updates via Webhooks.

​
Setting Up Your API Client

Before making any API calls, initialize your HTTP client with your API key. This setup is used throughout all steps below. 
const axios = require('axios');

const snappyClient = axios.create({
  baseURL: 'https://api.snappy.com/public-api/v2',
  headers: {
    'X-Api-Key': process.env.SNAPPY_API_KEY,
    'Content-Type': 'application/json'
  }
});
Store your API key as an environment variable — never hardcode it in your source code.

​
Step 1: Identify your Campaign

Every gift is created within a Campaign. Before making any API calls, you need the id of the Campaign you want to send under. If you haven’t created a Campaign yet, you can do so either through the Snappy Dashboard or via the API using POST /campaigns. When created via the API, the Campaign is automatically assigned the Account’s default Billing Method.
Every Campaign requires a default Collection or Product to be configured. In the Direct Fulfillment model, this is not used — you will specify the exact product and variant when placing the order.
Endpoint: GET /campaigns — use this to retrieve your Campaign list and confirm the correct id. 
async function getCampaigns() {
  const response = await snappyClient.get('/campaigns');
  const campaigns = response.data.results;
  console.log('Available campaigns:', campaigns);
  return campaigns;
}
→ For the full list of Campaign configuration options, see the [API Reference].

​
Step 2: Retrieve and Display the Product Catalog

Retrieve the available products and display them in your own platform UI. Call GET /products to return the full product catalog available to your account. Each Product object contains a variants array representing the available options (e.g. size, color). Your UI should present these variants to the user so they can make their selection. The response includes full product details. The fields most relevant to your UI are id, name, and the variants array. For example: 
{
  "id": "prd_12345",
  "name": "Premium Hoodie",
  "variants": [
    { "id": "var_001", "size": "M", "color": "Navy" },
    { "id": "var_002", "size": "L", "color": "Navy" },
    { "id": "var_003", "size": "M", "color": "Black" }
  ]
}
Use Field Projection to optimize performance and reduce payload size. See Request & Response Standards.
→ For the full product object schema, see the API Reference.

​
Step 3: User Selects an Item

This step happens within your platform — no API calls required yet. Your user browses the catalog you’ve displayed, selects their preferred item and variant, and provides their shipping address if you don’t already have it on file. Once you have all three pieces of information — Campaign ID, Variant ID, and shipping address — you’re ready to place the order.
We recommend validating the shipping address before placing the order to reduce fulfillment failures. See Validate Order Address.

​
Step 4: Create the Gift

Call POST /gifts with your Campaign ID and recipient details. This creates the Gift object and returns a giftId which you’ll need in the next step. 
async function createGift(campaignId, recipient) {
  const response = await snappyClient.post('/gifts', {
    campaignId: campaignId,
    recipients: [
      {
        firstname: recipient.firstname,
        lastname: recipient.lastname,
        email: recipient.email,
        key: recipient.key
      }
    ]
  });

  const gift = response.data.results[0];
  console.log('Gift created:', gift.id);
  return gift.id; // Store this — needed for the claim step
}

// Example usage
const giftId = await createGift('cmp_12345', {
  firstname: 'John',
  lastname: 'Smith',
  email: 'john@example.com',
  key: 'john-smith-onboarding-swag'
});
A successful response returns the Gift object including the giftId. Note the giftId — you will need it in the next step.
In this approach the Gift is created without a variant or shipping address. The recipient will not receive a notification — the Claim step immediately completes the order.
Include a unique key for every recipient to prevent duplicate gifts. See Duplicate Detection.

​
Step 5: Claim the Gift

Call POST /gifts//claim with the selected Variant ID and the recipient’s shipping address. This finalizes the Gift and places the Order immediately. 
async function claimGift(giftId, variantId, shippingAddress) {
  const response = await snappyClient.post(`/gifts/{giftId}/claim`, {
    variantId: variantId,
    shippingAddress: shippingAddress
  });

  const order = response.data;
  console.log('Order placed:', order.id);
  console.log('Order status:', order.status);
  return order;
}

// Example usage
claimGift(giftId, 'var_001', {
  line1: '123 Main Street',
  city: 'New York',
  state: 'NY',
  zip: '10001',
  country: 'US'
});

​
Step 6: Track Fulfillment via Webhooks

Listen for Webhook events to track fulfillment progress. Key events to handle:
EventMeaning
gift-delivery-status-changed (status: orderReceived)Order has been placed with the fulfillment partner
gift-delivery-status-changed (status: inTransit)Product has shipped
gift-delivery-status-changed (status: delivered)Product has reached its final destination
const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhooks/snappy', (req, res) => {
  const { webhookData, eventData } = req.body;

  if (webhookData.eventType === 'gift-delivery-status-changed') {
    const { giftId, deliveryStatus } = eventData;
    console.log(`Delivery update for gift ${giftId}: ${deliveryStatus}`);

    switch (deliveryStatus) {
      case 'orderReceived':
        console.log('Order confirmed with fulfillment partner');
        break;
      case 'inTransit':
        console.log('Order shipped');
        break;
      case 'delivered':
        console.log('Order delivered successfully');
        break;
    }
  }

  if (webhookData.eventType === 'order-canceled') {
    console.log(`Order canceled for gift ${eventData.giftId}`);
    console.log('Reason:', eventData.cancelReason);
    // Handle cancellation — notify sender, offer replacement etc.
  }

  if (webhookData.eventType === 'order-out-of-stock') {
    console.log(`Out of stock for gift ${eventData.giftId}`);
    // Handle out of stock — offer alternative variant etc.
  }

  res.status(200).send('OK');
});

app.listen(3000, () => console.log('Webhook listener running on port 3000'));
→ Configure your webhook listener — see Webhooks: Overview & Setup.

​
Full Flow Summary

  1. GET /campaigns → retrieve your campaign ID
  2. GET /products → retrieve catalog to display in your platform
  3. [User selects item, variant, and provides shipping address]
  4. POST /gifts → create the gift, get back the giftId
  5. POST /gifts/claim → claim the gift with variant and shipping address
  6. Webhooks → track order fulfillment and delivery
Last modified on April 30, 2026