Update gift by ID

curl --request PATCH \
  --url https://api.snappy.com/public-api/v2/gifts/{giftId} \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "customization": {
    "giftProperties": {
      "budget": {
        "max": 100,
        "min": 76
      },
      "collection": {
        "id": "12345678",
        "featuredProductId": "12345678"
      },
      "product": {
        "id": "12345678",
        "displayType": "displayAsSurprise"
      },
      "expiration": {
        "type": "specificDate",
        "date": "2022-12-06T09:50:38.536Z"
      },
      "guaranteedGift": {
        "type": "specificDate",
        "date": "2022-12-06T09:50:38.536Z"
      }
    },
    "notificationPolicy": {
      "sendingChannels": [
        "mail",
        "sms"
      ],
      "disableReminders": false
    },
    "recipientExperience": {
      "type": "enterAddress",
      "visualElements": {
        "reveal": {
          "type": "snowGlobe",
          "primaryColor": "#000000",
          "secondaryColor": "#000000",
          "mediaItems": {
            "background": [
              {
                "type": "image",
                "url": "https://example.com/image.jpg"
              }
            ],
            "logo": [
              {
                "type": "image",
                "url": "https://example.com/image.jpg"
              }
            ]
          }
        },
        "greeting": {
          "content": {
            "ops": [
              {
                "attributes": {
                  "font": "pacifico"
                },
                "insert": "Happy Birthday!"
              }
            ],
            "customProperty": "customValue"
          },
          "banner": {
            "text": "<string>",
            "color": "<string>",
            "mediaItems": {
              "background": [
                {
                  "type": "image",
                  "url": "https://example.com/image.jpg"
                }
              ],
              "logo": [
                {
                  "type": "image",
                  "url": "https://example.com/image.jpg"
                }
              ]
            }
          }
        }
      },
      "postClaim": {
        "redirectAfterClaim": "https://example.com/redirect"
      }
    }
  }
}
'

{
  "id": "<string>",
  "companyId": "12345678",
  "campaignId": "<string>",
  "status": "<string>",
  "budgetPlan": 123,
  "tyn": "<string>",
  "estimatedCost": {
    "budget": 100,
    "estimatedFee": 2,
    "estimatedTax": 7,
    "estimatedTotalCost": 109
  },
  "expirationDate": "2022-12-06T09:50:38.536Z",
  "createdAt": "<string>",
  "link": "<string>",
  "success": true,
  "deliveryDetails": {
    "carrier": "<string>",
    "trackingNumber": "<string>",
    "trackingLink": "<string>",
    "deliveredAt": "2022-12-06T09:50:38.536Z",
    "outForDelivery": "2022-12-06T09:50:38.536Z",
    "outForDeliveryDate": "2022-12-06T09:50:38.536Z"
  },
  "finalCost": {
    "cost": 100,
    "finalFee": 2,
    "finalTax": 7,
    "totalFinalCost": 109
  },
  "recipient": {
    "firstname": "John",
    "lastname": "Doe",
    "externalId": "1234567890",
    "phone": "+1234567890",
    "email": "example@domain.com",
    "key": "abc123"
  },
  "orders": [
    {
      "id": "<string>",
      "orderedProducts": [
        {
          "selectedProduct": {
            "variantId": "<string>",
            "title": "<string>"
          },
          "deliveryDetails": {
            "carrier": "<string>",
            "trackingNumber": "<string>",
            "trackingLink": "<string>",
            "deliveryDates": {
              "outForDelivery": "2023-11-07T05:31:56Z",
              "estimated": "2023-11-07T05:31:56Z",
              "deliveredAt": "2023-11-07T05:31:56Z"
            }
          }
        }
      ],
      "orderRecipient": {
        "firstName": "John",
        "lastName": "Doe",
        "country": "US"
      }
    }
  ],
  "customization": {
    "giftProperties": {
      "budget": {
        "max": 100,
        "min": 76
      }
    },
    "recipientNotifications": {
      "sendingChannels": [
        "mail",
        "sms"
      ],
      "disableReminders": false
    },
    "recipientExperience": {
      "type": "enterAddress",
      "visualElements": {
        "reveal": {
          "type": "snowGlobe",
          "primaryColor": "#000000",
          "secondaryColor": "#000000"
        },
        "greeting": {
          "content": {
            "ops": [
              {
                "insert": "Happy Birthday!"
              }
            ]
          },
          "banner": {
            "text": "Happy Birthday!",
            "color": "#000000",
            "mediaItems": {
              "background": [
                {
                  "type": "image",
                  "url": "https://example.com/image.jpg"
                }
              ]
            }
          }
        },
        "postClaim": {
          "redirectAfterClaim": "https://example.com/redirect"
        }
      }
    }
  }
}

