create-cartbase 0.1.0 → 0.1.2

package/template/app/docs/variables.md

@@ -0,0 +1,315 @@
+<!-- GENERATED FILE. Do not edit by hand.
+     Source: src/lib/variables/catalog.ts
+     Regenerate: bun x tsx scripts/generate-variables-doc.ts
+     Guarded by: tests/docs/variables-doc.test.ts -->
+
+# Variables
+
+Every value a store can put into a notification, a document or a page, as a
+named token. Write `{{ order.total }}` and the store fills in the amount, in
+its own currency, formatted the way the rest of the platform formats money.
+There are 122 of them across 15 scopes, and this page is generated
+from the same catalog the renderer resolves from, so it cannot drift.
+
+## Syntax
+
+Dotted paths, the shape Shopify and Klaviyo both use, so what you already
+know transfers:
+
+```liquid
+Hi {{ customer.first_name }}, order {{ order.number }} is on its way.
+Total {{ order.total }} including {{ order.tax }} VAT.
+Track it: {{ delivery.tracking_number }}
+```
+
+Whitespace inside the braces is optional. A variable the store cannot answer
+renders as nothing, never as the raw `{{ ... }}`: a customer must never see
+template syntax.
+
+## Two rules worth knowing
+
+**The platform formats, you place.** Money carries the order's currency,
+dates carry the platform's date format, statuses carry the same words the
+admin shows ("Unpaid", "Partially shipped"). You never format a value
+yourself, and the same amount looks identical in an email, on an invoice and
+in an API response.
+
+**Product names, not column names.** The token is `{{ order.number }}`, and
+it resolves to the store's own order number when the store has one. Database
+column names never appear here.
+
+## Scopes
+
+A scope is a group of related variables. Which ones a given notification
+carries depends on what that notification is about: an order confirmation
+carries the order, the customer, both addresses, the delivery and the store,
+while a purchase order carries the purchase order, the supplier and the
+store.
+
+### Order
+
+Every customer notification carries it. Money is formatted in the order's own currency.
+
+| Variable | What it is | Format | Also accepts |
+|---|---|---|---|
+| `{{ order.number }}` | The number the customer sees. The store's own number when it has one, otherwise the platform sequence. | text | `{{display_id}}`, `{{order_number}}` |
+| `{{ order.id }}` | Internal identifier. Useful in links and API calls, not in customer copy. | text |  |
+| `{{ order.url }}` | Link to the customer's own order page. Built per store and per order: the store's custom domain when it has one, otherwise its Cartbase address. | url | `{{order_url}}` |
+| `{{ order.email }}` | The address the order was placed with. | email |  |
+| `{{ order.date }}` | When the order was placed. | date |  |
+| `{{ order.status }}` | Lifecycle state: pending, completed, canceled or archived. | text |  |
+| `{{ order.payment_status }}` | Paid, Awaiting payment, Refunded and so on, in the same words the admin uses. | text |  |
+| `{{ order.fulfillment_status }}` | Unfulfilled, Shipped, Delivered and so on, in the same words the admin uses. | text |  |
+| `{{ order.locale }}` | Language the customer shopped in, when the storefront sends one. | text |  |
+| `{{ order.cancelled_at }}` | When the order was cancelled, if it was. | datetime |  |
+| `{{ order.item_count }}` | Total number of units in the order. | number |  |
+| `{{ order.currency }}` | Currency code the order was placed in. | text |  |
+| `{{ order.total }}` | What the customer pays, everything included. | money | `{{order_total}}`, `{{total}}` |
+| `{{ order.subtotal }}` | Items only, before tax, shipping and discounts. | money |  |
+| `{{ order.tax }}` | Total tax on the order. | money |  |
+| `{{ order.shipping }}` | What delivery cost the customer. | money |  |
+| `{{ order.discount }}` | Total discount applied to the order. | money |  |
+| `{{ order.payment_method_fee }}` | The fee of the payment method the customer chose (a COD courier fee, a handling fee on a manual method). | money |  |
+| `{{ order.paid }}` | How much has actually been captured so far. | money |  |
+| `{{ order.refunded }}` | How much has been refunded. | money |  |
+| `{{ order.balance_due }}` | What is still outstanding on the order. | money |  |
+
+### Customer
+
+The email address is the customer's identity here, so every order carries a customer. Names fall back to the shipping then the billing address.
+
+| Variable | What it is | Format | Also accepts |
+|---|---|---|---|
+| `{{ customer.name }}` | Full name of the customer. | text | `{{customer_name}}` |
+| `{{ customer.first_name }}` | First name on its own, for a greeting. | text |  |
+| `{{ customer.last_name }}` | Last name on its own. | text |  |
+| `{{ customer.email }}` | The customer's email address, which is their identity here. | email |  |
+| `{{ customer.phone }}` | Phone number on the customer record. | text |  |
+| `{{ customer.company }}` | Company name for business customers. | text |  |
+| `{{ customer.vat_number }}` | VAT number for business customers, needed on invoices. | text |  |
+| `{{ customer.eik }}` | Bulgarian EIK for business customers. | text |  |
+| `{{ customer.tags }}` | Tags on the customer, comma separated. | text |  |
+
+### Shipping address
+
+Every field individually, plus a one-line `formatted` version.
+
+| Variable | What it is | Format | Also accepts |
+|---|---|---|---|
+| `{{ shipping_address.formatted }}` | The whole address on one line, ready to drop into a sentence. | text |  |
+| `{{ shipping_address.name }}` | Recipient's full name. | text |  |
+| `{{ shipping_address.first_name }}` | Recipient's first name. | text |  |
+| `{{ shipping_address.last_name }}` | Recipient's last name. | text |  |
+| `{{ shipping_address.company }}` | Company on the address, when given. | text |  |
+| `{{ shipping_address.line_1 }}` | Street and number. | text |  |
+| `{{ shipping_address.line_2 }}` | Apartment, floor, or extra detail. | text |  |
+| `{{ shipping_address.city }}` | City or town. | text |  |
+| `{{ shipping_address.province }}` | Province, region or state. | text |  |
+| `{{ shipping_address.postal_code }}` | Postal code. | text |  |
+| `{{ shipping_address.country }}` | Two-letter country code. | text |  |
+| `{{ shipping_address.phone }}` | Phone number on the address. | text |  |
+
+### Billing address
+
+The same field set as the shipping address.
+
+| Variable | What it is | Format | Also accepts |
+|---|---|---|---|
+| `{{ billing_address.formatted }}` | The whole address on one line, ready to drop into a sentence. | text |  |
+| `{{ billing_address.name }}` | Recipient's full name. | text |  |
+| `{{ billing_address.first_name }}` | Recipient's first name. | text |  |
+| `{{ billing_address.last_name }}` | Recipient's last name. | text |  |
+| `{{ billing_address.company }}` | Company on the address, when given. | text |  |
+| `{{ billing_address.line_1 }}` | Street and number. | text |  |
+| `{{ billing_address.line_2 }}` | Apartment, floor, or extra detail. | text |  |
+| `{{ billing_address.city }}` | City or town. | text |  |
+| `{{ billing_address.province }}` | Province, region or state. | text |  |
+| `{{ billing_address.postal_code }}` | Postal code. | text |  |
+| `{{ billing_address.country }}` | Two-letter country code. | text |  |
+| `{{ billing_address.phone }}` | Phone number on the address. | text |  |
+
+### Delivery
+
+Reads the order's most recent live fulfillment and its first label.
+
+| Variable | What it is | Format | Also accepts |
+|---|---|---|---|
+| `{{ delivery.method }}` | The shipping option the customer chose, in the merchant's own words. | text |  |
+| `{{ delivery.price }}` | What the chosen delivery method cost. | money |  |
+| `{{ delivery.carrier }}` | The courier carrying the parcel. | text |  |
+| `{{ delivery.tracking_number }}` | Waybill number the customer can track. | text | `{{tracking_number}}` |
+| `{{ delivery.tracking_url }}` | Direct link to the courier's tracking page for this parcel. | url |  |
+| `{{ delivery.pickup_location }}` | Courier office or locker the customer chose. | text |  |
+| `{{ delivery.shipped_at }}` | When the parcel left the store. | datetime |  |
+| `{{ delivery.delivered_at }}` | When the courier delivered the parcel. | datetime |  |
+
+### Store
+
+The store's public identity. `store.email` is the address a reply reaches.
+
+| Variable | What it is | Format | Also accepts |
+|---|---|---|---|
+| `{{ store.name }}` | The store's name. | text | `{{store_name}}` |
+| `{{ store.url }}` | Link to the storefront: the custom domain when there is one. | url |  |
+| `{{ store.email }}` | Where customers reach the store. The sender address when set, otherwise the owner's account email. | email | `{{support_email}}` |
+| `{{ store.address }}` | Registered address of the business. | text |  |
+| `{{ store.vat_number }}` | The business VAT number. | text |  |
+| `{{ store.eik }}` | Bulgarian EIK of the business. | text |  |
+| `{{ store.iban }}` | Bank account customers pay into. | text |  |
+
+### Brand
+
+| Variable | What it is | Format | Also accepts |
+|---|---|---|---|
+| `{{ brand.logo_url }}` | The store's primary logo image URL, for <img> tags. | url |  |
+| `{{ brand.logo_square_url }}` | The square logo mark image URL, for compact placements. | url |  |
+| `{{ brand.color_primary }}` | The brand's primary color as #rrggbb, for inline styles. | text |  |
+| `{{ brand.color_secondary }}` | The brand's secondary color as #rrggbb, for inline styles. | text |  |
+| `{{ brand.slogan }}` | The store's slogan or tagline. | text |  |
+
+### Cart
+
+For abandoned-cart flows. Supplied by the caller, not by an order.
+
+| Variable | What it is | Format | Also accepts |
+|---|---|---|---|
+| `{{ cart.id }}` | Identifier of the customer's cart. | text |  |
+| `{{ cart.total }}` | What is in the cart, priced. | money |  |
+| `{{ cart.item_count }}` | How many units are in the cart. | number |  |
+
+### Document
+
+Read from the document's frozen snapshot, never from the live order, because orders change and documents must not.
+
+| Variable | What it is | Format | Also accepts |
+|---|---|---|---|
+| `{{ document.number }}` | Number of the invoice or other document. | text | `{{document_number}}` |
+| `{{ document.type }}` | Invoice, proforma, dispatch note or handover protocol. | text | `{{document_type}}` |
+| `{{ document.date }}` | Date the document was issued. | date |  |
+| `{{ document.url }}` | Link to download the PDF. | url |  |
+| `{{ document.currency }}` | Currency the document is issued in. | text |  |
+| `{{ document.payment_method }}` | How the document says payment is made. | text |  |
+| `{{ document.due_date }}` | When the invoice is due. | date |  |
+| `{{ document.outstanding }}` | How much of the invoice is still unpaid. | money |  |
+| `{{ document.paid_at }}` | When the invoice was settled. | datetime |  |
+| `{{ document.voided_at }}` | When the document was voided, if it was. | datetime |  |
+| `{{ document.issuer.name }}` | Legal name of the issuer. | text |  |
+| `{{ document.issuer.address }}` | Registered address of the issuer. | text |  |
+| `{{ document.issuer.eik }}` | Bulgarian EIK / company registration number. | text |  |
+| `{{ document.issuer.vat_number }}` | VAT registration number. | text |  |
+| `{{ document.issuer.mol }}` | Materially responsible person (Bulgarian invoicing). | text |  |
+| `{{ document.issuer.iban }}` | Bank account for payment. | text |  |
+| `{{ document.recipient.name }}` | Legal name of the recipient. | text |  |
+| `{{ document.recipient.address }}` | Registered address of the recipient. | text |  |
+| `{{ document.recipient.eik }}` | Bulgarian EIK / company registration number. | text |  |
+| `{{ document.recipient.vat_number }}` | VAT registration number. | text |  |
+| `{{ document.recipient.mol }}` | Materially responsible person (Bulgarian invoicing). | text |  |
+| `{{ document.recipient.iban }}` | Bank account for payment. | text |  |
+| `{{ document.totals.subtotal }}` | Line items on the document, before tax. | money |  |
+| `{{ document.totals.discount }}` | Discount on the document. | money |  |
+| `{{ document.totals.shipping }}` | Shipping on the document. | money |  |
+| `{{ document.totals.tax }}` | Tax on the document. | money |  |
+| `{{ document.totals.tax_rate_percent }}` | Effective VAT percentage shown on the document. | percent |  |
+| `{{ document.totals.total }}` | The amount the document is for. | money |  |
+
+### Purchase order
+
+| Variable | What it is | Format | Also accepts |
+|---|---|---|---|
+| `{{ purchase_order.number }}` | Number of the purchase order sent to a supplier. | text | `{{po_number}}` |
+| `{{ purchase_order.status }}` | Where the purchase order stands. | text |  |
+| `{{ purchase_order.total }}` | Value of the purchase order. | money |  |
+| `{{ purchase_order.expected_at }}` | When the goods are expected. | date |  |
+
+### Supplier
+
+| Variable | What it is | Format | Also accepts |
+|---|---|---|---|
+| `{{ supplier.name }}` | Name of the supplier the purchase order goes to. | text | `{{supplier_name}}` |
+| `{{ supplier.email }}` | Where the purchase order is sent. | email |  |
+| `{{ supplier.phone }}` | Supplier phone number. | text |  |
+
+### Review
+
+| Variable | What it is | Format | Also accepts |
+|---|---|---|---|
+| `{{ review.url }}` | Link to the review form for this order. | url |  |
+| `{{ review.product_title }}` | The product being reviewed. | text | `{{product_title}}` |
+| `{{ review.reward_percentage }}` | Discount percentage earned for leaving a review. | number | `{{reward_percentage}}` |
+| `{{ review.reward_code }}` | The single-use discount code earned for a review. | text | `{{reward_code}}` |
+
+### Gift card
+
+The amount only. The card CODE is never a variable: it renders as a fixed block so an edited template cannot drop it or leak it.
+
+| Variable | What it is | Format | Also accepts |
+|---|---|---|---|
+| `{{ gift_card.amount }}` | Value loaded on the gift card. | money | `{{gift_card_amount}}` |
+| `{{ gift_card.expires_at }}` | When the gift card stops working, if it expires. | date |  |
+
+### Subscription
+
+| Variable | What it is | Format | Also accepts |
+|---|---|---|---|
+| `{{ subscription.plan_name }}` | The subscription plan the customer is on. | text | `{{plan_name}}` |
+| `{{ subscription.next_charge_date }}` | When the subscription renews next. | text | `{{next_charge_date}}` |
+
+### Alert
+
+Staff operational alerts only.
+
+| Variable | What it is | Format | Also accepts |
+|---|---|---|---|
+| `{{ alert.title }}` | Headline of the operational alert. | text | `{{alert_title}}` |
+| `{{ alert.detail }}` | What the system check found. | text |  |
+
+## What each notification carries
+
+| Notification | Scopes |
+|---|---|
+| Order Confirmation | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
+| Order Shipped | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
+| Order Delivered | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
+| Order Refunded | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
+| Order Cancelled | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
+| Admin: New Order | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
+| Welcome Email | Customer, Store, Brand |
+| Password Reset | Customer, Store, Brand |
+| Document Issued | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand, Document |
+| Sign-in Code | Customer, Store, Brand |
+| B2B Account Approved | Customer, Store, Brand |
+| Review Request | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand, Review |
+| Review Reward Code | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand, Review |
+| Out for Delivery | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
+| Ready for Pickup | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
+| Picked Up | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
+| Econt Office Reminder (Day 3) | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
+| Econt Office Reminder (Day 5) | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
+| Admin: System Alert | Alert, Store, Brand |
+| Gift Card Delivery | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand, Gift card |
+| Purchase Order | Purchase order, Supplier, Store, Brand |
+| Subscription: Upcoming Renewal | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand, Subscription |
+| Subscription: Payment Failed | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand, Subscription |
+| Subscription: Paused | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand, Subscription |
+| Subscription: Canceled | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand, Subscription |
+
+Writing a variable from a scope the notification does not carry is refused
+when you save it, with the reason, rather than rendering as a blank in a real
+customer's inbox.
+
+## Not available yet
+
+These are real product gaps, listed so they are visible rather than promised.
+They are not offered in the editor and cannot be saved into a template.
+
+| Variable | What it would be | What is missing |
+|---|---|---|
+| `{{ order.note }}` | The note the customer left with their order. | not collected yet |
+| `{{ store.phone }}` | The number customers can call. | no column yet |
+| `{{ cart.url }}` | Link that puts the customer back in their abandoned cart. | storefront cart recovery route plus the cart id |
+
+## Never variables
+
+The **gift card code** and the **sign-in code** render as fixed blocks and
+are deliberately not tokens. An edited template must not be able to drop them
+(the customer loses their code) or move them somewhere they leak.

