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

# Shopify Gift Card Order Metafield

<Warning>
  Loop writes this metafield only when the feature is enabled for your shop.
  Contact your Merchant Success Manager or Implementation team to request
  enablement.
</Warning>

## Overview

When Loop **issues a Shopify gift card** for a return, it can append structured
gift card details to the original Shopify order. Integrations read this
metafield from **Shopify's order API** — there is no Loop API endpoint for
this data.

**Scope:** Shopify-native gift card issuance only (Loop creates the gift card in
Shopify). This does not apply to third-party store credit or gift card platforms
(for example Rise.ai) or other credit providers. Use the
[Gift card webhook](/webhook-reference/topics/gift-card-webhook) for those flows.

| Surface                                                          | When to use                                                |
| ---------------------------------------------------------------- | ---------------------------------------------------------- |
| [Gift card webhook](/webhook-reference/topics/gift-card-webhook) | Third-party providers, or push-based integration           |
| **Order metafield**                                              | Shopify gift cards when the order is your system of record |

## Metafield location

| Property  | Value                        |
| --------- | ---------------------------- |
| Namespace | `loop-returns-data`          |
| Key       | `gift_cards`                 |
| Type      | JSON object (map of entries) |

Each successful issuance adds one map entry keyed by that gift card. If Loop
writes the same gift card again, the existing entry for that key is replaced
with the same payload — integrators should treat entries as idempotent by map
key.

## When Loop writes

Loop writes when all of the following are true:

1. The shop has this feature enabled.
2. Gift card credit is **successfully issued** (action `issued`).
3. The provider is **Shopify gift card API** or **Shopify gift card order**
   (Loop-created Shopify gift cards).

Loop does **not** write for Rise, Reshop, Shopify store credit refund,
third-party gift card webhooks, failed issuance, or shops without enablement.

## Standard vs out-of-stock exchange

Both paths write the same metafield when Loop issues a **Shopify** gift card.
The entry shape differs.

When Loop issues a Shopify gift card for an out-of-stock exchange (including
auto out-of-stock gift cards), Loop writes this metafield when enabled and does
**not** send the `giftcard.requested` webhook. That webhook still applies for
third-party providers such as Rise.

|                             | **Standard store-credit issuance**                              | **Out-of-stock exchange credit**                                    |
| --------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------- |
| **Trigger**                 | Return settled as store credit; Loop issues a Shopify gift card | Exchange item is out of stock; Loop issues Shopify gift card credit |
| **Map key**                 | `gift_card_{id}` (`id` = Loop gift card ID)                     | `gift_card_provider_{shopify_gift_card_id}`                         |
| **`id` field**              | Loop gift card ID                                               | `null`                                                              |
| **Tax / bonus**             | From the return gift card breakdown                             | Always `0.00`                                                       |
| **`provider_gift_card_id`** | Shopify gift card ID from Loop's gift card record               | Shopify gift card ID from the issuance result                       |
| **`issued_at`**             | From gift card `processed_at` when available                    | From the issuance result when available                             |
| **Loop `gift_cards` row**   | Usually present                                                 | Often absent                                                        |

<Note>
  **Out-of-stock edge case:** If Loop cannot obtain a Shopify gift card ID or a
  non-zero issuance amount, no metafield entry is written for that event.
</Note>

## Entry schema

Each map value uses the same fields as the
[Gift card webhook](/webhook-reference/topics/gift-card-webhook) payload (minus
`topic` and `trigger`), plus issuance identifiers. Amount fields are formatted
strings in shop currency.

