# Gift Cards

**Category:** Admin
**Base URL:** `/admin/gift-cards`
**Authentication:** Required
**Routes:** 3 routes documented

## Overview

This section documents 3 API routes for gift cards.

A gift card is a code with a balance, held by whoever has the code. It is not tied to a customer, which is what separates it from [store credit](/admin/store-credit). Customers redeem cards through the [storefront endpoints](/store/gift-cards).

Applying a balance to a cart does not spend it. The deduction happens when the order completes, and is undone if payment fails. See [Gift Cards & Store Credit](/guides/gift-cards-store-credit) for the full lifecycle, the differences between the two, refunds, and troubleshooting.

> ⚠️ **These endpoints operate on your live store.** `POST`/`PUT`/`DELETE` operations here — including sync, push, resync, and cache operations — modify or delete production data, and some trigger downstream effects such as warehouse orders or customer emails. `DELETE` operations are generally irreversible. Verify IDs and parameters carefully before calling them from scripts.

## Quick Reference

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/admin/gift-cards` | Issue a gift card. `value` and `currency_code` are required.... |
| GET | `/admin/gift-cards` | List gift cards. Supports `q` for free-text search, `fields`... |
| POST | `/admin/gift-cards/:id` | Update a gift card. Used to adjust value, change the expiry,... |
| GET | `/admin/gift-cards/:id` | Retrieve one gift card, including its current balance. |
| GET | `/admin/gift-cards/:id/orders` | List the orders this gift card has been spent against. Reads... |

---

## POST Admin Gift-cards

**Endpoint:** `POST /admin/gift-cards`
**Authentication:** Admin (Required)

### Description

Issue a gift card. `value` and `currency_code` are required. A `code` may be supplied or left to be generated, and `expires_at`, `note`, `reference`, `reference_id` and `line_item_id` are optional — the reference fields are how a card generated by a purchase is tied back to the line item that bought it.

### Request Body

| Field | Type | Required |
|-------|------|----------|
| `status` | enum(PENDING, REDEEMED) | No |
| `currency_code` | string | Yes |
| `value` | number | Yes |
| `code` | string | No |
| `expires_at` | string | No |
| `reference` | string | No |
| `reference_id` | string | No |
| `line_item_id` | string | No |
| `note` | string | No |
| `metadata` | record | No |

### Response

**Success:**
```typescript
{
  gift_card,
}
```

### Example Request

```bash
curl -X POST 'https://your-store.omnicart.cc/admin/gift-cards' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'
```

---

## GET Admin Gift-cards

**Endpoint:** `GET /admin/gift-cards`
**Authentication:** Admin (Required)

### Description

List gift cards. Supports `q` for free-text search, `fields` for shaping the response, and standard limit/offset pagination; the response carries `count`, `offset` and `limit`.

### Response

**Success:**
```typescript
{
  gift_cards,
  count,
  offset,
  limit,
}
```

### Example Request

```bash
curl -X GET 'https://your-store.omnicart.cc/admin/gift-cards' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'
```

---

## POST Admin Gift-cards :id

**Endpoint:** `POST /admin/gift-cards/:id`
**Authentication:** Admin (Required)

### Description

Update a gift card. Used to adjust value, change the expiry, or annotate the card; the code itself identifies the card and is not re-issued here.

### URL Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Request Body

| Field | Type | Required |
|-------|------|----------|
| `status` | enum(PENDING, REDEEMED) | No |
| `note` | string | No |
| `expires_at` | string | No |
| `metadata` | record | No |

### Response

**Success:**
```typescript
{
  gift_card,
}
```

### Example Request

```bash
curl -X POST 'https://your-store.omnicart.cc/admin/gift-cards/:id' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'
```

---

## GET Admin Gift-cards :id

**Endpoint:** `GET /admin/gift-cards/:id`
**Authentication:** Admin (Required)

### Description

Retrieve one gift card, including its current balance.

### URL Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Response

**Success:**
```typescript
{
  gift_card,
}
```

### Example Request

```bash
curl -X GET 'https://your-store.omnicart.cc/admin/gift-cards/:id' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'
```

---

## GET Admin Gift-cards :id Orders

**Endpoint:** `GET /admin/gift-cards/:id/orders`
**Authentication:** Admin (Required)

### Description

List the orders this gift card has been spent against. Reads the order-to-gift-card link, so it answers "where did this balance go" for a card a customer is disputing.

### URL Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Id identifier |

### Response

**Success:**
```typescript
{
  orders,
}
```

### Example Request

```bash
curl -X GET 'https://your-store.omnicart.cc/admin/gift-cards/:id/orders' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'
```

---