package/template/app/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/dev/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/template/app/next.config.ts

@@ -15,12 +15,12 @@ const nextConfig: NextConfig = {
     // A real store should allowlist its media domain via remotePatterns.
     unoptimized: true,
   },
-  // The barter store API ships NO CORS headers — browser-side SDK calls
+  // The Cartbase store API ships NO CORS headers — browser-side SDK calls
   // must be same-origin. Proxy them through the app origin (the browser
   // client's baseUrl is window.location.origin); server-side SDK calls go
-  // straight to NEXT_PUBLIC_BARTER_URL and are unaffected.
+  // straight to NEXT_PUBLIC_CARTBASE_URL and are unaffected.
   async rewrites() {
-    const barterUrl = process.env.NEXT_PUBLIC_BARTER_URL
+    const barterUrl = process.env.NEXT_PUBLIC_CARTBASE_URL
     if (!barterUrl) return []
     return [
       {

package/template/app/package.json

@@ -8,7 +8,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@cartbase/storefront": "^0.1.0",
+    "@cartbase/storefront": "^0.3.0",
     "next": "16.2.4",
     "react": "19.2.4",
     "react-dom": "19.2.4"

package/template/app/smoke.mjs

@@ -106,7 +106,7 @@ try {
   const codTab = page.getByRole("button", { name: "Cash on delivery" })
   await codTab.waitFor({ state: "visible" })
   await codTab.click()
-  step("selected manual payment (pp_manual offline tab)")
+  step("selected the merchant method (offline tab)")
 
   // ── Place order ─────────────────────────────────────────────────────
   const submit = page.getByTestId("submit-order-button")

package/template/app/src/app/checkout/checkout-page-client.tsx

@@ -3,11 +3,11 @@
 import { useRouter } from "next/navigation"
 import type { Cart } from "@cartbase/storefront/api/carts"
 import type { StoreShippingOption } from "@cartbase/storefront/api/checkout"
-import type { StorePaymentProvider } from "@cartbase/storefront/api/checkout"
-import type { PublicCodConfig } from "@cartbase/storefront/api/integrations"
+import type { StorePaymentEntry } from "@cartbase/storefront/api/checkout"
 import { CheckoutProvider } from "@cartbase/storefront/checkout/context"
 import { CheckoutClient } from "@cartbase/storefront/checkout/checkout-client"
 import { browserClient } from "@/lib/browser-client"
+import { MyposDemoTab } from "./mypos-demo-tab"
 
 /** sessionStorage key the confirmation page reads (guests have no order
  * read endpoint — the completeCart() response is the only order handle,
@@ -18,12 +18,10 @@ export function CheckoutPageClient({
   cart,
   shippingOptions,
   paymentProviders,
-  codConfig,
 }: {
   cart: Cart
   shippingOptions: StoreShippingOption[]
-  paymentProviders: StorePaymentProvider[]
-  codConfig: PublicCodConfig | null
+  paymentProviders: StorePaymentEntry[]
 }) {
   const router = useRouter()
 
@@ -38,13 +36,31 @@ export function CheckoutPageClient({
         countryCode="bg"
         countries={[{ iso_2: "bg", display_name: "Bulgaria" }]}
         // Per-store rule (the documented paymentMethodFilter seam): this
-        // reference store checks out offline via pp_manual only — without
-        // the filter the hook prefers a tenant-enabled pp_cod for the
-        // offline tab.
+        // reference store checks out offline via its merchant methods only
+        // (pp_* kill: method entries carry payment_method_id, processors
+        // carry id) — the filter drops any connected processor.
         paymentMethodFilter={(methods) =>
-          methods?.filter((m) => m.id === "pp_manual") ?? null
+          methods?.filter((m) => "payment_method_id" in m) ?? null
+        }
+        // Provider-research demo (2026-08-04): the myPOS sandbox as a third
+        // radio card, so the embedded-provider seam can be judged inside
+        // the real checkout. Off unless NEXT_PUBLIC_MYPOS_DEMO=1.
+        extraPaymentTabs={
+          process.env.NEXT_PUBLIC_MYPOS_DEMO === "1"
+            ? [
+                {
+                  id: "mypos-demo",
+                  label: "Card via myPOS (demo)",
+                  content: (
+                    <MyposDemoTab
+                      amount={Number(cart.total) || 23.45}
+                      currency={cart.currency_code}
+                    />
+                  ),
+                },
+              ]
+            : undefined
         }
-        codConfig={codConfig}
         onOrderPlaced={(order) => {
           // Guest order handle = the completeCart() response (orders.md).
           // Stash it (+ the decorated cart lines for the items list) for

package/template/app/src/app/checkout/mypos-demo-tab.tsx

@@ -0,0 +1,101 @@
+"use client"
+
+import { useEffect, useRef, useState } from "react"
+
+/**
+ * DEMO ONLY (2026-08-04, provider research): mounts the myPOS Embedded
+ * sandbox (their public docs demo store) inside the real checkout's
+ * payment section, so the visual seam of a third-party embedded provider
+ * can be judged against our own tabs. Enabled by
+ * NEXT_PUBLIC_MYPOS_DEMO=1; never ship this to a real store.
+ */
+
+const SDK_SRC = "https://developers.mypos.com/repository/mypos-embedded-sdk.js"
+const CONTAINER_ID = "mypos-demo-container"
+
+declare global {
+  interface Window {
+    MyPOSEmbedded?: {
+      createPayment: (
+        containerId: string,
+        params: Record<string, unknown>,
+        callbacks: Record<string, unknown>
+      ) => void
+    }
+  }
+}
+
+export function MyposDemoTab({ amount, currency }: { amount: number; currency: string }) {
+  const mounted = useRef(false)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (mounted.current) return
+    mounted.current = true
+
+    const mount = () => {
+      const sdk = window.MyPOSEmbedded
+      if (!sdk || typeof sdk.createPayment !== "function") {
+        setError("myPOS SDK loaded but its global was not found (check the console).")
+        return
+      }
+      sdk.createPayment(
+        CONTAINER_ID,
+        {
+          // Public sandbox store from the myPOS docs sample.
+          sid: "000000000000010",
+          ipcLanguage: "en",
+          walletNumber: "61938166610",
+          amount,
+          currency: currency.toUpperCase(),
+          orderID: `demo_${Math.random().toString(36).slice(2, 11)}`,
+          urlNotify: "https://example.com/payment-notify",
+          urlOk: window.location.href,
+          urlCancel: window.location.href,
+          keyIndex: 1,
+          cartItems: [{ article: "Cartbase demo order", quantity: 1, price: amount, currency: currency.toUpperCase() }],
+        },
+        {
+          isSandbox: true,
+          onSuccess: (data: unknown) => {
+            // Real integration: this is where complete-cart would run,
+            // AFTER server-side verification via urlNotify.
+            // eslint-disable-next-line no-console
+            console.log("[mypos-demo] sandbox success", data)
+            window.alert("myPOS sandbox reported success (demo only, no order is placed).")
+          },
+          onError: () => {
+            // eslint-disable-next-line no-console
+            console.log("[mypos-demo] sandbox payment failed")
+          },
+        }
+      )
+    }
+
+    const existing = document.querySelector(`script[src="${SDK_SRC}"]`)
+    if (existing && window.MyPOSEmbedded) {
+      mount()
+      return
+    }
+    const script = document.createElement("script")
+    script.src = SDK_SRC
+    script.async = true
+    script.onload = mount
+    script.onerror = () => setError("Could not load the myPOS SDK script.")
+    document.head.appendChild(script)
+  }, [amount, currency])
+
+  return (
+    <div>
+      {error ? (
+        <p className="text-sm text-red-600">{error}</p>
+      ) : (
+        <div id={CONTAINER_ID} className="min-h-[620px]" />
+      )}
+      <p className="mt-2 text-xs text-muted-foreground">
+        myPOS sandbox demo. The frame above is myPOS's embedded form with its
+        own pay button; everything around it is the Cartbase checkout.
+      </p>
+    </div>
+  )
+}

package/template/app/src/app/checkout/page.tsx

@@ -5,8 +5,7 @@ import {
   listPaymentProviders,
   listShippingOptions,
 } from "@cartbase/storefront/api/checkout"
-import { getIntegrationsConfig } from "@cartbase/storefront/api/integrations"
-import { CART_COOKIE } from "@/lib/config"
+import { readCartCookie } from "@/lib/config"
 import { getServerClient } from "@/lib/server-client"
 import { CheckoutPageClient } from "./checkout-page-client"
 
@@ -19,7 +18,9 @@ import { CheckoutPageClient } from "./checkout-page-client"
  */
 export default async function CheckoutPage() {
   const jar = await cookies()
-  const cartId = jar.get(CART_COOKIE)?.value
+  // Back-compat: prefer `_cartbase_cart`, fall back to the legacy
+  // `_barter_cart_id` name (platform-fingerprints card).
+  const cartId = readCartCookie((name) => jar.get(name)?.value)
   if (!cartId) redirect("/")
 
   const client = await getServerClient()
@@ -29,13 +30,12 @@ export default async function CheckoutPage() {
   if (!cart || (cart.items ?? []).length === 0) redirect("/")
   if (cart.completed_at) redirect("/")
 
-  const [shippingOptions, paymentProviders, integrations] = await Promise.all([
+  const [shippingOptions, paymentProviders] = await Promise.all([
     listShippingOptions(client, { cart_id: cart.id }),
     listPaymentProviders(client, {
       cart_id: cart.id,
       region_id: cart.region_id ?? undefined,
     }),
-    getIntegrationsConfig(client),
   ])
 
   return (
@@ -43,7 +43,6 @@ export default async function CheckoutPage() {
       cart={cart}
       shippingOptions={shippingOptions.shipping_options}
       paymentProviders={paymentProviders.payment_providers}
-      codConfig={integrations.cod}
     />
   )
 }