| Field                    | Type            | Description                                                            |
| ------------------------ | --------------- | ---------------------------------------------------------------------- |
| `id`                     | integer \| null | Loop gift card ID; `null` for some out-of-stock paths                  |
| `total_credit_issued`    | string          | Total credit issued                                                    |
| `gift_card_subtotal`     | string          | Gift card value minus taxes and bonus                                  |
| `gift_card_tax`          | string          | Tax portion                                                            |
| `gift_card_bonus_credit` | string          | Bonus credit                                                           |
| `presentment`            | object          | Customer-facing currency amounts (same shape as the gift card webhook) |
| `currency`               | string          | Shop currency code                                                     |
| `return_id`              | integer         | Loop return ID                                                         |
| `email`                  | string          | Customer email                                                         |
| `first_name`             | string          | Customer first name                                                    |
| `last_name`              | string          | Customer last name                                                     |
| `external_order_id`      | integer         | Shopify order ID                                                       |
| `external_order_name`    | string          | Order name (for example `#1234`)                                       |
| `external_order_number`  | integer \| null | Order number when available                                            |
| `provider_gift_card_id`  | string          | Shopify gift card ID (when available)                                  |
| `issued_at`              | string          | ISO 8601 issuance timestamp (when available)                           |

## Examples

### Standard issuance

```json theme={null}
{
  "gift_card_98765": {
    "id": 98765,
    "total_credit_issued": "50.00",
    "gift_card_subtotal": "45.00",
    "gift_card_tax": "3.00",
    "gift_card_bonus_credit": "2.00",
    "presentment": {
      "total_credit_issued": "50.00",
      "gift_card_subtotal": "45.00",
      "gift_card_tax": "3.00",
      "gift_card_bonus_credit": "2.00",
      "currency": "USD"
    },
    "currency": "USD",
    "return_id": 123456,
    "email": "customer@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "external_order_id": 5678901234,
    "external_order_name": "#1042",
    "external_order_number": 1042,
    "provider_gift_card_id": "1122334455",
    "issued_at": "2026-08-15T14:30:00+00:00"
  }
}
```

### Out-of-stock exchange (second entry on the same order)

```json theme={null}
{
  "gift_card_98765": {
    "id": 98765,
    "total_credit_issued": "50.00",
    "gift_card_subtotal": "45.00",
    "gift_card_tax": "3.00",
    "gift_card_bonus_credit": "2.00",
    "presentment": {
      "total_credit_issued": "50.00",
      "gift_card_subtotal": "45.00",
      "gift_card_tax": "3.00",
      "gift_card_bonus_credit": "2.00",
      "currency": "USD"
    },
    "currency": "USD",
    "return_id": 123456,
    "email": "customer@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "external_order_id": 5678901234,
    "external_order_name": "#1042",
    "external_order_number": 1042,
    "provider_gift_card_id": "1122334455",
    "issued_at": "2026-08-15T14:30:00+00:00"
  },
  "gift_card_provider_9988776655": {
    "id": null,
    "total_credit_issued": "25.00",
    "gift_card_subtotal": "25.00",
    "gift_card_tax": "0.00",
    "gift_card_bonus_credit": "0.00",
    "presentment": {
      "total_credit_issued": "25.00",
      "gift_card_subtotal": "25.00",
      "gift_card_tax": "0.00",
      "gift_card_bonus_credit": "0.00",
      "currency": "USD"
    },
    "currency": "USD",
    "return_id": 123457,
    "email": "customer@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "external_order_id": 5678901234,
    "external_order_name": "#1042",
    "external_order_number": 1042,
    "provider_gift_card_id": "9988776655",
    "issued_at": "2026-08-16T09:15:00+00:00"
  }
}
```

## Reading from Shopify

Query the order metafield with the Shopify Admin API:

```graphql theme={null}
query OrderGiftCards($id: ID!) {
  order(id: $id) {
    metafield(namespace: "loop-returns-data", key: "gift_cards") {
      value
    }
  }
}
```

Parse `value` as JSON. Multiple issuances on the same order accumulate as
separate map keys.

## Related documentation

* [Gift card webhook](/webhook-reference/topics/gift-card-webhook) — push-based
  alternative
* [Retrieving Return Data](/integration-guides/return-data) — Loop API polling
  options