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

# Checkout discount vouchers

Some Global-e checkout vouchers (for example a payment-method provider code) must apply an SFCC **promotion** without creating an SFCC **coupon line item**. The Global-e cartridges support that via **checkout discount vouchers**: mapped codes that set a **session custom attribute**, qualify a **dynamic customer group**, and apply a **no-coupon promotion** during Global-e checkout only.

This feature reuses the existing `Globale-Coupon` (VoucherValidation) endpoint. Unmapped codes continue to use the normal coupon-line-item path.

## Limitations

* **Percentage discounts only.** This feature works only with **percentage** discounts (SFCC percent-off promotions with Global-e `geDiscountType` = `PERCENTAGE`). Other checkout discount types (for example fixed amount / currency-off) are **not supported** by the Global-e service and must not be used for payment-method provider / checkout discount vouchers.

## Behaviour

* Shopper selects an eligible payment method (or enters a mapped voucher) on Global-e checkout → SFCC applies the mapped promotion for that `Globale-Coupon` request only and returns a new `CartToken`.
* Mapped codes do **not** create an SFCC coupon line item.
* The checkout discount (payment-method provider discount) does **not** survive a later real SFCC coupon apply/remove. When Global-e checkout reloads after voucher validation, payment-method selection is reset — the shopper must select an eligible payment method again to get the checkout discount.
* Leaving Global-e checkout for the cart (or opening checkout again from the cart without re-entering the voucher / re-selecting the PM) does **not** keep or revive the checkout discount.
* On order failover (SOTM / basket rebuilt from SendCartV2 payload), if the last SendCartV2 still carried the voucher in `UrlParameters`, it can be restored for calculate.
* Works on SFRA, SiteGenesis, and headless storefronts, using the scenario that matches each integration:
  * **SFRA / SiteGenesis** — Global-e calls `Globale-Coupon` in the shopper session (forwarded `dwsid`); the cartridge applies the mapped promotion directly on the storefront basket and calls SendCartV2. No OCAPI/SCAPI basket or coupon hooks are involved.
  * **Headless (PWA, SFNext, etc.)** — Global-e calls with a JWT (`AuthToken`) through OCAPI/SCAPI; the `int_globale_headless` basket/coupon hooks apply the promotion and refresh the cart token.

## Prerequisites

