SDKs & tools

ORBCART DOCUMENTATION

SDKs & tools

Which package for which job, and which key goes where.

All packages are TypeScript-first. Until the first release they are used from the source workspace; there is no npm install yet.

You are building…PackageStart here
A storefront, app or agent@orbcart/clientCarts
A React checkout@orbcart/reactReact checkout
An ERP link or support tool@orbcart/adminOrders & refunds
Your commerce Worker@orbcart/runtimeConfiguration
A DHL pickup finder@orbcart/plugin-dhlShipping

React is optional. The client works in any framework, on a server and in Node.

Imports at a glance

In the storefront:

import { createCommerce, formatMoney, unitsIn, isSubmitted, CommerceError } from "@orbcart/client";
import { Checkout, CartProvider, useShoppingCart } from "@orbcart/react";
import "@orbcart/react/styles.css";
import { betterAuthIdentity } from "@orbcart/client/better-auth";

On your server and in your Worker:

import { createAdmin } from "@orbcart/admin";
import { defineCommerce } from "@orbcart/runtime";
export * from "@orbcart/runtime/objects";

Test helpers live in @orbcart/runtime/testing and @orbcart/client/testing. Testing →

Which key goes where

The publishable key goes in the browser, the Cart token in a session cookie, the secret key only on your server. Full table →

createCommerce refuses a secret key and createAdmin refuses a publishable one, so a mix-up fails loudly in development.

Errors

Every SDK throws CommerceError for a failed request. Business outcomes, such as a declined card or quote_changed, are return values, not exceptions. Handle them → · Every code →

The checkout store of cart.checkout() puts a refusal where the buyer looks for it. Its bag steps (add, setQuantity, remove, enterCode) throw it like the cart's own, so the Line or the discount code shows it in place. Its checkout steps (start, submitDetails, setShipping, placeOrder) never throw a refusal: they show it in state.notice.

Words for buyers

describe(locale) turns codes into buyer-friendly sentences in English, German, French and Dutch. Never show the API's detail text to buyers.

import { describe } from "@orbcart/client";

const words = describe("de-DE");
words.problem("code_invalid"); // a sentence for the buyer
words.paymentMethod("ideal"); // "iDEAL | Wero"
words.change(change); // explains one entry of cart.changes

Retries

The SDKs add an Idempotency-Key to every change and repeat a request when the network drops, so a retry never adds a Line twice or charges twice (how). You only pass your own key for refunds that must survive a restart of your backend.

Add the React checkout →

On this page