Skip to main content
To protect the recipient experience and maintain billing accuracy, Snappy uses a unique key system to prevent redundant gift deliveries. This idempotency system ensures that your integration remains reliable even in the event of network timeouts, automated retries, or accidental double-clicks.
Including a unique key is not mandatory, but it is strongly recommended for all production integrations to ensure billing accuracy and a seamless recipient experience.

​
How it Works

When you include a key in your gift request, Snappy checks if that specific key has been used before.
  • If it’s a new key: We process the gift as usual.
  • If the key exists: We reject the duplicate and return a specific error, ensuring no additional gift is sent or billed.

​
Implementing Unique Keys

We recommend generating a unique key for every gift intent. You can use two primary strategies:
  1. UUID (Recommended): Generate a random version 4 UUID for every gift object.
  2. Deterministic Logic: Create a string based on your internal business rules (e.g., user_123_anniversary_2024). This is perfect for ensuring a recipient only receives one gift for a specific event.
Keys do not expire with their associated gift. Even if a gift expires without being claimed, its key remains permanently reserved in the system. Reusing an expired gift’s key for a new send will trigger a duplicate detection error. Always generate a fresh unique key for every new gift intent, regardless of the outcome of previous sends.

​
Usage Example

Add the key field to the individual recipient objects in your payload: 
{
  "campaignId": "cmp_12345",
  "recipients": [
    {
      "firstname": "John",
      "lastname": "Doe",
      "email": "john@example.com",
      "key": "unique-uuid-string-001"
    },
    {
      "firstname": "Jane",
      "lastname": "Doe",
      "email": "jane@example.com",
      "key": "unique-uuid-string-002"
    }
  ]
}

​
Handling Errors & Partial Success

If a duplicate key is detected, the API will return errorCode: 41008.
Partial Success ScenariosBecause Snappy processes gift batches, a single request may result in a “Partial Success.” This happens if some keys in your list are new while others are duplicates.
Sample Partial Success Response: 
{
    "results": [
        {
            "success": false,
            "message": "Duplicate gift detected based on the provided key.",
            "errorCode": 41008
        },
        {
            "success": true,
            "id": "gft_789abc",
            "link": "https://gift.snappy.com/gft_789abc"
        }
    ],
    "message": "1 gift out of 2 sent successfully."
}
Last modified on June 17, 2026