Glossary
A reference of domain terms used throughout the HappyColis GraphQL API documentation.
Business Domain
Organization The top-level tenant in HappyColis. All resources (orders, products, locations, integrations) belong to an organization. Access tokens are scoped to a single organization via the organization_id parameter at authentication time.
Location A physical or virtual warehouse site managed within HappyColis. Locations hold stock, execute fulfillment, and are associated with fulfillment services. Each stock reference and delivery order is scoped to a specific location.
Product A sellable item in the catalog. A product groups one or more variants and carries top-level metadata such as title, vendor, and category. Products are not stocked directly — variants are.
Variant A specific purchasable version of a product, identified by its SKU. Variants carry attributes (e.g. size, color) and are the unit of inventory tracking. Each variant has one or more stock references across locations.
SKU (Stock Keeping Unit) The unique identifier for a product variant within a location's inventory. SKUs are used in order lines, stock references, and shipment details to identify which items are being ordered, stocked, or shipped.
Stock Reference The inventory record for a specific variant at a specific location. It tracks physical, usable, and reserved quantities and is the core of the inventory management system. A stock reference is identified by SKU + location.
Bundle A virtual product composed of one or more underlying variants. When a bundle is ordered, the system automatically expands it into its constituent variant quantities for picking and packing.
Variant Link The association between a bundle variant and its component variants. Variant links define the composition of a bundle (e.g. "gift set = 1x candle + 1x diffuser").
Storage Profile A configuration template attached to a stock reference that defines how a variant is stored and handled at a warehouse (e.g. fragile handling, cold chain, pallet storage).
Order & Fulfillment
Order A customer purchase request containing one or more order lines (SKU + quantity), a delivery contact, and fulfillment metadata. Orders drive the full lifecycle from creation through warehouse dispatch to delivery.
DeliveryOrder A fulfillment task derived from an Order, scoped to a single location. When an order is opened, the system creates one or more delivery orders — one per fulfillment location — and sends them to the appropriate warehouse or fulfillment service.
Shipment A physical parcel dispatched from a warehouse. A shipment is linked to a delivery order and carries the carrier tracking number, addresses, packed items, and a timeline of shipping events.
Fulfillment Service An external or internal warehouse system connected to a HappyColis location. Fulfillment services receive delivery orders and report back on their status (accepted, refused, shipped, completed). Examples include WMS integrations and 3PL partners.
FulfillmentAction An event sent by a fulfillment service to update the state of a delivery order (e.g. accepted, refused, shipped, completed). FulfillmentActions trigger state transitions and fire corresponding webhooks.
DispatchableRequest The asynchronous result type returned by order mutations such as orderOpen, orderCancel, and orderRequestFulfillment. It represents a background processing request rather than the final outcome. Use webhooks to be notified when the operation completes.
Security & Authentication
OAuth The authorization framework used by HappyColis to grant API access. Supports client credentials (server-to-server), authorization code (public apps on behalf of organizations), and refresh token flows.
Bearer Token An access token included in the Authorization: Bearer <token> HTTP header to authenticate API requests. Tokens are JWTs signed by the HappyColis auth service and expire after expires_in seconds (default: 3600).
Scope A permission label included in an access token that controls which operations the token may perform (e.g. view_orders, create_shipments). Tokens without the required scope receive a FORBIDDEN / INSUFFICIENT_SCOPE error.
Webhooks
Webhook An HTTP callback that HappyColis sends to your registered endpoint when a specific event occurs. Webhooks deliver a JSON payload signed with an HMAC-SHA256 signature so you can verify authenticity.
HMAC (Hash-based Message Authentication Code) A cryptographic signature computed from the raw webhook payload body using a shared secret. Verify the X-HappyColis-Hmac-SHA256 header against your own computed HMAC to confirm that the payload was sent by HappyColis and was not tampered with in transit.
Event A named occurrence in the HappyColis system that can trigger a webhook delivery (e.g. order/created, shipment/shipping_event). Events follow the pattern {domain}/{action}.
Integration A registered application that connects to HappyColis via the API. Integrations own webhook subscriptions and are authenticated via OAuth client credentials. An integration is either private (single organization) or public (installable by any organization).
GraphQL & Architecture
Apollo Federation The microservices architecture pattern used by HappyColis. Each domain (orders, catalog, stock, shipments) is a separate subgraph exposing its own GraphQL schema. The supergraph (front-api gateway) composes them into a single unified API endpoint.
Supergraph The composed GraphQL schema that end clients query. The supergraph is served by the Apollo Gateway (front-api) and federates queries across all domain subgraphs transparently.
Subgraph An individual domain service that exposes a subset of the overall API schema. Subgraphs use @key directives to declare their entity types and participate in cross-service joins via federated references.
Code First The GraphQL development approach used by HappyColis where the schema is derived from TypeScript decorators (@ObjectType, @InputType, @Resolver) rather than hand-written .graphql files. The schema is auto-generated at startup from the decorator metadata.