Skip to content

Environments & schema identity

Base URLs

EnvironmentAPI baseWhat it is
Productionhttps://api.litecommerce.ioThe live API.
Previewhttps://api.preview.litecommerce.ioThe staging API, where an integration is built and verified before it goes live.

Both appear in the server selector at the top of the API reference. Production is the default; pick Preview while you are integrating.

Everything on this site describes one API surface. It is the same contract on both bases — but the two do not deploy at the same moment, so at any given time one of them may be a build ahead of the other. The rest of this page is how you tell.

Storefront mode: Production or Sandbox

The API deployment and your store's commerce mode are distinct. Your Production storefront uses Live data. Your Sandbox storefront is your Preview/Staging test website and uses separate test data. You host both sites; cartonium registers and verifies their addresses.

In tenant Admin, use Settings → Storefront domains to set both addresses. Enable Sandbox beside the logo before configuring its domain. Each replacement becomes active after its DNS-TXT ownership check succeeds. Changing an address here does not change the mode selected beside the logo, deploy your site, or configure its DNS or HTTPS certificate.

Domains is the sole source of truth for storefront data selection, including server rendering. Browser requests carry their actual Origin automatically. Your server transport must forward the current storefront request origin as x-storefront-origin, alongside the route's tenant and authentication headers. The same code works on both addresses; it sends the hostname, never a chosen mode.

Missing, unknown or conflicting storefront context is rejected. There is no Live fallback, and calling the Preview API alone does not select Sandbox. When both origin headers are present, they must agree. The domain must belong to the requested tenant; API keys and customer credentials must match that tenant and its selected data.

For example, a server request originating at https://test.your-store.example sends x-storefront-origin: https://test.your-store.example. If that address is registered under Sandbox in Domains, the API uses Sandbox data. Derive this value from the current request in your transport; do not create a second URL or mode setting. Never retry a context error with the header removed.

This also applies to token-only storefront payment requests: the origin selects the data scope, while the token remains the credential. Shared endpoints such as API schema identity and plan pricing do not require storefront context.

The Admin's Connection details and copied integration instructions report the selected mode and its hosted cartonium checkout address. Use those values instead of constructing a checkout hostname from your storefront URL.

For local cartonium checkout development, http://localhost:9908 redirects to the configured tenant's explicit local host, such as http://demo.localhost:9908. Use http://demo.sandbox.localhost:9908 for that tenant's local Sandbox tables. These platform-owned development hosts work only with a non-deployed API reached over loopback. They are not tenant-owned Domains entries and are not accepted by the staging or production API. No extra mode setting is required.

The problem

The reference you are reading is a committed artifact. It is generated from the API source and published with the docs site; it is never scraped from a running API. The API you are calling is a deployment. Those two things move on their own schedules.

So "the docs redeployed but the endpoint I care about looks unchanged" is genuinely ambiguous from the outside: it might mean the change was somewhere else, or it might mean you are reading a build that is not the one answering your requests. Before schema identity there was no public way to tell those apart — info.version read 0.0.1 (a package placeholder that never moved), and public health returned only a status and a timestamp.

Schema identity

Every generated copy of the reference carries a schema digest — a SHA-256 content hash of the document itself, in the form sha256:<64 hex characters>. The running API publishes the digest of the document it was built from. If the two strings are equal, that runtime was built from the same public API surface this reference was generated from.

The digest is opaque. It is a fingerprint, not a version number: it has no ordering, so two different digests tell you the reference and the runtime are out of step, but not which one is newer.

How to compare

1. Ask the runtime. The endpoint is public — no API key, no session, no x-organization-slug:

curl https://api.preview.litecommerce.io/api/v1/public/api-schema
{
  "schemaDigest": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
}

That value is a placeholder — a real response carries 64 hex characters of actual digest. Swap the host for https://api.litecommerce.io to check Production.

2. Fetch the reference. The same vendored document rendered by the API reference is available as JSON at /api-reference/openapi.json. Its info.version is the reference digest:

curl -fsS https://docs.litecommerce.io/api-reference/openapi.json \
  | jq -er '.info.version'

The version badge beside the rendered reference title shows the same value. The response sends Cache-Control: no-store, so conforming caches do not retain it across docs deployments and produce a false match after the runtime has moved.

3. Compare the two strings verbatim.

  • Equal → the reference you are reading was generated from the same public API surface the runtime was built from. Build against it.
  • Different → the reference and that deployment are out of step. Re-check in a few minutes: a deploy may be mid-flight. If it persists, treat the runtime as authoritative for behavior, and raise it with us rather than guessing which side is stale.

Compare against the base you are actually calling. A digest read from Preview says nothing about Production, and vice versa.

For example, this assertion fails a CI job when the published reference and Preview runtime describe different contracts:

reference_digest="$(
  curl -fsS https://docs.litecommerce.io/api-reference/openapi.json \
    | jq -er '.info.version'
)"
runtime_digest="$(
  curl -fsS https://api.preview.litecommerce.io/api/v1/public/api-schema \
    | jq -er '.schemaDigest'
)"
 
test "$reference_digest" = "$runtime_digest"

What equality does not tell you

Equality is a statement about build provenance, not about which routes a given deployment has switched on. The reference describes the API surface, not any one environment's configuration, so a route family that is gated behind deployment configuration is documented here whether or not a particular runtime has it mounted. Such an endpoint can answer 404 on a runtime whose digest matches this reference, and that is not a mismatch.

Today this applies to exactly one family: /api/v1/support-provider/*, the provider callout surface for cartonium, which stays unmounted until an operator enables it. Every public, customer, merchant, storefront, and import route in this reference is mounted wherever the API runs. If some other documented endpoint returns 404 against a matching digest, that is not expected — raise it with us.

What the digest covers

It is computed over the whole generated OpenAPI document — paths, operations, parameters, request and response schemas, security schemes, tags, and the rest of info — with exactly two exclusions:

  • servers — the base URL list is publication detail, rewritten per environment. Excluding it is what lets one digest describe the contract on both bases.
  • info.version — the digest's own field.

Two normalizations keep it honest, so it moves on real changes and only on real changes: object keys are sorted before hashing (key order carries no meaning in JSON), and parameters lists are sorted (OpenAPI defines them as a set, unique by name and location). Everything else, including the order of required and enum entries, is significant.

So: a new endpoint, a renamed field, a changed type, a dropped security requirement, an added response code, or an edited operation summary all move the digest. Adding a base URL to the server list does not.

info.version is not a release version

info.version in this API's OpenAPI document is the schema digest. It is not semver, not a release number, and it is not comparable — do not parse it, sort by it, or gate behavior on it. Its only supported use is the equality check above.

It used to be 0.0.1, which was the API package's placeholder version and never changed. If you have logic reading that value as a version signal, it is reading noise; replace it with the comparison on this page.

The API's versioning boundary is the /api/v1 path prefix, not this field.