EU Consumer Guarantee - Global-e Docs

Part of the EU Consumer Guarantee (Notice & GARAN) - Platform Setup Guides.

One-time setup

In BigCommerce, create a variant-level metafield with namespace globale and key garan_image_url (single-line text). Use a Metafields Manager app (like Hypa) to create and populate it.

Creating the metafield in BigCommerce is not enough on its own. Ask your Customer Success Manager to enable GARAN label support on your Global-e account and confirm the adapter is configured to read variant metafield globale / garan_image_url. Until that is in place, GaranImageURL will be empty in all payloads.

If you already store the URL under a different variant metafield, contact Global-e before changing anything. They will either configure the adapter to read your existing namespace/key, or ask you to adopt the standard globale / garan_image_url. Do not use a product custom field, or a generic “send metafields as attributes” mapping. Those do not populate the dedicated GaranImageURL field.

Per variant

The GARAN URL is read at variant level, not parent product level — the same grain as the product image. Set the metafield on each eligible variant. Leave it empty for variants with no guarantee.

Variant SKU	Metafield value
JKT-4471-BLK-M	`https://cdn.example.com/garan/JKT-4471.png`
JKT-4471-BLK-L	`https://cdn.example.com/garan/JKT-4471.png`
TEE-1102-WHT-L	(empty — no guarantee)

Different variants can carry different URLs. A value on the parent product alone is not read. Products with no size or colour options still have a default variant — set the metafield on that variant.

When the value syncs

Event	Path
Variant save in the BigCommerce admin	Catalog sync
Product/variant updates via API or bulk import	Catalog sync (same webhooks as admin save)
Checkout / cart refresh	Cart (GetCart)

Prerequisites

Requirement	Value
Minimum adapter version	Global-e BigCommerce 1.59 or later
Merchant data source	Variant metafield namespace `globale`, key `garan_image_url`
Admin tool	A Metafields Manager app (like Hypa), or equivalent metafield UI/API
Global-e enablement	GARAN label support enabled on your account; adapter configured to read `globale` / `garan_image_url` (see One-time setup)

Delivery paths

The value reaches Global-e on two paths: catalog sync (SaveProductsList) and checkout (GetCart). Where both supply a value for the same variant, the Catalog value wins.

Platform notes

Namespace matching is case-sensitive; key matching is case-insensitive. Use globale / garan_image_url unless Global-e has confirmed a different namespace/key pair for your account (see One-time setup). BigCommerce’s native admin has limited support for variant-level metafields on some stores. Many merchants use a Metafields Manager app (for example Hypa) to create and populate them. If your metafield namespace/key do not match what Global-e configured on your account, GaranImageURL will be empty even when a URL exists on the variant. Use a full public https:// URL to the GARAN PNG. Relative paths are not valid. This is not the storefront product image.

Payload reference

For technical readers. The field name is GaranImageURL on both catalog and cart. Catalog — POST /Browsing/SaveProductsList

[
  {
    "ProductCode": "JKT-4471-BLK-M",
    "ProductGroupCodeSecondary": "4471",
    "Name": "Alpine Insulated Jacket",
    "ImageURL": "https:\/\/cdn.example.com\/products\/jkt-4471-blk.jpg",
    "GaranImageURL": "https:\/\/cdn.example.com\/garan\/JKT-4471.png"
  },
  {
    "ProductCode": "TEE-1102-WHT-L",
    "Name": "Cotton Crew Tee",
    "ImageURL": "https:\/\/cdn.example.com\/products\/tee-1102-wht.jpg",
    "GaranImageURL": null
  }
]

Other catalog fields (for example ProductGroupCode) may appear on real payloads; only GaranImageURL and related product fields are shown here. Cart — GetCart productsList[]

{
  "productsList": [
    {
      "ProductCode": "JKT-4471-BLK-M",
      "CartItemId": "17984028-0eec-46aa-9af3-4817a207bcc7",
      "Name": "Alpine Insulated Jacket",
      "OrderedQuantity": 1,
      "ImageURL": "https:\/\/cdn.example.com\/products\/jkt-4471-blk.jpg",
      "GaranImageURL": "https:\/\/cdn.example.com\/garan\/JKT-4471.png"
    }
  ]
}

Verify

Check	Done
Variant metafield `globale` / `garan_image_url` exists and is populated on a test variant	☐
Global-e has enabled GARAN on your account (until then, `GaranImageURL` stays null even when the metafield is populated)	☐
`GaranImageURL` appears on the catalog payload after admin save or API/bulk update	☐
`GaranImageURL` appears in GetCart for that variant at checkout	☐
A variant without the metafield sends `GaranImageURL` as null or omits it	☐

Activation modes and the general preparation steps — opting in, identifying qualifying products, and creating and hosting the GARAN PNG — are covered on the EU Consumer Guarantee Information (Notice & GARAN) overview page.

FAQ

Do product variants each need their own URL?

Yes. The value is read per variant. Set the metafield on each variant Global-e syncs.

My product has no options — where do I set the URL?

Single-SKU products still have a default variant in BigCommerce. Set the metafield on that variant, not on the parent product alone.

Can I use a custom field instead of a metafield?

No. Variant metafields are the only supported source.

Why is GaranImageURL always empty?

Check in order: (1) the variant metafield is missing or set on the parent product only; (2) the namespace/key do not match what Global-e configured for your account — the default is globale / garan_image_url unless Global-e told you otherwise; (3) GARAN label support is not enabled on your Global-e account, or the adapter is not configured to read your metafield — ask your CSM to confirm both. Until Global-e completes that enablement, GaranImageURL stays null in every payload even when the metafield is populated.

What if the URL breaks?

That attachment is skipped and logged. The order and confirmation email are unaffected.

Does checkout use SendCart?

On this adapter, checkout coverage is GetCart. You do not set a separate SendCart field in BigCommerce.

​One-time setup

​Per variant

​When the value syncs

​Prerequisites

​Delivery paths

​Platform notes

​Payload reference

​Verify

​FAQ

One-time setup

Per variant

When the value syncs

Prerequisites

Delivery paths

Platform notes

Payload reference

Verify

FAQ