# Gift card products

Source: https://developers.swell.is/backend-api/gift-card-products

Gift card products are [products](https://developers.swell.is/backend-api/products) with `type=giftcard`. When preparing to sell gift cards in a store, consider whether there is a need to fulfill physical cards or have a gift card code automatically generated and email to the customer.

When selling physical gift cards, an admin would generate gift card codes from the Swell dashboard and export the codes for printing. In this case, the gift card product would have `delivery=shipment instead of delivery=giftcard.`

## Create a gift card for email fulfillment

Create a gift card product that will be fulfilled automatically by email.

### Arguments

- `name` (string, required): Human-friendly name of the product.
- `options` (array of object, required): Specify the denominations available on the product.
  - `name` (string, required): Name of the denominated value.
  - `values` (array of object, required): List of possible values for this option.
    - `name` (string, required): Human-friendly name of the option value.
    - `price` (currency, required): Value fulfilled as a gift card when the option is selected.
  - `variant` (boolean, required): Must be `true` for gift card options.
- `type` (string, required): Set to `giftcard` to indicate the product is a gift card.
- `delivery` (enum): For gift cards fulfilled digitally, set `delivery=giftcard`. Possible values: `shipment`, `subscription`, `giftcard`.
- `active` (boolean): Set `true` to make the product visible to customers in a storefront, otherwise it will be hidden.
- `attributes` (object): An object containing custom attribute key/value pairs. See [attributes](https://developers.swell.is/frontend-api/attributes) for more details.
- `category_id` (objectId): Primary category, commonly used as a navigation anchor.
- `description` (string): A long-form description of the product. Can have HTML or other markup languages.
- `images` (array of object): List of images depicting the bundle.
  - `caption` (string): A brief description of the image, intended for display as a caption or alt text.
  - `file` (object): An object representing the image's source file.
    - `data` (filedata): Set or overwrite file data. Use the following format when writing a file from binary data (for example an image): `data[$binary]=<base64 encoded binary daya>`.
    - `filename` (string): Optional file name.
- `meta_description` (string): Page description used for search engine optimization purposes.
- `meta_keywords` (string): Page keywords used for search engine optimization purposes.
- `meta_title` (string): Page title used to override product name in storefronts.
- `slug` (string): Lowercase, hyphenated identifier typically used in URLs. When creating a product, a `slug` will be generated automatically from the `name`. Maximum length of 1,000 characters.
- `tags` (string): List of arbitrary tags typically used as metadata to improve search results or associate custom behavior with a product.

### Example request

`POST /products`

**cURL**

```bash
$ curl https://api.swell.store/products \
  -u store-id:secret-key \
  -d name="Gift Card" \
  -d type=giftcard \
  -d options[0][name]=Value \
  -d options[0][variant]=true \
  -d options[0][values][0][name]=$25 \
  -d options[0][values][0][price]=25 \
  -d options[0][values][1][name]=$50 \
  -d options[0][values][1][price]=50 \
  -d options[0][values][2][name]=$100 \
  -d options[0][values][2][price]=100
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.post('/products', {
  name: 'Gift Card',
  type: 'giftcard',
  options: [
    {
      name: 'Value',
      variant: true,
      values: [
        {
          name: '$25',
          price: 25,
        },
        {
          name: '$50',
          price: 50,
        },
        {
          name: '$100',
          price: 100,
        },
      ],
    },
  ],
});
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->post('/products', [
  'name' => 'Gift Card',
  'type' => 'giftcard',
  'options' => [
    [
      'name' => 'Value',
      'variant' => true,
      'values' => [
        [
          'name' => '$25',
          'price' => 25
        ],
        [
          'name' => '$50',
          'price' => 50
        ],
        [
          'name' => '$100',
          'price' => 100
        ]
      ]
    ]
  ]
]);
```

### Example response

```json
{
  "id": "5cad15bc9b14d1990724663a",
  "delivery": "giftcard"
  "name": "Gift Card",
  "options": [
    {
      "id": "5ca24ab32599d4179c24a624",
      "name": "Value",
      "variant": true,
      "values": [
        {
          "id": "5ca24ad59c077817e5fe2ba3",
          "name": "$25",
          "price": 25
        },
        {
          "id": "5ca24ad59c077817e5fe2ba4",
          "name": "$50",
          "price": 50
        },
        {
          "id": "5ca24ad59c077817e5fe2ba5",
          "name": "$100",
          "price": 100
        }
      ]
    }
  ],
  "slug": "gift-card",
  "type": "giftcard"
}
```


## Create a gift card for physical delivery

Create a gift card product that will be fulfilled by shipping a physical card.

### Arguments

- `name` (string, required): Human-friendly name of the product.
- `options` (array of object, required): Specify the denominations available on the product.
  - `name` (string, required): Name of the denominated value.
  - `values` (array of object, required): List of possible values for this option.
    - `name` (string, required): Human-friendly name of the option value.
    - `price` (currency, required): Value fulfilled as a gift card when the option is selected.
  - `variant` (boolean, required): Must be `true` for gift card options.
- `type` (string, required): Set to `giftcard` to indicate the product is a gift card.
- `delivery` (enum): For gift cards fulfilled digitally, set `delivery=shipment`. Possible values: `shipment`, `subscription`, `giftcard`.
- `active` (boolean): Set `true` to make the product visible to customers in a storefront, otherwise it will be hidden.
- `attributes` (object): An object containing custom attribute key/value pairs. See [attributes](https://developers.swell.is/frontend-api/attributes) for more details.
- `category_id` (objectId): Primary category, commonly used as a navigation anchor.
- `description` (string): A long-form description of the product. Can have HTML or other markup languages.
- `images` (array of object): List of images depicting the bundle.
  - `caption` (string): A brief description of the image, intended for display as a caption or alt text.
  - `file` (object): An object representing the image's source file.
    - `data` (filedata): Set or overwrite file data. Use the following format when writing a file from binary data (for example an image): `data[$binary]=<base64 encoded binary daya>`.
    - `filename` (string): Optional file name.
- `meta_description` (string): Page description used for search engine optimization purposes.
- `meta_keywords` (string): Page keywords used for search engine optimization purposes.
- `meta_title` (string): Page title used to override product name in storefronts.
- `slug` (string): Lowercase, hyphenated identifier typically used in URLs. When creating a product, a `slug` will be generated automatically from the `name`. Maximum length of 1,000 characters.
- `tags` (string): List of arbitrary tags typically used as metadata to improve search results or associate custom behavior with a product.

### Example request

`POST /products`

**cURL**

```bash
$ curl https://api.swell.store/products \
  -u store-id:secret-key \
  -d name="Gift Card" \
  -d type=giftcard \
  -d delivery=shipment \
  -d options[0][name]=Value \
  -d options[0][variant]=true \
  -d options[0][values][0][name]=$25 \
  -d options[0][values][0][price]=25 \
  -d options[0][values][1][name]=$50 \
  -d options[0][values][1][price]=50 \
  -d options[0][values][2][name]=$100 \
  -d options[0][values][2][price]=100
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.post('/products', {
  name: 'Gift Card',
  type: 'giftcard',
  delivery: 'shipment',
  options: [
    {
      name: 'Value',
      variant: true,
      values: [
        {
          name: '$25',
          price: 25,
        },
        {
          name: '$50',
          price: 50,
        },
        {
          name: '$100',
          price: 100,
        },
      ],
    },
  ],
});
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->post('/products', [
  'name' => 'Gift Card',
  'type' => 'giftcard',
  'delivery' => 'shipment',
  'options' => [
    [
      'name' => 'Value',
      'variant' => true,
      'values' => [
        [
          'name' => '$25',
          'price' => 25
        ],
        [
          'name' => '$50',
          'price' => 50
        ],
        [
          'name' => '$100',
          'price' => 100
        ]
      ]
    ]
  ]
]);
```

### Example response

```json
{
  "id": "5cad15bc9b14d1990724663a",
  "delivery": "shipment"
  "name": "Gift Card",
  "options": [
    {
      "id": "5ca24ab32599d4179c24a624",
      "name": "Value",
      "variant": true,
      "values": [
        {
          "id": "5ca24ad59c077817e5fe2ba3",
          "name": "$25",
          "price": 25
        },
        {
          "id": "5ca24ad59c077817e5fe2ba4",
          "name": "$50",
          "price": 50
        },
        {
          "id": "5ca24ad59c077817e5fe2ba5",
          "name": "$100",
          "price": 100
        }
      ]
    }
  ],
  "slug": "gift-card",
  "type": "giftcard"
}
```