Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt

Use this file to discover all available pages before exploring further.

The Headless Checkout SDK is for merchants who want a fully custom checkout page on their own domain. You own the layout, fields, and buyer experience. Shoppex still creates the invoice, starts the payment session, handles 3DS or redirects, receives webhooks, and fulfills the order. Use this when the hosted checkout page or modal embed is not flexible enough.
Headless checkout requires an active Business plan.

​
What You Need

  • A storefront or app page on your own domain.
  • An active Business plan.
  • A headless checkout publishable key from the dashboard.
  • At least one allowed origin for the site that will call the browser API.
  • @shoppexio/checkout-js installed in your frontend app.

​
Dashboard Setup

Open Dashboard -> Settings -> Developer -> Headless Checkout.
1

Generate a publishable key

Click Generate key. Copy the pk_live_... key immediately. The full key is shown only once.
2

Add your storefront origin

Add the exact origin that hosts your checkout page, for example https://yourstore.com.
3

Add local development origins

For local testing, add the exact local origin too, for example http://localhost:3000.
An origin is only the scheme, host, and optional port. Do not include a path.
URL you pasteSaved origin
https://vyy.gg/checkouthttps://vyy.gg
https://www.vyy.gghttps://www.vyy.gg
http://localhost:3000/carthttp://localhost:3000
If your site works on both https://vyy.gg and https://www.vyy.gg, add both origins.
Never put a secret shx_... API key in browser code. Headless checkout uses pk_live_... or pk_test_... publishable keys only.

​
Install

npm install @shoppexio/checkout-js
# or
bun add @shoppexio/checkout-js

​
React Example

import {
  ShoppexCheckoutProvider,
  useCheckoutSession,
  useStripePaymentSession,
  ShoppexPoweredBy,
} from '@shoppexio/checkout-js/headless/react';

function CheckoutForm() {
  const { session, loading, error } = useCheckoutSession({
    product_id: 'PROD_123',
    email: '[email protected]',
    quantity: 1,
  });

  const stripe = useStripePaymentSession(session?.id, {
    returnUrl: 'https://yourstore.com/thanks',
  });

  if (loading) return <p>Preparing checkout...</p>;
  if (error) return <p>{error.message}</p>;
  if (!session) return null;

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        void stripe.confirm();
      }}
    >
      <h1>{session.product?.title ?? 'Checkout'}</h1>
      <p>Total: {session.breakdown.total} {session.currency}</p>

      <div ref={stripe.mountRef} />

      <button type="submit" disabled={!stripe.ready}>
        Pay now
      </button>

      <ShoppexPoweredBy />
    </form>
  );
}

export default function Page() {
  return (
    <ShoppexCheckoutProvider publishableKey="pk_live_your_key_here">
      <CheckoutForm />
    </ShoppexCheckoutProvider>
  );
}
ShoppexPoweredBy is required unless your account has a server-side white-label entitlement. The SDK checks that the badge is visible before payment confirmation.

​
API Shape

The browser SDK sends the publishable key in the x-shoppex-publishable-key header. Shoppex also checks the request Origin header against your allowed origins. The SDK can:
  • create a checkout session
  • read the current session status
  • apply or remove coupons
  • set tips
  • select add-ons
  • start a gateway payment session
  • fetch delivery after the payment is complete
The session response includes line items, totals, available payment gateways, shop branding, terms, and delivery state. Render against the gateway kind, not the provider name, so your UI works across card, redirect, crypto, balance, and manual payment flows.

​
Troubleshooting

​
Generate key fails

Check these first:
  • The shop has an active Business plan.
  • You are using the shop owner account or a team member with permission to manage webhooks/developer settings.
  • Your dashboard session is fresh. Refresh the page or log out and back in.
If it still fails, open browser DevTools -> Network and inspect: 
POST /v1/dashboard/checkout/headless/rotate-key
Common responses:
StatusMeaning
403 BUSINESS_PLAN_REQUIREDThe shop is not on an active Business plan.
401The dashboard session or shop permission is invalid.
500Backend or database issue. Contact support with the request id if available.

​
Add origin fails

Use a full http:// or https:// origin. These are valid: 
https://vyy.gg
https://www.vyy.gg
http://localhost:3000
These should not be saved as origins: 
vyy.gg
https://vyy.gg/checkout
ftp://vyy.gg
The dashboard normalizes paths away before saving, but the backend still rejects non-http origins and malformed values. Inspect this request if the UI only shows a generic error: 
PUT /v1/dashboard/checkout/headless/origins

​
Browser API calls fail

Check the browser response code:
StatusMeaning
401Missing, malformed, or unknown publishable key. Make sure it starts with pk_live_ or pk_test_.
403 ORIGIN_NOT_ALLOWEDThe calling site’s origin is not in the allowed origins list.
403 BUSINESS_PLAN_REQUIREDHeadless checkout is not enabled for the shop’s current plan.

Headless Commerce Overview

Pick the right integration shape for custom storefronts, apps, and backend flows.

Checkout Embed SDK

Use the hosted modal when you do not need a fully custom checkout UI.

Storefront SDK

Read public product, cart, and storefront data from browser code.

Webhooks

Fulfill orders and update your app after Shoppex receives payment events.