> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Gift Card

> Create a new gift card with a specified balance

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

## Authentication

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

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Request Body

<ParamField body="type" type="string" required>
  Gift card type: "physical", "digital", "both"
</ParamField>

<ParamField body="initial_balance" type="integer" required>
  Initial balance in cents (e.g., 5000 for \$50.00)
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 currency code
</ParamField>

<ParamField body="recipient" type="object">
  Gift card recipient information

  <Expandable title="Recipient properties">
    <ParamField body="email" type="string">
      Recipient email for digital delivery
    </ParamField>

    <ParamField body="name" type="string">
      Recipient name
    </ParamField>

    <ParamField body="message" type="string">
      Personal message to recipient
    </ParamField>

    <ParamField body="delivery_date" type="string">
      Scheduled delivery date (ISO 8601)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="purchaser" type="object">
  Gift card purchaser information

  <Expandable title="Purchaser properties">
    <ParamField body="customer_id" type="string">
      Existing customer ID
    </ParamField>

    <ParamField body="email" type="string">
      Purchaser email
    </ParamField>

    <ParamField body="name" type="string">
      Purchaser name
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="design" type="object">
  Gift card design customization

  <Expandable title="Design properties">
    <ParamField body="template_id" type="string">
      Design template ID
    </ParamField>

    <ParamField body="custom_image_url" type="string">
      Custom image URL
    </ParamField>

    <ParamField body="theme" type="string">
      Theme: "birthday", "holiday", "thank\_you", "congratulations", "custom"
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="validity" type="object">
  Gift card validity settings

  <Expandable title="Validity properties">
    <ParamField body="expires_at" type="string">
      Expiration date (ISO 8601)
    </ParamField>

    <ParamField body="activation_date" type="string">
      Activation date for future use (ISO 8601)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="restrictions" type="object">
  Usage restrictions

  <Expandable title="Restriction properties">
    <ParamField body="product_ids" type="array">
      Restricted to specific products
    </ParamField>

    <ParamField body="category_ids" type="array">
      Restricted to specific categories
    </ParamField>

    <ParamField body="exclude_sale_items" type="boolean">
      Cannot be used on sale items
    </ParamField>

    <ParamField body="minimum_purchase" type="integer">
      Minimum purchase amount in cents
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="code" type="string">
  Custom gift card code (auto-generated if not provided)
</ParamField>

<ParamField body="order_id" type="string">
  Associated order ID if purchased
</ParamField>

<ParamField body="metadata" type="object">
  Additional custom fields
</ParamField>

### Response

Returns the created gift card object.

<RequestExample>
  ```bash cURL theme={null}
  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": "recipient@example.com",
          "name": "Jane Smith",
          "message": "Happy Birthday! Enjoy your shopping.",
          "delivery_date": "2024-02-14T09:00:00Z"
      },
      "purchaser": {
          "customer_id": "cust_abc123",
          "email": "purchaser@example.com",
          "name": "John Doe"
      },
      "design": {
          "template_id": "tmpl_birthday_001",
          "theme": "birthday"
      },
      "validity": {
          "expires_at": "2025-02-14T23:59:59Z"
      },
      "order_id": "order_789012"
  }'
  ```

  ```javascript Node.js theme={null}
  const giftCard = await stateset.giftCards.create({
    type: "digital",
    initial_balance: 5000,
    currency: "USD",
    recipient: {
      email: "recipient@example.com",
      name: "Jane Smith",
      message: "Happy Birthday! Enjoy your shopping.",
      delivery_date: "2024-02-14T09:00:00Z"
    },
    purchaser: {
      customer_id: "cust_abc123",
      email: "purchaser@example.com",
      name: "John Doe"
    },
    design: {
      template_id: "tmpl_birthday_001",
      theme: "birthday"
    },
    validity: {
      expires_at: "2025-02-14T23:59:59Z"
    },
    order_id: "order_789012"
  });
  ```

  ```python Python theme={null}
  gift_card = stateset.gift_cards.create(
    type="digital",
    initial_balance=5000,
    currency="USD",
    recipient={
      "email": "recipient@example.com",
      "name": "Jane Smith",
      "message": "Happy Birthday! Enjoy your shopping.",
      "delivery_date": "2024-02-14T09:00:00Z"
    },
    purchaser={
      "customer_id": "cust_abc123",
      "email": "purchaser@example.com",
      "name": "John Doe"
    },
    design={
      "template_id": "tmpl_birthday_001",
      "theme": "birthday"
    },
    validity={
      "expires_at": "2025-02-14T23:59:59Z"
    },
    order_id="order_789012"
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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": "recipient@example.com",
      "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": "purchaser@example.com",
      "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"
    }
  }
  ```
</ResponseExample>