brainerce 1.37.2 → 1.37.3

package/README.md

@@ -2050,8 +2050,11 @@ const checkout = await client.createCheckout({
 ```
 
 > The region is recorded on the checkout and used for payment-provider scoping.
-> Currency continues to follow the cart until FX price conversion lands, so
-> passing a `regionId` does not re-price the cart.
+> **FX-at-checkout:** when the region currency differs from the store base and its
+> provider can settle it (presentment-enabled — Stripe today), the buyer is charged
+> in the region currency and the checkout response carries a `presentment` overlay
+> (`presentment.total` / `presentment.currency` = what's charged). Otherwise the
+> checkout is charged in the store base currency.
 
 #### Region display pricing (`getProducts({ regionId })`)
 
@@ -3638,8 +3641,10 @@ const { region: resolved } = await store.getAutoRegion('DE'); // server-side, on
 
 > **Multi-region checkout:** pass a `regionId` to `createCheckout` to associate the
 > checkout with a region (for reporting + payment-provider scoping). The region
-> must belong to the store. Currency still follows the cart until FX price
-> conversion lands. See the Checkout section.
+> must belong to the store. **FX-at-checkout:** presentment-enabled regions
+> (Stripe today) charge in the region currency and return a `presentment` overlay;
+> otherwise the checkout is charged in the store base currency. See the Checkout
+> section.
 
 ### Price Lists (per-region pricing)
 

package/dist/index.d.mts

@@ -2507,8 +2507,11 @@ interface Checkout {
     currency: string;
     /**
      * Region this checkout is associated with (multi-region commerce), or null.
-     * Recorded for reporting + provider scoping; currency follows the cart until
-     * FX price conversion lands.
+     * Recorded for reporting + provider scoping. FX-at-checkout: when the region
+     * currency differs from the store base and its provider can settle it
+     * (presentment-enabled — Stripe today), the buyer is charged in the region
+     * currency and the `presentment` overlay below carries the charged amounts;
+     * otherwise the checkout is charged in the store base currency.
      */
     regionId?: string | null;
     /** Subtotal as string - use parseFloat() */
@@ -2560,6 +2563,41 @@ interface Checkout {
      * @see ReservationInfo
      */
     reservation?: ReservationInfo;
+    /**
+     * FX-at-checkout presentment overlay. Present ONLY when the checkout's region
+     * uses a different currency from the store base AND that region charges in its
+     * own currency (presentment). These are the amounts the buyer will actually be
+     * CHARGED, in `presentment.currency` — `presentment.total` equals the payment
+     * intent amount to the cent. Render these (not the base `total`/`currency`
+     * above) when present. Absent = the checkout is charged in the store base
+     * currency (the fields above are authoritative).
+     *
+     * @example
+     * const c = await client.getCheckout(id);
+     * const shown = c.presentment
+     *   ? formatPrice(c.presentment.total, { currency: c.presentment.currency })
+     *   : formatPrice(c.total, { currency: c.currency });
+     */
+    presentment?: {
+        /** ISO-4217 currency the buyer is charged in (e.g. "EUR"). */
+        currency: string;
+        /** Subtotal in the presentment currency as string - use parseFloat(). */
+        subtotal: string;
+        /** Discount amount in the presentment currency as string. */
+        discountAmount: string;
+        /** Shipping cost in the presentment currency as string. */
+        shippingAmount: string;
+        /** Tax amount in the presentment currency as string. */
+        taxAmount: string;
+        /** Surcharge amount in the presentment currency as string. */
+        surchargeAmount: string;
+        /** Grand total in the presentment currency — equals the charged amount. */
+        total: string;
+        /** Base→presentment rate applied (buffer included), as string. */
+        fxChargingRate: string;
+        /** FX buffer percent applied to the mid-market rate, as string (or null). */
+        fxBufferPercent: string | null;
+    };
 }
 /**
  * Options for creating a checkout from a cart.

package/dist/index.d.ts

@@ -2507,8 +2507,11 @@ interface Checkout {
     currency: string;
     /**
      * Region this checkout is associated with (multi-region commerce), or null.
-     * Recorded for reporting + provider scoping; currency follows the cart until
-     * FX price conversion lands.
+     * Recorded for reporting + provider scoping. FX-at-checkout: when the region
+     * currency differs from the store base and its provider can settle it
+     * (presentment-enabled — Stripe today), the buyer is charged in the region
+     * currency and the `presentment` overlay below carries the charged amounts;
+     * otherwise the checkout is charged in the store base currency.
      */
     regionId?: string | null;
     /** Subtotal as string - use parseFloat() */
@@ -2560,6 +2563,41 @@ interface Checkout {
      * @see ReservationInfo
      */
     reservation?: ReservationInfo;
+    /**
+     * FX-at-checkout presentment overlay. Present ONLY when the checkout's region
+     * uses a different currency from the store base AND that region charges in its
+     * own currency (presentment). These are the amounts the buyer will actually be
+     * CHARGED, in `presentment.currency` — `presentment.total` equals the payment
+     * intent amount to the cent. Render these (not the base `total`/`currency`
+     * above) when present. Absent = the checkout is charged in the store base
+     * currency (the fields above are authoritative).
+     *
+     * @example
+     * const c = await client.getCheckout(id);
+     * const shown = c.presentment
+     *   ? formatPrice(c.presentment.total, { currency: c.presentment.currency })
+     *   : formatPrice(c.total, { currency: c.currency });
+     */
+    presentment?: {
+        /** ISO-4217 currency the buyer is charged in (e.g. "EUR"). */
+        currency: string;
+        /** Subtotal in the presentment currency as string - use parseFloat(). */
+        subtotal: string;
+        /** Discount amount in the presentment currency as string. */
+        discountAmount: string;
+        /** Shipping cost in the presentment currency as string. */
+        shippingAmount: string;
+        /** Tax amount in the presentment currency as string. */
+        taxAmount: string;
+        /** Surcharge amount in the presentment currency as string. */
+        surchargeAmount: string;
+        /** Grand total in the presentment currency — equals the charged amount. */
+        total: string;
+        /** Base→presentment rate applied (buffer included), as string. */
+        fxChargingRate: string;
+        /** FX buffer percent applied to the mid-market rate, as string (or null). */
+        fxBufferPercent: string | null;
+    };
 }
 /**
  * Options for creating a checkout from a cart.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "1.37.2",
+  "version": "1.37.3",
   "description": "Official SDK for building e-commerce storefronts with Brainerce Platform. Perfect for vibe-coded sites, AI-built stores (Cursor, Lovable, v0), and custom storefronts.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",