> ## 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.

# Duplicate Gift Detection

> Prevent accidental double-billing with idempotency keys. How to assign keys, reuse them safely, and handle conflict responses.

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.

<Note>
  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.
</Note>

### 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.

<Warning>
  **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.
</Warning>

### Usage Example

Add the `key` field to the individual recipient objects in your payload:

```json theme={null}
{
  "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`.

<Note>
  **Partial Success Scenarios**

  Because 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.
</Note>

**Sample Partial Success Response:**

```json theme={null}
{
    "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."
}
```