Gifts

Update gift by ID

Use this endpoint to update the Gift Customization settings of a specific gift that has not yet been claimed. Changes apply only to unclaimed gifts.

Required fields:

giftId - the Gift identifier, passed as a path parameter

Optional fields: (in request body, under `customization`)

giftProperties - budget, expiration, collection / product, guaranteed gift configuration
notificationPolicy - sending channels, reminder settings
recipientExperience - type, visual elements, post-claim redirect

Optional parameters:

companyId query parameter - Company ID (when not inferable from the calling key)

Behavior Notes

Changes apply only to unclaimed gifts (status unopened, unwrapped, or opened). Updating a claimed gift returns 409 (409_PBLC_001).
Returns 404 if the Gift doesn’t exist or isn’t accessible to the calling key.

Permissions

Requires: gifts:update

PATCH

gifts

{giftId}

Update gift by ID

curl --request PATCH \
  --url https://api.snappy.com/public-api/v2/gifts/{giftId} \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "customization": {
    "giftProperties": {
      "budget": {
        "max": 100,
        "min": 76
      },
      "collection": {
        "id": "12345678",
        "featuredProductId": "12345678"
      },
      "product": {
        "id": "12345678",
        "displayType": "displayAsSurprise"
      },
      "expiration": {
        "type": "specificDate",
        "date": "2022-12-06T09:50:38.536Z"
      },
      "guaranteedGift": {
        "type": "specificDate",
        "date": "2022-12-06T09:50:38.536Z"
      }
    },
    "notificationPolicy": {
      "sendingChannels": [
        "mail",
        "sms"
      ],
      "disableReminders": false
    },
    "recipientExperience": {
      "type": "enterAddress",
      "visualElements": {
        "reveal": {
          "type": "snowGlobe",
          "primaryColor": "#000000",
          "secondaryColor": "#000000",
          "mediaItems": {
            "background": [
              {
                "type": "image",
                "url": "https://example.com/image.jpg"
              }
            ],
            "logo": [
              {
                "type": "image",
                "url": "https://example.com/image.jpg"
              }
            ]
          }
        },
        "greeting": {
          "content": {
            "ops": [
              {
                "attributes": {
                  "font": "pacifico"
                },
                "insert": "Happy Birthday!"
              }
            ],
            "customProperty": "customValue"
          },
          "banner": {
            "text": "<string>",
            "color": "<string>",
            "mediaItems": {
              "background": [
                {
                  "type": "image",
                  "url": "https://example.com/image.jpg"
                }
              ],
              "logo": [
                {
                  "type": "image",
                  "url": "https://example.com/image.jpg"
                }
              ]
            }
          }
        }
      },
      "postClaim": {
        "redirectAfterClaim": "https://example.com/redirect"
      }
    }
  }
}
'

{
  "id": "<string>",
  "companyId": "12345678",
  "campaignId": "<string>",
  "status": "<string>",
  "budgetPlan": 123,
  "tyn": "<string>",
  "estimatedCost": {
    "budget": 100,
    "estimatedFee": 2,
    "estimatedTax": 7,
    "estimatedTotalCost": 109
  },
  "expirationDate": "2022-12-06T09:50:38.536Z",
  "createdAt": "<string>",
  "link": "<string>",
  "success": true,
  "deliveryDetails": {
    "carrier": "<string>",
    "trackingNumber": "<string>",
    "trackingLink": "<string>",
    "deliveredAt": "2022-12-06T09:50:38.536Z",
    "outForDelivery": "2022-12-06T09:50:38.536Z",
    "outForDeliveryDate": "2022-12-06T09:50:38.536Z"
  },
  "finalCost": {
    "cost": 100,
    "finalFee": 2,
    "finalTax": 7,
    "totalFinalCost": 109
  },
  "recipient": {
    "firstname": "John",
    "lastname": "Doe",
    "externalId": "1234567890",
    "phone": "+1234567890",
    "email": "example@domain.com",
    "key": "abc123"
  },
  "orders": [
    {
      "id": "<string>",
      "orderedProducts": [
        {
          "selectedProduct": {
            "variantId": "<string>",
            "title": "<string>"
          },
          "deliveryDetails": {
            "carrier": "<string>",
            "trackingNumber": "<string>",
            "trackingLink": "<string>",
            "deliveryDates": {
              "outForDelivery": "2023-11-07T05:31:56Z",
              "estimated": "2023-11-07T05:31:56Z",
              "deliveredAt": "2023-11-07T05:31:56Z"
            }
          }
        }
      ],
      "orderRecipient": {
        "firstName": "John",
        "lastName": "Doe",
        "country": "US"
      }
    }
  ],
  "customization": {
    "giftProperties": {
      "budget": {
        "max": 100,
        "min": 76
      }
    },
    "recipientNotifications": {
      "sendingChannels": [
        "mail",
        "sms"
      ],
      "disableReminders": false
    },
    "recipientExperience": {
      "type": "enterAddress",
      "visualElements": {
        "reveal": {
          "type": "snowGlobe",
          "primaryColor": "#000000",
          "secondaryColor": "#000000"
        },
        "greeting": {
          "content": {
            "ops": [
              {
                "insert": "Happy Birthday!"
              }
            ]
          },
          "banner": {
            "text": "Happy Birthday!",
            "color": "#000000",
            "mediaItems": {
              "background": [
                {
                  "type": "image",
                  "url": "https://example.com/image.jpg"
                }
              ]
            }
          }
        },
        "postClaim": {
          "redirectAfterClaim": "https://example.com/redirect"
        }
      }
    }
  }
}

