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 system triggers the gift, Snappy handles the experience, the recipient chooses what they want.” Use this recipe when you want to:
  • Notify a recipient and let them select their own gift from a Collection.
  • Send a specific gift but don’t have the recipient’s shipping address upfront.
Common use cases include:
  • Employee Recognition & Retention.
  • Sales Lead Nurturing.
  • Client Onboarding & Appreciation.

​
Overview

In this model, your system is responsible for creating the Gift. Snappy then takes over — notifying the recipient, presenting the gift experience, collecting their address, and fulfilling the order. Your integration only needs to handle two things:
  1. Creating the gift
  2. 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. Your Campaign should already have a Collection or Product assigned, along with your preferred Gift Customization settings. 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: Create the Gift

Call POST /gifts with your Campaign ID and recipient details. This is the core action that initiates the entire gifting flow. 
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);
  console.log('Claim link:', gift.link);
  return gift;
}

// Example usage
createGift('cmp_12345', {
  firstname: 'Jane',
  lastname: 'Doe',
  email: 'jane@example.com',
  key: 'jane-doe-anniversary-2025'
});
Snappy creates a Gift object and returns it in the response, including a unique link — the recipient’s personal claim URL. If your Campaign’s Notification Policy is configured to notify automatically, Snappy sends the recipient an email immediately. If not, you can use the link from the response to trigger your own notification.
Include a key for every recipient to prevent duplicate gifts. See Duplicate Gift Detection for details.

​
Step 3: Recipient Claims the Gift

This step happens entirely within Snappy’s recipient experience — no API calls required from your side.
The recipient opens their claim link, browses the Collection (or sees their assigned Product), selects a variant, and enters their shipping address. Snappy automatically generates an Order once the selection is complete.

​
Step 4: Track Status via Webhooks

Rather than polling the API, listen for Webhook events to track the gift as it moves through its lifecycle. Key events to handle:
EventMeaning
gift-notification-initial-sentThe gift notification has been sent to the recipient
gift-status-changed (status: opened)Recipient viewed the available gift options
gift-status-changed (status: claimed)Recipient selected their gift and provided their details
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;

  switch (webhookData.eventType) {
    case 'gift-notification-initial-sent':
      console.log(`Notification sent for gift: ${eventData.giftId}`);
      break;
    case 'gift-status-changed':
      console.log(`Gift ${eventData.giftId} status: ${eventData.status}`);
      if (eventData.status === 'claimed') {
        console.log('Gift claimed — order will be generated shortly');
      }
      if (eventData.status === 'expired') {
        console.log('Gift expired — consider follow-up action');
      }
      break;
    case 'gift-delivery-status-changed':
      console.log(`Delivery update for gift ${eventData.giftId}: ${eventData.deliveryStatus}`);
      if (eventData.deliveryStatus === 'delivered') {
        console.log('Gift delivered successfully');
      }
      break;
  }

  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. POST /gifts → create the gift, get back the claim link.
  3. [Snappy notifies recipient] → [Recipient selects gift] → Snappy generates the Order automatically.
  4. Webhooks → track gift and order status updates.
Last modified on April 30, 2026