Duplicate Gift Detection

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:

UUID (Recommended): Generate a random version 4 UUID for every gift object.
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."
}

Welcome

Start building

Our API Standards

Migrating to V3

Webhooks & Events

How it Works

Implementing Unique Keys

Usage Example

Handling Errors & Partial Success

​How it Works

​Implementing Unique Keys

​Usage Example

​Handling Errors & Partial Success

How it Works

Implementing Unique Keys

Usage Example

Handling Errors & Partial Success