Send Triggered Gifts

The Send Triggered Gifts pattern creates gifts programmatically for a list of recipients — triggered by events like hiring, anniversaries, or milestone completions. Gifts are created in the V2 gifting API and sent to recipients who choose their own product from a curated selection.

Prerequisites

API key with gifts:create scope
At least one Campaign configured in the Snappy Dashboard
The campaignId for the campaign you’re sending under

Create gifts

POST /v2/gifts

Pass a recipients array — each entry creates one gift for one recipient.

The V2 gifting API uses lowercase field names for recipient names: firstname and lastname (not camelCase). This differs from the V3 orders API which uses firstName / lastName.

JavaScript

async function sendGifts(campaignId, recipients) {
  const res = await fetch(`${SNAPPY}/v2/gifts`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      campaignId,
      recipients: recipients.map(r => ({
        firstname: r.firstName,      // lowercase - V2 API
        lastname: r.lastName,        // lowercase - V2 API
        email: r.email,
        key: r.stableId,             // idempotency key - see below
      })),
    }),
  });
  return res.json();
}

Python

def send_gifts(campaign_id, recipients):
    payload = {
        "campaignId": campaign_id,
        "recipients": [
            {
                "firstname": r["first_name"],   # lowercase - V2 API
                "lastname": r["last_name"],      # lowercase - V2 API
                "email": r["email"],
                "key": r["stable_id"],           # idempotency key - see below
            }
            for r in recipients
        ],
    }
    res = requests.post(f"{SNAPPY}/v2/gifts", headers=headers, json=payload)
    return res.json()

Chunking for large lists

The V2 gifts endpoint has a maximum recipients per request. For large sends, split into chunks of 100 and send sequentially (or with bounded concurrency):

JavaScript

const CHUNK_SIZE = 100;

async function sendGiftsInBulk(campaignId, allRecipients) {
  const results = [];
  for (let i = 0; i < allRecipients.length; i += CHUNK_SIZE) {
    const chunk = allRecipients.slice(i, i + CHUNK_SIZE);
    const result = await sendGifts(campaignId, chunk);
    results.push(result);
  }
  return results;
}

Python

CHUNK_SIZE = 100

def send_gifts_in_bulk(campaign_id, all_recipients):
    results = []
    for i in range(0, len(all_recipients), CHUNK_SIZE):
        chunk = all_recipients[i:i + CHUNK_SIZE]
        result = send_gifts(campaign_id, chunk)
        results.append(result)
    return results

Idempotency

Each recipient entry accepts a key field — a stable, permanent identifier for that recipient in the context of this send. Snappy uses this to deduplicate: sending the same key twice does not create a second gift. Derive key from stable identifiers, not from random values or timestamps:

JavaScript

// Good: stable per recipient per campaign
const key = `campaign-${campaignId}-user-${userId}`;

// Bad: changes on retry, defeats idempotency
const key = `${Date.now()}-${Math.random()}`;

Keys must be unique within a campaign. A good pattern: {campaignId}-{userId} or {campaignId}-{employeeId}.

Partial failure handling

The API may succeed for some recipients and fail for others in the same request. The response includes per-recipient status:

Outcome	Field	Action
Success	`gifts[].id` present	Record gift ID for tracking
Validation error	`errors[].recipient`	Fix the data and re-send that recipient
Duplicate key	`errors[].code === "duplicate_key"`	Already sent — no action needed
Campaign not found	Top-level `404`	Check `campaignId`

Always inspect errors in the response and re-run the failed recipients rather than the full list. Since each recipient has a key, re-running is safe — duplicates are silently ignored.

JavaScript

function extractFailures(result) {
  return (result.errors ?? []).filter(e => e.code !== "duplicate_key");
}

Auto-claim Gifts as Fallback — what to do when a recipient doesn’t claim their gift
Track Order Fulfillment — subscribe to webhooks once the gift is claimed

Introduction

Patterns

Recipes

Migration

Prerequisites

Create gifts

Chunking for large lists

Idempotency

Partial failure handling

​Prerequisites

​Create gifts

​Chunking for large lists

​Idempotency

​Partial failure handling

​Related

Prerequisites

Create gifts

Chunking for large lists

Idempotency

Partial failure handling

Related