Checkout API

Redirect customers to secure hosted checkout

The Checkout API redirects customers to Shoppex’s hosted checkout page. The checkout is fully hosted by Shoppex for PCI compliance.

checkout

Redirects the customer to the checkout page with their cart contents.

await shoppex.checkout();

Parameters

coupon · string

Pre-applied coupon code

options · CheckoutOptions

Show CheckoutOptions

autoRedirect · boolean · default: "true"

Automatically redirect to checkout page

locale · string

Override checkout language

Example: Checkout with Coupon

const couponCode = document.getElementById('coupon-input').value;

if (couponCode) {
  // Validate coupon first
  const { data } = await shoppex.validateCoupon(couponCode);

  if (!data.valid) {
    alert('Invalid coupon code');
    return;
  }
}

// Proceed to checkout
await shoppex.checkout(couponCode);

buildCheckoutUrl

Builds the checkout URL without redirecting. Useful for opening in a new tab or iframe.

const checkoutUrl = await shoppex.buildCheckoutUrl('SAVE10', { locale: 'de' });
console.log(checkoutUrl);
// https://yourstore.shoppex.io/checkout?coupon=SAVE10&locale=de&cart=...

Parameters

coupon · string

Coupon code to pre-apply

locale · string

Checkout language (e.g., ‘en’, ‘de’, ‘fr’)

Example: Open Checkout in New Tab

async function openCheckoutInNewTab() {
  const url = await shoppex.buildCheckoutUrl();
  window.open(url, '_blank');
}

buildCheckoutUrlSync (Deprecated)

buildCheckoutUrlSync is deprecated and throws immediately. Use buildCheckoutUrl() instead — it handles both default and custom domains.

Coupons

validateCoupon

Validates a coupon code before checkout. Affiliate/referral codes are separate from coupons and should use validateAffiliateCode or applyAffiliateCode.

const { data } = await shoppex.validateCoupon('SAVE10', {
  productId: 'prod_abc123',
  variantId: 'variant_lifetime',
});

if (data.valid) {
  console.log('Discount:', data.discount, data.discount_type);
  // 10, "percentage" → 10% off
  // 5.00, "fixed" → $5 off
} else {
  console.log('Invalid or expired coupon');
}

Parameters

code · string · required

Coupon code to validate

options.productId · string

Product ID to check product-specific coupons

options.variantId · string

Selected variant ID to check variant-specific coupons. Requires options.productId.

Response

data · CouponValidation

Show CouponValidation

valid · boolean

Whether the coupon is valid

discount · number

Discount amount

discount_type · string

Either “percentage” or “fixed”

product_restricted · boolean

Whether the coupon is restricted to selected products

variant_restricted · boolean

Whether the coupon is restricted to selected variants

restriction_scope · string

One of “all”, “products”, “variants”, or “products_and_variants”

allowed_product_ids · string[]

Public product IDs the coupon can apply to

allowed_variant_ids · string[]

Variant IDs the coupon can apply to

Affiliate Codes

validateAffiliateCode

Validates an affiliate/referral code without storing it.

const result = await shoppex.validateAffiliateCode('creator10');

if (result.success && result.data.valid) {
  console.log(result.data.affiliate_code);
} else if (result.data?.program_enabled === false) {
  console.log('Affiliate program is disabled for this shop');
}

applyAffiliateCode

Validates and stores the normalized affiliate code. checkout() sends the stored code as affiliate_code.

const affiliate = await shoppex.applyAffiliateCode('creator10');

await shoppex.checkout({
  coupon: 'SAVE10',
  affiliateCode: affiliate.data?.affiliate_code,
});

Example: Coupon Input with Validation

<div class="coupon-form">
  <input type="text" id="coupon-input" placeholder="Enter coupon code">
  <button onclick="applyCoupon()">Apply</button>
  <span id="coupon-status"></span>
</div>

<script>
let appliedCoupon = null;

async function applyCoupon() {
  const code = document.getElementById('coupon-input').value.trim();
  const status = document.getElementById('coupon-status');

  if (!code) {
    status.textContent = '';
    return;
  }

  const { data } = await shoppex.validateCoupon(code);

  if (data.valid) {
    appliedCoupon = code;
    if (data.discount_type === 'percentage') {
      status.textContent = `${data.discount}% off applied!`;
    } else {
      status.textContent = `$${data.discount} off applied!`;
    }
    status.className = 'success';
  } else {
    appliedCoupon = null;
    status.textContent = 'Invalid coupon';
    status.className = 'error';
  }
}

async function goToCheckout() {
  await shoppex.checkout(appliedCoupon);
}
</script>

Checkout Flow

┌─────────────────────────────────────────────────────────────────┐
│                        Your Website                             │
├─────────────────────────────────────────────────────────────────┤
│  1. Customer browses products                                   │
│  2. Adds items to cart (SDK stores in localStorage)            │
│  3. Clicks "Checkout"                                          │
│  4. SDK calls shoppex.checkout()                      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Shoppex Checkout                            │
│                   (yourstore.shoppex.io)                        │
├─────────────────────────────────────────────────────────────────┤
│  5. Customer enters email, billing info                        │
│  6. Selects payment method (Stripe, PayPal, Crypto)           │
│  7. Completes payment                                          │
│  8. Receives confirmation + delivery                           │
└─────────────────────────────────────────────────────────────────┘

After Checkout

After successful checkout, the cart is automatically cleared. If you need to handle the return:

// Check URL for order confirmation
const urlParams = new URLSearchParams(window.location.search);
const orderId = urlParams.get('order');

if (orderId) {
  // Customer returned from successful checkout
  showOrderConfirmation(orderId);
}

---

Next Steps

Cart API

Manage shopping cart items before checkout

Webhooks Guide

Get notified when orders are paid or cancelled