Skip to content
jtWMS Docs

API & integration

jtWMS is API-first: every feature is available through its REST API before it appears in the app, and the app itself is built on the same API. This section is for developers who connect other systems to jtWMS, such as an ERP, an e-commerce platform or a reporting tool.

Basics

Section titled “Basics”
  • Base URL. Every request goes to your jtWMS host, https://<your-jtwms-host>. On a local development stack, that is http://localhost:5050.
  • Versioning. Every endpoint is under /api/v1/, for example /api/v1/products. Event types carry their version in their name, such as jtWMS.Catalog.Events.V1.ProductCreated.
  • JSON. Requests and responses are JSON, with camelCase property names. Enumerations are strings ("Active"), timestamps are ISO 8601 with an offset, in UTC, and IDs are GUIDs. Ignore response fields you don’t recognise, and expect an enumeration in a response or an event to gain values: treat a value you don’t know as a sensible default rather than an error. There are two exceptions: the keys inside a webhook event’s data use PascalCase (see Webhooks), and the OAuth endpoints under /connect/ take form-encoded requests and answer in OAuth’s snake_case (see Authentication).
  • Tenancy. A request only ever sees the data of the tenant it authenticates as. You never send a tenant ID: it comes from your token or API key.
  • Errors. Every error on /api/v1/ is an RFC 9457 problem details object with a correlationId you can quote to support, and a machine-readable errorCode where the error has one.

Guides

Section titled “Guides”
  • Authentication: user access tokens from /connect/token, refresh and sign-out, and API keys in the X-Api-Key header.
  • Permissions and scopes: the permission keys, the standard roles, and how an API key’s scope is chosen.
  • Errors: the problem details format, validation errors and every errorCode.
  • Paging, filtering and sorting: page, pageSize and sort, and which lists are paged.
  • Bulk import: loading products and inviting your team in batches.
  • Rate limits and feature gates: the burst limit, the daily quota per plan, and routes your plan must include.
  • Correlation IDs: tagging requests with X-Correlation-Id and tracing them with support.
  • Concurrency and deletes: retrying 409 concurrency_conflict, soft deletes, and ?cascade=true.
  • Webhooks: subscribing to events, verifying signed deliveries, retries and redelivery.

References

Section titled “References”

The API reference in this section lists every public operation of each service, generated from its OpenAPI document. Open it from the sidebar, or start with one of these:

The jtWMS host also serves an interactive reference at /docs, where you can try requests. The documents themselves are at /openapi/{service}/v1.json, for example /openapi/catalog/v1.json. The events reference describes every event you can receive through webhooks, with its payload.