Create Gift Card

Create a new gift card with a specified balance

This endpoint creates a new gift card that can be purchased or issued to customers. Gift cards support both physical and digital delivery, custom designs, and flexible redemption rules.

Authentication

This endpoint requires a valid API key with gift_cards:write permissions.

Authorization: Bearer YOUR_API_KEY

Request Body

type · string · required

Gift card type: “physical”, “digital”, “both”

initial_balance · integer · required

Initial balance in cents (e.g., 5000 for $50.00)

currency · string · required

ISO 4217 currency code

recipient · object

Gift card recipient information

Show Recipient properties

email · string

Recipient email for digital delivery

name · string

Recipient name

message · string

Personal message to recipient

delivery_date · string

Scheduled delivery date (ISO 8601)

purchaser · object

Gift card purchaser information

Show Purchaser properties

customer_id · string

Existing customer ID

email · string

Purchaser email

name · string

Purchaser name

design · object

Gift card design customization

Show Design properties

template_id · string

Design template ID

custom_image_url · string

Custom image URL

theme · string

Theme: “birthday”, “holiday”, “thank_you”, “congratulations”, “custom”

validity · object

Gift card validity settings

Show Validity properties

expires_at · string

Expiration date (ISO 8601)

activation_date · string

Activation date for future use (ISO 8601)

restrictions · object

Usage restrictions

Show Restriction properties

product_ids · array

Restricted to specific products

category_ids · array

Restricted to specific categories

exclude_sale_items · boolean

Cannot be used on sale items

minimum_purchase · integer

Minimum purchase amount in cents

code · string

Custom gift card code (auto-generated if not provided)

order_id · string

Associated order ID if purchased

metadata · object

Additional custom fields

Response

Returns the created gift card object.

cURL

curl --location --request POST 'https://api.stateset.com/v1/gift-cards' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "type": "digital",
    "initial_balance": 5000,
    "currency": "USD",
    "recipient": {
        "email": "[e-mail]",
        "name": "Jane Smith",
        "message": "Happy Birthday! Enjoy your shopping.",
        "delivery_date": "2024-02-14T09:00:00Z"
    },
    "purchaser": {
        "customer_id": "cust_abc123",
        "email": "[e-mail]",
        "name": "John Doe"
    },
    "design": {
        "template_id": "tmpl_birthday_001",
        "theme": "birthday"
    },
    "validity": {
        "expires_at": "2025-02-14T23:59:59Z"
    },
    "order_id": "order_789012"
}'

Response

{
  "id": "gc_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "object": "gift_card",
  "code": "GIFT-XMAS-A3B7C9D2",
  "type": "digital",
  "status": "active",
  "initial_balance": 5000,
  "current_balance": 5000,
  "currency": "USD",
  "recipient": {
    "email": "[e-mail]",
    "name": "Jane Smith",
    "message": "Happy Birthday! Enjoy your shopping.",
    "delivery_date": "2024-02-14T09:00:00Z",
    "delivery_status": "scheduled"
  },
  "purchaser": {
    "customer_id": "cust_abc123",
    "email": "[e-mail]",
    "name": "John Doe"
  },
  "design": {
    "template_id": "tmpl_birthday_001",
    "theme": "birthday",
    "preview_url": "https://gift-cards.stateset.com/preview/gc_0901f083-aa1c-43c5-af5c-0a9d2fc64e30"
  },
  "validity": {
    "activated_at": "2024-01-20T12:00:00Z",
    "expires_at": "2025-02-14T23:59:59Z",
    "is_expired": false,
    "days_until_expiry": 390
  },
  "restrictions": {
    "product_ids": [],
    "category_ids": [],
    "exclude_sale_items": false,
    "minimum_purchase": null
  },
  "redemption_url": "https://shop.example.com/gift-card/GIFT-XMAS-A3B7C9D2",
  "order_id": "order_789012",
  "created_at": "2024-01-20T12:00:00Z",
  "updated_at": "2024-01-20T12:00:00Z",
  "transactions": [],
  "metadata": {
    "campaign": "birthday_promo_2024"
  }
}