Skip to main content

​
Checkout SDK

The COPE Checkout SDK is a browser SDK for buyer checkout flows. It lets you fetch product data, build a cart, calculate final prices, create a hosted checkout session, and either redirect the buyer to COPE checkout or mount that checkout inside your page. Use the SDK when your site owns the product page or shopping experience and COPE owns payment collection, tax calculation, order creation, and payment lifecycle events.

​
Install

npm install @copecart/sdk

import { CopeCart } from "@copecart/sdk"

const cope = new CopeCart({
  publishableKey: "cope_pk_live_...",
})
For pages without a bundler, load the global build: 
<script src="https://unpkg.com/@copecart/sdk@latest/dist/index.global.js"></script>
<script>
  const cope = new CopeCart.CopeCart({
    publishableKey: "cope_pk_live_...",
  })
</script>

​
Configuration

OptionRequiredDefaultNotes
publishableKeyYes-Business publishable key. It starts with cope_pk_ and is safe to use in browser code.
baseUrlNoCOPE production APIOverride only when COPE support gives you an environment-specific API URL.
checkoutBaseUrlNoThe baseUrl originUsed to validate checkout URLs returned by the API.
The SDK requires HTTPS except for http://localhost during development.

​
Basic redirect flow

import { CopeCart } from "@copecart/sdk"

const cope = new CopeCart({
  publishableKey: "cope_pk_live_...",
})

const product = await cope.getProduct("prd_...")
const cart = await cope.createCart({ currency: product.currency })

await cope.addLine(cart.id, {
  product_id: product.id,
  plan_id: product.payment_plans[0].id,
  quantity: 1,
})

await cope.setBuyerIdentity(cart.id, {
  email: "buyer@example.com",
  tax_location: {
    country: "DE",
    postal_code: "10115",
  },
})

await cope.reprice(cart.id)

const checkout = await cope.checkout(cart.id, {
  success_url: "https://your-site.example/thank-you",
  cancel_url: "https://your-site.example/cart",
  consents: [{ type: "buyer_tos" }],
})

cope.redirectToCheckout(checkout)
After successful payment, COPE redirects to success_url with order_id appended: 
https://your-site.example/thank-you?order_id=ord_...

​
Embedded checkout

To keep the buyer on your page, create checkout with embed_origin and mount it with mountCheckout(). 
const checkout = await cope.checkout(cart.id, {
  embed_origin: window.location.origin,
  consents: [{ type: "buyer_tos" }],
})

const mounted = cope.mountCheckout("#cope-checkout", checkout, {
  fallback: "redirect",
  onReady: () => {
    document.querySelector("#cope-checkout")?.removeAttribute("hidden")
  },
  onSuccess: () => {
    window.location.href = "/thank-you"
  },
  onError: ({ code }) => {
    console.error("COPE checkout iframe error", code)
  },
})
Read the full embedded checkout guide before launching iframe checkout. It covers registered embed origins, iframe security, postMessage events, and fallback behavior.

​
Core methods

MethodPurpose
getProduct(productId)Fetch public product details and payment plans.
createCart(payload)Create a cart and store the checkout credential needed for later cart updates.
addLine(cartId, payload)Add a product, payment plan, and quantity.
setBuyerIdentity(cartId, payload)Set buyer location and contact data for tax and checkout.
reprice(cartId)Calculate taxes, shipping, discounts, and final totals.
checkout(cartId, payload)Create a hosted checkout session.
redirectToCheckout(checkout)Navigate the browser to hosted checkout.
mountCheckout(target, checkout, options)Mount hosted checkout inside an iframe.
cancelCheckout(checkoutId)Cancel an open checkout session.
destroy()Abort in-flight requests, remove mounted iframes, and clear SDK cart state.

​
Errors

The SDK exposes typed errors: 
import {
  CopeApiError,
  CopeCartExpiredError,
  CopeNetworkError,
} from "@copecart/sdk"

try {
  await cope.reprice(cart.id)
} catch (error) {
  if (error instanceof CopeApiError) {
    console.log(error.status, error.code, error.errors)
  }

  if (error instanceof CopeCartExpiredError) {
    const replacement = await cope.createCart({ currency: "EUR" })
  }

  if (error instanceof CopeNetworkError) {
    console.log("Retry later")
  }
}
Treat 4xx API errors as permanent for the same payload. Fix the input and retry with a new request. The SDK retries selected transient network or server failures with backoff.