Authorizations

X-Api-Key

string

header

required

Company Level Authentication

Company level authentication provides access to all resources under your company, including accounts, campaigns, gifts, and recipients.

Getting Your API Key

Create an API Key: Use the POST /v2/authentication/apiKeys endpoint to generate a new API key
Set Expiration: Choose from 30, 60, 90, or 180 days (default: 90 days)
Optional mTLS: Enable mutual TLS for enhanced security
Name Your Key: Provide a descriptive name for easy identification

Using Your API Key

Include your API key in the X-Api-Key header for every request:

X-Api-Key: YOUR_24_CHARACTER_API_KEY

API Key Management

Maximum Keys: Up to 3 active API keys per company
Rotation: Delete old keys before creating new ones when at the limit
Security: Keys are hashed and cannot be retrieved after creation

Enhanced Security (mTLS)

For production environments, enable mutual TLS authentication:

Set enforceMtls: true when creating the API key
Contact support to obtain your client certificates
Use the mTLS endpoint: https://mtls-api.snappy.com/public-api

Path Parameters

giftId

string

required

Gift ID

Pattern: ^[A-Za-z0-9]{8,}$

Example:

"abc123de"

Query Parameters

companyId

string

Company ID

Pattern: ^[A-Za-z0-9]{8,}$

Example:

"12345678"

Body

application/json

Gift configuration to patch

customization

object

Show child attributes

Response

The Gift object.

string

required

The gift identifier

companyId

string

The company id

Example:

"12345678"

campaignId

string

The campaign identifier

status

string

The status of the gift.

budgetPlan

number

deprecated

The budget plan of the gift. This field is deprecated, use "customization.giftProperties.budget" instead.

tyn

string

A Thank You Note sent by the end client.

estimatedCost

object

The estimated cost of the gift including estimated tax and fee.

Show child attributes

Example:

{
  "budget": 100,
  "estimatedFee": 2,
  "estimatedTax": 7,
  "estimatedTotalCost": 109
}

expirationDate

string

deprecated

When the gift will be expired. Date Format: YYYY-MM-DDThh:mm:ss.sZ. This field is deprecated, use "customization.giftProperties.expiration" instead.

Example:

"2022-12-06T09:50:38.536Z"

createdAt

string

When the gift was originally created. Date Format: YYYY-MM-DDThh:mm:ss.sZ. e.g. 2022-12-06T09:50:38.536Z

link

string

The link used to redeem the gift.

success

boolean

The success of the gift creation

deliveryDetails

object

deprecated

The Delivery Details object.

Show child attributes

finalCost

object

The final cost of the gift including tax and fee.

Show child attributes

Example:

{
  "cost": 100,
  "finalFee": 2,
  "finalTax": 7,
  "totalFinalCost": 109
}

recipient

object

The gift recipient object.

Show child attributes

Example:

{
  "firstname": "John",
  "lastname": "Doe",
  "externalId": "1234567890",
  "phone": "+1234567890",
  "email": "example@domain.com",
  "key": "abc123"
}

orders

object[]

Show child attributes

customization

object

Complete gift customization configuration

Show child attributes

Last modified on June 17, 2026

Get gift by ID

Expire a gift