1. **Global-e platform** — the voucher / payment-method provider discount must also be configured on the Global-e side for the merchant. Contact **Global-e Merchant Support** to confirm merchant-account configuration (including settings required for checkout discount / voucher refresh behaviour).
2. **Cartridge path** that includes `int_globale` and the storefront cartridge for the integration: `int_globale_sfra` or `int_globale_sitegenesis` (shopper-session scenario), or `int_globale_headless` (JWT OCAPI/SCAPI scenario). Only `int_globale_headless` registers the OCAPI basket/coupon hooks (`beforePATCH`/`afterPATCH`, `coupon.*`) that the JWT scenario relies on; SFRA/SiteGenesis do not need them because the shopper-session scenario runs entirely in `Globale-Coupon`.
3. **Site preference** `geCheckoutDiscountVoucherMappings` configured (see below).
4. An SFCC **dynamic customer group** whose membership depends on the session attribute in the mapping.
5. An SFCC **percentage** promotion (no coupon required) assigned to that customer group, with Global-e promotion attributes set as usual (`geDiscountType` = `PERCENTAGE`). Other discount types are not supported for this feature — see [Limitations](#limitations). See [Promotions](/promotions-sfcc).
6. **SFRA / SiteGenesis only** — the shopper `dwsid` cookie must be present in the SendCartV2 `UrlParameters` (inside the `ClientCookie` entry). Global-e replays it when it calls `Globale-Coupon`, letting SFCC re-bind to the shopper session and current basket. Without `dwsid`, voucher apply/remove (and session-bound order create) fail — see [Checkout flow → Session identifiers](/checkout-flow-sfcc#session-identifiers-in-sendcartv2-sfra--sitegenesis). Headless uses the OCAPI/SCAPI JWT instead and does not need `dwsid`.

## Configuration

### 1. Site preference — Checkout Discount Voucher Mappings

**Merchant Tools → Site Preferences → Custom Site Preference Groups → Global-e Settings → Checkout Discount Voucher Mappings** (`geCheckoutDiscountVoucherMappings`)

JSON array. Empty, `null`, or invalid JSON means no mapped codes (all vouchers use the normal coupon path).

| Field | Description |
| - | - |
| `voucherCode` | Code the shopper enters on Global-e checkout (match is **case-insensitive**) |
| `sessionAttribute` | Session custom attribute name to set (e.g. `geCheckoutDiscountOnCheckout`) |
| `sessionValue` | Value to set (typically `true`) |
| `promotionId` | SFCC promotion ID that must appear as a price adjustment after apply (fail-closed check) |

Example:

```json theme={null}
[
  {
    "voucherCode": "DISCOUNT-ON-CHECKOUT",
    "sessionAttribute": "geCheckoutDiscountOnCheckout",
    "sessionValue": true,
    "promotionId": "globale-discount-on-checkout"
  }
]
```

### 2. Customer group and promotion

<Steps>
  <Step>
    Create a dynamic customer group that includes shoppers when the session attribute from the mapping is set.
  </Step>

  <Step>
    Create (or reuse) a **percentage** (percent-off) promotion that qualifies on that group — **without** requiring an SFCC coupon. Do not use amount, fixed-price, or other non-percentage discount types for this feature.
  </Step>

  <Step>
    Assign the promotion to an active campaign and set Global-e promotion custom attributes with `geDiscountType` = `PERCENTAGE`.
  </Step>

  <Step>
    Ensure `promotionId` in the mapping matches the promotion ID exactly.
  </Step>
</Steps>

### 3. Metadata

Import Global-e metadata that includes:

* Site preference `geCheckoutDiscountVoucherMappings`
* Basket attribute `geCheckoutDiscountVouchers` (used by the cartridge; merchants do not set this manually)

See [Metadata reference](/metadata-sfcc).

## Expected checkout behaviour

| Action | Result |
| - | - |
| Apply mapped voucher | `IsVoucherValid: true`, promotion price adjustment present, new `CartToken` |
| Apply mapped voucher but promotion does not apply | `IsVoucherValid: false` (fail-closed) |
| Apply or remove mapped voucher but no new `CartToken` is returned by Global-e | `IsVoucherValid: false` (fail-closed) |
| Remove mapped voucher | Discount cleared, new `CartToken` |
| Apply real SFCC coupon after payment-method checkout discount | Checkout discount is **cleared** (not revived); real coupon applies; new `CartToken`. Shopper must re-select an eligible payment method to get the checkout discount again |
| Apply a real SFCC coupon that does not qualify | `IsVoucherValid: false`, coupon line item removed, no cart refresh sent to Global-e |
| Leave Global-e checkout for the cart, then open it again without the voucher | Checkout discount **not** revived |
| Unmapped code | Normal coupon path (create/remove coupon line item) + refreshed `CartToken` |

## Notes

* SendCartV2 `UrlParameters` may carry checkout discount vouchers for **SOTM / fallback** basket rebuild when the discount-apply SendCart still had the basket attribute set. Other Global-e requests (`OrderClientCreate`, `OrderCreateV2`, `KeepAlive`, `ValidateCart`) neither apply nor validate vouchers, so they do not need the voucher session attributes.
* Only one checkout discount voucher is active at a time. Applying another mapped voucher replaces the previous one.
* On the Global-e platform, configure the matching payment-method provider / checkout discount as a **percentage** value only (for example `10%`). Non-percentage checkout discounts are not supported by the Global-e service. Confirm related merchant-account settings with **Global-e Merchant Support** before go-live.

## See also

* [Promotions](/promotions-sfcc)
* [Customer groups](/customer-groups-sfcc)
* [Session attributes](/session-attributes-sfcc)
* [Failover and recovery](/failover-sfcc)
* [Metadata reference](/metadata-sfcc)