OMS API integration guide

Welcome to the API Integration Guide for OMS!

What is the OMS?

The Calicantus Order Management System (OMS) is the platform where the orders placed on a brand's e-commerce channels are collected and managed through their whole lifecycle: payment, fulfillment by the warehouse, shipping by the carrier and — when goods come back — returns and refunds.

This API is how an external system takes part in that flow: you read the data you need with queries (orders, documents, stock availabilities…), act on your side of the process with mutations, and get notified of changes through webhooks — whether you are integrating a payment gateway, a logistics system or the brand's own backend.

Before you start

This guide is crafted to assist developers in integrating our Order Management System into their applications through GraphQL. A few facts before you start:

• The API is GraphQL: a single endpoint per environment, with a staging environment available to develop and test your integration safely.
• You decide the shape of every response: a single query can return a resource together with its related data — the orders with their details and documents, for example — instead of a listing call followed by one call per item. See the introduction to GraphQL.
• Every request requires an access token, and each operation requires specific permissions granted to it — see Authentication to learn how to obtain and use one.

Where to start

• Integrating the API for the first time? Start from Getting started: set up a client, authenticate, and learn the core concepts of the API — pagination, filtering, errors and rate limiting.
• Want to try the API before writing code? Open the Playground: paste your access token and run queries against staging directly from these docs — every example in the guides can be opened there with one click.
• Integrating a specific scenario — like a payment gateway or an external warehouse? Start from the Use cases section: each use case explains what the integration is for and walks you through the flows involved.
• Looking for a specific operation? Go straight to the guide of the flow you are working on — orders, payments, repayments, shipping, warehouses or brands.
• Want to react to changes without polling the API? See Webhooks to receive real-time notifications when an order changes status, or when OMS requests a refund, issues a fiscal document or a shipping label (waybill).
• Need the exact definition of a type, field or enum? The full GraphQL schema reference documents every operation and object of the API — the guides link into it from every example.

Working with an AI assistant?

These docs are plain, pre-rendered pages: you can point your AI assistant (Claude, ChatGPT, Gemini, Copilot…) at the pages you are working with and ask questions in your own words. Treat its answers as a starting point — this documentation remains the source of truth, and every example here is verified against the real API.

The site also follows the llms.txt convention, which most assistants don't discover on their own — point them to it explicitly: /llms.txt is an index of every page built for AI consumption, and appending .md to any page URL (for example /webhooks/intro.md) returns its plain-markdown version — the same verified content without the HTML around it, so it uses far fewer tokens and leaves the assistant more room for your actual question.

Key terms

A few domain terms you will meet across these docs:

Term	Meaning
Order	A purchase placed on the brand's e-commerce channel, managed by OMS through its whole lifecycle.
Shipping	A shipment of an order — first fulfilled by the warehouse, then shipped by the carrier, each stage with its own status. An order can have more than one shipping.
Fulfilment	The warehouse stage of a shipping: picking the goods and packing them into parcels. In projects where the external warehouse validates the shippings, it declares it through the API — in full, in part or cancelled — see Confirm or cancel a fulfilment.
Repayment request (return)	The return of goods of an order, which may end in a refund — see its lifecycle.
Payment transaction	The record of a payment gateway's activity — payments, refunds and disputes — linked to an order or a repayment request, with its own lifecycle.
Order documents	The files attached to an order along its lifecycle — accounting documents, proformas and shipping labels (waybills) — retrievable through the order documents queries.

If you encounter any challenges or have questions along the way, feel free to reach out to our support team for support.

Happy coding!