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
The SDK is published on npm ascope-sdk.
Cope, the class itself. It also defines the CopeCart namespace, which carries every export, for example CopeCart.CopeApiError.
These examples use
cope-sdk 0.1.8, whose class is Cope. CopeCart stays exported as a deprecated alias of the same class, so code written against 0.1.0 keeps working. 0.1.1, 0.1.2 and 0.1.3 each change some behaviour an earlier caller can notice; the package changelog (CHANGELOG.md in the npm package) lists each one under Behaviour changes.Configuration
The SDK requires HTTPS except for
http://localhost during development.
Basic redirect flow
getProduct() takes the product’s ID, which starts with prod_ — the same ID the Commerce API and the webhooks use. Pass that ID as product_id when you add a line. setBuyerIdentity() takes country (a two-letter country code such as DE) and postal_code at the top level of the payload; together they are the buyer’s tax location, which reprice() uses to calculate tax. A billing_address.region you send is part of it too, as the state or province: when you change postal_code, send the matching region, or region: null, because a region left from an earlier address can make reprice() fail. A key setBuyerIdentity() does not take, such as a misspelled one or a nested tax_location: { ... }, is ignored: the rest of the payload is saved, and the response lists each ignored key by its path in ignored_keys (["tax_location"], or "billing_address.state" for a key inside an address). Check that it is absent after you call setBuyerIdentity(). A later release will refuse such keys with an error instead; no date is set.
Can this product be bought?
getProduct()’s response says whether the product can be bought now, so you can disable your Buy button before a cart exists:
When
purchasable is false, addLine() and createPrefilledCheckout() refuse the product with 422 not_saleable, carrying the same value in block_reason and the value of purchase_block_detail in block_detail (see errors). purchasable judges the product’s first payment plan only: a plan you name in plan_id is checked on its own when you add it, and can be refused with a plan reason such as plan_currency_not_settleable or interval_exceeds_max while purchasable is true. A product that goes off sale after it was added to a cart is refused by checkout() and by the payment with 422 product_unavailable.
cope-sdk 0.1.8 does not declare purchasable, purchase_block_reason or purchase_block_detail on the product type, although the API sends them. Read them from the response as untyped fields until a release declares them.
Consents
Consents are the buyer’s own acceptance, and the API takes the same set COPE’s own checkout asks for:
Whether the buyer must waive their right of withdrawal depends on where and as whom they buy, and on what each cart line’s product promises. Where they buy is the country of the buyer identity’s
billing_address, or its country when the address names none; buyer_type: "b2b" buys as a company, anything else as a person. Each cart line carries product_type, withdrawal_period_b2c_days and withdrawal_period_b2b_days (days, -1 for no withdrawal right, null while the seller has not chosen one) so your page can apply the rule:
A subscription needs no consent of its own:
auto_renewal_consent is not required, and one you send is still recorded.
Send a consent only when the buyer gave it on your page, with a version naming the text they saw: COPE records each consent’s type and version on the checkout, with the time it was accepted, as the buyer’s own acceptance. A consent you send counts exactly as one ticked on COPE’s checkout page. The page shows it ticked and locked, so the buyer still sees the terms they are paying under, and asks only for the required consents you did not send. The checkout lists the types it holds in accepted_consents (acceptedConsents on the SDK’s checkout() and createPrefilledCheckout() results). Send all the required ones and the buyer can pay without ticking anything.
COPE’s checkout page does not offer a “subscribe to updates” box. To collect marketing opt-in, ask for it on your page and send marketing only when the buyer opted in.
Identifiers and amounts in cart API responses
The SDK speaks the cart API (/api/cart/v1). Two things in its responses differ from the Commerce API and the webhooks, and code that reads them should expect exactly this:
Read cart totals from the
*_minor_units fields, which are exact. Use the plan amounts only to display a price before a cart exists.
After successful payment, COPE redirects to success_url with your checkout metadata, the affiliate reference when there is one, and the order ID appended:
Prices: payment plans and offers
A cart line names a product and one of that product’s payment plans, and the plan decides the price. Nothing sent from the browser sets a price, so a catalogue checkout sells exactly the prices you have created: one payment plan per price point, including each recurring amount and billing cycle. When the price is decided per buyer — a negotiated amount, a custom subscription price, an installment schedule agreed on a call — create an offer instead of another payment plan. An offer prices one product for one named buyer, and can sell other products beside it inextra_lines, each with its own price, and returns a private checkout link made out to them. Create it on your server with your secret API key:
pricing.plan_type is one_time, subscription or installment, and decides which other pricing fields are required; installment is available only to sellers enabled for installment sales. The offer is paid with the payment methods the product already accepts. Creating an offer notifies nobody: send its public_url to the buyer yourself, or call POST /v1/commerce/offers/{id}/send to have COPE email it. To open the offer inside your own page, see Mounting a phone offer. The Create an offer operation in the API reference lists every field.
external_reference and metadata are optional and attach your own reference to the sale; the buyer cannot change them, and Metadata and attribution gives their limits and every webhook they arrive on.
What the buyer cannot change on an offer
An offer’s checkout runs in the buyer’s browser like any other, but what you set when you created the offer stays as you set it:- Products and quantities. Adding, changing or removing a line on the offer’s cart is refused with
422 lines_locked. - Buyer details. The offer is made out to the buyer you named. A change to any detail you set, except the checkout language, is refused with
422 buyer_identity_locked, one error per field; a detail you left empty, the buyer can fill in. The cart’sbuyer_email_lockedistruewhen you set the email.
422 metadata_locked, and any attribution with 422 attribution_locked. See Offers and checkouts from your server.
Redirect URLs
success_url and cancel_url must be registered for the business before you can pass them to checkout(). Register them in the COPE dashboard under Settings → SDK, on the API Settings page, in the Redirect URLs section — up to 10 of each.
Passing a URL that is not registered fails the checkout call with 422 and a field error per offending value. The message points at the same screen:
Matching is exact
A registered entry is compared to the value you send as a complete URL string. It is not an origin match and not a path prefix, so every one of these is rejected when onlyhttps://shop.example.com/thank-you is registered:
If your landing page needs its own query parameters, register the full URL including them. You do not need to register a variant with COPE’s parameters: they are appended after the value has been matched.
What you can register
- HTTPS, on a public host. Private addresses such as
10.x.x.x,172.16-31.x.x,192.168.x.x, and IPv6 unique-local addresses are always rejected. - Loopback hosts (
localhost,127.0.0.1, and IPv6[::1]) are rejected:https://app.cope.comdoes not redirect a buyer to an integration running on your own machine, such ashttp://localhost:5173/thank-you. - No credentials in the URL (
https://user:pass@…) and no backslashes. - A product’s custom thank-you page follows the same rules, so a buyer is never sent anywhere a registered redirect URL could not go.
Omitting them
success_url and cancel_url are optional on checkout(). When you omit one, COPE uses the first URL registered for that field. When you send one, it must be registered.
Embedded checkout signals completion through postMessage events rather than a redirect, so iframe integrations can omit both. Keep at least one of each registered anyway: when mountCheckout() falls back with fallback: "redirect", the buyer continues on COPE hosted checkout, and that page still needs a success and cancel destination to return them to afterwards.
Your own reference on an order
COPE carries a small bag of your data,metadata with your external_reference in it, through checkout and hands it back on the webhooks that follow, so you can match a COPE order to the record it belongs to in your own system. It carries the marketing attribution of the link the buyer arrived on too: the UTM parameters, the ad click ids and the affiliate link click. Metadata and attribution covers what each way into checkout accepts, the link spellings and limits, and where every value comes back.
1-click checkout links
The 1-click checkout link,https://app.cope.com/checkout?product=<product-id>, is reusable: anyone who opens it can buy the product, on one page that shows the product, its plans and its add-ons beside the checkout. Every product has one. Add &plan=<plan-id> to start the page on that plan; the buyer can still choose another of the product’s plans, and a plan the product does not sell starts the page on its first plan.
A product’s own link, https://app.cope.com/products/<product-id>, opens the product in its checkout layout, chosen in the dashboard under the product’s general information or sent as checkout_type when you create or update the product: one_click opens the same one-page checkout, and standard the product page with its checkout in a pop-up. A product created without one starts on one_click; a product created before the layout existed is standard.
A link’s value belongs to the buyer
Anything in a link can be edited in the buyer’s address bar, and a value your page sends with the publishable key comes from the buyer’s browser. Never grant anything onexternal_reference or metadata alone: match a paid order to your record by order.id, as described in match the order by its ID.
Where it comes back
Your bag comes back asmetadata on the cart and order events and as order.metadata on every payment event, and the attribution as attribution and first_click_ref. Reading it back lists every event and field, and what the API returns.
On your thank-you page
After payment COPE appends your bag’s top-level keys asmetadata[<key>], the affiliate code of the buyer’s link click as affiliate when there is one, and the order ID as order to the URL it sends the buyer to. On your thank-you page gives the order of the parameters, their encoding and the length limit.
Embedded checkout
To keep the buyer on your page, create checkout withembed_origin and mount it with mountCheckout().
Core methods
Errors
The cart API answers a refused request with a JSON body holding anerrors array. Each entry has a machine-readable code and a human-readable message; field names the request field at fault when there is one. When code is not_saleable, block_reason, when present, says why the product or plan cannot be bought, and block_detail, when present, holds the same value, except non_ess_not_enabled for an approved product that is not available for purchase yet, where block_reason is pending_approval. A product that is not active is refused with neither. Read block_detail first when it is present:
413), too many requests (429), a path that does not exist (404), or COPE not answering, or not in time (502, 504). Those bodies have a single error code and a request_id instead of the errors array:
error.code, which is the first entry’s code or the error field, and log error.requestId when you contact COPE support. Neither shape is the application/problem+json body the Commerce API uses.
The SDK exposes typed errors:
429 (rate_limited) and a 409, which says the cart or checkout is busy — a checkout still being created, or a payment still in progress — and which the same request can pass once that finishes. Fix the input and send a new request. The SDK retries selected transient network or server failures with its own backoff; it does not wait for a Retry-After, which it reports as error.retryAfter (seconds) on the error it finally throws.
A 503 with code checkout_release_retry, from cancelCheckout(), means Stripe or PayPal did not answer in time and nothing changed: send the same call again. The SDK does not retry a checkout call for you. cope-sdk 0.1.2 declares it in ApiErrorCode; 0.1.1 reports it as error.code without declaring it.