JavaScript API

window.OpenShop is the supported way for your own site code to talk to Open Shop. It reads customer, cart, store, product, and referral state, performs cart actions, and emits events when anything changes.

Where it comes from

Nothing extra to load. The same components.js that registers the os-* custom elements installs window.OpenShop as it boots:

index.html

<link rel="stylesheet" href="https://openshopgo.com/wc/components.css" />
<script src="https://openshopgo.com/wc/components.js" defer></script>

If the Quickstart tags are already on your page, the API is already there. OpenShop.version reports the bundle version that installed it.

Note

The namespace is frozen. You can read it and call it, but you cannot add to it or replace its methods. Snapshots handed to you are frozen too.

Loading and readiness

components.js carries defer, so it runs after the HTML is parsed. Any inline <script> earlier in the page runs before window.OpenShop exists. Pick the path that matches where your code lives.

Code that may run before the bundle

Push a callback onto window.OpenShopQ. This is the same pattern as a dataLayer queue: the array exists whether the bundle has loaded or not.

Site header custom code

<script>
  (window.OpenShopQ ??= []).push((os) => {
    console.log('Open Shop', os.version, 'is ready');
  });
</script>

On init the bundle drains the queue, then replaces push with an immediate call — so callbacks pushed later still run right away. This snippet is safe anywhere on the page, which makes it the one to reach for in a site builder where you do not control script order.

Code that already runs after the bundle

Use the ready promise.

app.js

OpenShop.ready.then((os) => {
  console.log('Open Shop', os.version, 'is ready');
});

The os:ready document event

The bundle also dispatches os:ready on document, for code that only wants addEventListener.

app.js

document.addEventListener('os:ready', (event) => {
  const os = event.detail;
  console.log('Open Shop', os.version, 'is ready');
});

Ready does not mean resolved

ready resolves once the store overview has been requested and the customer, cart, and referral resolvers have started. It does not wait for them to finish, so OpenShop.customer.current and OpenShop.referral.current may still be undefined at that moment, and OpenShop.cart.current is null until the summary lands. If you need a value, call get() or listen for the matching change event.

Snapshots, undefined, and null

Every current property is a snapshot: a frozen plain object built from the bundle’s internal state. On each change the snapshot is replaced wholesale rather than mutated, which means:

• === is a valid change check. If the reference is the same, nothing changed.
• Nothing you do to a snapshot affects the store. The objects are frozen.
• Promise results are the same snapshots, so await OpenShop.customer.get() and OpenShop.customer.current hand you the same object once resolution finishes.

Two empty-looking values mean different things, and the difference matters:

Value	Meaning
undefined	Not resolved yet. The request is in flight, or has not started. Do not draw a UI from this.
null	Resolved, and there is nothing. No signed-in customer, no cart, no referral.

Only customer.current and referral.current have the unresolved state. cart.current is CartSummary | null and is never undefined — for the cart, null simply means there is nothing to show.

app.js

const customer = OpenShop.customer.current;

if (customer === undefined) {
  // Still resolving — wait for customer:change instead of painting anything.
} else if (customer === null) {
  showLoginLink();
} else {
  showGreeting(customer.firstName);
}

Events

Subscribe with OpenShop.on(event, handler). It returns an unsubscribe function.

app.js

const off = OpenShop.on('cart:change', (summary) => {
  console.log('cart now has', summary?.itemCount ?? 0, 'items');
});

// Later
off();

Event	detail	Fires when
ready	OpenShop	Init is complete.
customer:change	Customer | null	First resolution, a detected login or logout, or get({ refresh: true }).
cart:change	CartSummary | null	Any summary replacement, including refreshes triggered by another tab.
cart:open	undefined	The slideout opens.
cart:close	undefined	The slideout closes.
cart:add	{ item, summary }	An add to cart succeeds. item is null when the added line is not in the refreshed summary.
cart:error	OpenShopError	A mutation through OpenShop.cart.add/update/remove fails. Clicks on the components’ own buttons do not fire it.
referral:change	Referral | null	The tracker resolves or clears attribution.

The os: document mirror

