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. Customers redeem cards through the storefront endpoints.

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 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#

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#

Response#

Success:

{
  gift_card,
}

Example Request#

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:

{
  gift_cards,
  count,
  offset,
  limit,
}

Example Request#

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#

Request Body#

Response#

Success:

{
  gift_card,
}

Example Request#

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#

Response#

Success:

{
  gift_card,
}

Example Request#

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#

Response#

Success:

{
  orders,
}

Example Request#

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