Region-Restricted Coupons

A coupon can be scoped to one or more regions through its regionIds field. This lets you run a promo that only applies to EU buyers, or keep a HOME10 welcome code limited to your domestic region, without minting a separate coupon per market.

A coupon's type is either PERCENTAGE or FIXED_AMOUNT, the only two values it takes. Free shipping, buy-one-get-one, tiered pricing and bundles are discount rules, not coupons, and a coupon has no customer-segment targeting: it can be scoped to products, categories and regions only. Discount rules, in turn, have no regionIds field, so restrict those by sales channel instead.

How regionIds resolves

• Empty / omitted regionIds: the coupon applies in all regions (the default; unchanged for stores that don't use regions).
• Non-empty regionIds: only buyers whose checkout resolved to a region in the list can redeem the coupon. A buyer in any other region, or a checkout with no region at all, is rejected, even if the code, dates, and minimums all match.

The check is on the checkout's region, the same region recorded for reporting and payment-provider scoping. Each id must reference a region of the same store.

Restricting a coupon (admin SDK)

storeId is derived from the API key. regionIds is accepted on both create and update; pass [] (or omit it) to clear the restriction and make the coupon valid everywhere again.

import { BrainerceClient } from 'brainerce';

const admin = new BrainerceClient({ apiKey: process.env.BRAINERCE_API_KEY });

const { data: regions } = await admin.getRegions();
const eu = regions.find((r) => r.name === 'European Union')!;

// EU-only summer promo
await admin.createCoupon({
  code: 'EUSUMMER',
  type: 'PERCENTAGE',
  value: 15,
  regionIds: [eu.id], // only buyers whose checkout region is the EU region
});

// Later: open it up to every region again
await admin.updateCoupon(couponId, { regionIds: [] });

The coupon response echoes regionIds so you can show the restriction in the dashboard or a storefront's "applies in your region" hint.

See also Regions for how a checkout resolves to a region, including the parallel region-restricted shipping that uses the same empty = all / non-empty = restricted pattern.