Every event is also dispatched on document as a CustomEvent named os: plus the event name — os:ready, os:customer:change, os:cart:open, and so on — carrying the same detail. Use this when you cannot hold a reference to the namespace, such as a one-off embed or a tag manager snippet.

Site footer custom code

document.addEventListener('os:customer:change', (event) => {
  const customer = event.detail;
  document.body.classList.toggle('is-signed-in', customer !== null);
});

Both paths deliver the same payloads. on() is easier to unsubscribe from; the document events are easier to attach from anywhere.

Errors

Rejected promises reject with an OpenShopError:

openshop.d.ts

interface OpenShopError {
  code: string;
  status: number;
  message: string;
}

code is stable enough to branch on. status is the HTTP status. message is a short description — useful for logs, not written for shoppers.

Codes from the API

These are the backend’s own codes, passed through untouched. You get them from cart.add() and from api.get / api.post.

code	What it means
UNPROCESSABLE_ENTITY	The product is out of stock.
GONE	The product is no longer available.
FORBIDDEN	On an add, the product is not available to this shopper’s account type. On a quantity update, the line is externally priced and its quantity cannot change.
DUPLICATE	The cart already holds an enrollment, and enrollments cannot be added twice.
CONFLICT	Several causes — an inactive cart, or a competing enrollment item. Read message for the specific one.
INVALID_TOKEN	Not signed in, or the session has ended.

When a response carries no code of its own, the status is used to pick one: BAD_REQUEST, NOT_FOUND, or RATE_LIMITED.

Codes from the library

These are raised before or around the request, so status may be 0.

code	What it means
INVALID_INPUT	cart.add() was called with neither productId nor slug.
INVALID_PATH	api.get or api.post was given a path that does not start with a single /. Absolute URLs and protocol-relative // paths are refused.
INVALID_RESPONSE	The response body was not JSON.
NETWORK	The request never reached the API. status is 0.
UNKNOWN	No code could be determined. status is 0.

Products and store failures carry the HTTP status, not a backend code

products.* and store.get() reject with status set to the HTTP status and a code derived from it — a missing product is code: 'NOT_FOUND', status: 404. They never read the API’s own err code out of the body, so branch on status there; status: 0 still means the request never got an answer. cart.add() and api.* are where the backend’s own codes come through.

app.js

try {
  await OpenShop.cart.add({ slug: 'vip-perks' });
} catch (error) {
  if (error.code === 'UNPROCESSABLE_ENTITY') return showBackInStockForm();
  console.error(error.code, error.message);
}

Stability policy

The API follows the bundle’s semver.

Covered by semver — safe to build on:

• Method names on OpenShop and its namespaces
• Event names, including the os: document mirror
• Snapshot field names and their types
• data-os-* attribute names and behaviour
• The os-components CSS cascade layer — its name, and that every style the bundle injects lives inside it

Not covered — do not build on these:

• Internal class names such as .os-cart-item-name
• The DOM structure inside a component
• Svelte-scoped selectors

Matching on internal class names or component markup is how site code breaks on a routine refactor. If you are doing that today, this API is the replacement.

For styling, the os-components cascade layer means a plain class selector already beats ours, so you never need our generated hash classes to override a component. The class names you write that selector against are still ours to rename between versions — the layer makes overriding easy, not the class names permanent.

Deprecations are announced with a console.warn — logged once per page — for at least one minor release before anything is removed.

TypeScript definitions

The build publishes a declaration file next to the bundle:

https://openshopgo.com/wc/openshop.d.ts

It declares OpenShop, every snapshot type, OpenShopEvent, and OpenShopError, and augments Window with OpenShop and OpenShopQ. Save it into your project and point at it with /// <reference path="./openshop.d.ts" /> at the top of a file to get completion and type checking in your editor.

Keep reading

Customer Login state, the customer snapshot, handoff tokens, and logout.

Cart Read the cart, add and update items, and drive the slideout.

Store, Products, Referral Store overview, product lookups, the resolved enroller, and the raw API escape hatch.

Data Attributes The no-code layer — show, hide, and fill elements without writing JavaScript.