“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:
- Creating the gift
- 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;
}
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'
});
Step 3: Recipient Claims the Gift
This step happens entirely within Snappy’s recipient experience - no API calls required from your side.
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:
| Event | Meaning |
|---|
| gift-notification-initial-sent | The 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'));
Full Flow Summary
- GET /campaigns → retrieve your campaign ID.
- POST /gifts → create the gift, get back the claim link.
- [Snappy notifies recipient] → [Recipient selects gift] → Snappy generates the Order automatically.
- Webhooks → track gift and order status updates.
