Shopify Gift Card Order Metafield

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

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 for those flows.

Surface	When to use
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:

The shop has this feature enabled.
Gift card credit is successfully issued (action issued).
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

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.

Entry schema

Each map value uses the same fields as the 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

{
  "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)

{
  "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:

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.

Gift card webhook — push-based alternative
Retrieving Return Data — Loop API polling options

Introduction

Guides

Use Cases

Return Create

Overview

Metafield location

When Loop writes

Standard vs out-of-stock exchange

Entry schema

Examples

Standard issuance

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

Reading from Shopify

​Overview

​Metafield location

​When Loop writes

​Standard vs out-of-stock exchange

​Entry schema

​Examples

​Standard issuance

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

​Reading from Shopify

​Related documentation

Overview

Metafield location

When Loop writes

Standard vs out-of-stock exchange

Entry schema

Examples

Standard issuance

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

Reading from Shopify

Related documentation