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

# Create Gift Card

> This endpoint adds a new gift card to a user's account.

This endpoint allows users to add a gift card to their account. The card is validated with the gift card provider and the balance is checked before the card is stored. The system prevents duplicate cards — the same card number cannot be added twice for the same user and merchant.

<Note>
  Please review proper request headers [here](/consumer/usage/headers).
</Note>

### Body

<ParamField body="provider_id" type="string" required>
  The provider merchant ID. This identifies which gift card provider and merchant configuration to use for validation.
</ParamField>

<ParamField body="card_number" type="string" required>
  The full gift card number
</ParamField>

<ParamField body="pin" type="string">
  The PIN code for the gift card, if required by the provider
</ParamField>

### Response

<Snippet file="entities/gift-card.mdx" />

<RequestExample>
  ```bash With PIN theme={null}
  curl https://api.thanxsandbox.com/gift_cards \
    -X POST \
    -H "Content-Type: application/json"  \
    -H "Accept-Version: v4.0" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer ${token}" \
    -H "X-ClientId: ${client_id}" \
    -d '{
      "provider_id": "prov123merchant",
      "card_number": "1234567890123456",
      "pin": "1234"
    }'
  ```

  ```bash Without PIN theme={null}
  curl https://api.thanxsandbox.com/gift_cards \
    -X POST \
    -H "Content-Type: application/json"  \
    -H "Accept-Version: v4.0" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer ${token}" \
    -H "X-ClientId: ${client_id}" \
    -d '{
      "provider_id": "prov123merchant",
      "card_number": "9876543210987654"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "gift_card": {
      "id": "abc123def456",
      "provider_id": "prov123merchant",
      "card_number": "1234567890123456",
      "pin": "1234",
      "last4": "3456",
      "balance": 50.00,
      "state": "active",
      "expires_at": "2026-12-31T23:59:59Z",
      "created_at": "2024-12-15T10:00:00Z"
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": "This gift card has already been added"
  }
  ```
</ResponseExample>