Getting Started

Welcome to the HappyColis GraphQL API — the logistics platform for e-commerce operations including orders, fulfillment, stock, products, locations, and shipments.

Base URL

All API requests are sent as GraphQL POST requests to:

https://api-v3.happycolis.com/graphql

Architecture

HappyColis uses Apollo Federation v2 — a supergraph composed of multiple microservices. Types are extended across services, giving you a unified API over the entire platform.

Authentication

Every request requires a Bearer token obtained via OAuth 2.0.

curl -X POST https://api-v3.happycolis.com/graphql \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "query": "{ __typename }" }'

See Authentication for the full OAuth flow.

Making Requests

GraphQL requests use application/json with a query (or mutation) field and optional variables:

curl

curl -X POST https://api-v3.happycolis.com/graphql \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetOrder($id: String!) { order(id: $id) { id state } }",
    "variables": { "id": "order_123" }
  }'

Node.js

async function graphql(accessToken, query, variables = {}) {
  const response = await fetch('https://api-v3.happycolis.com/graphql', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query, variables }),
  });
  const { data, errors } = await response.json();
  if (errors) throw new Error(errors[0].message);
  return data;
}

Python

import requests

def graphql(access_token, query, variables=None):
    response = requests.post(
        'https://api-v3.happycolis.com/graphql',
        headers={
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json',
        },
        json={'query': query, 'variables': variables or {}}
    )
    result = response.json()
    if 'errors' in result:
        raise Exception(result['errors'][0]['message'])
    return result['data']

PHP

<?php
function graphql(string $accessToken, string $query, array $variables = []): array {
    $client = new \GuzzleHttp\Client();
    $response = $client->post('https://api-v3.happycolis.com/graphql', [
        'headers' => [
            'Authorization' => 'Bearer ' . $accessToken,
            'Content-Type' => 'application/json',
        ],
        'json' => ['query' => $query, 'variables' => $variables],
    ]);
    $result = json_decode($response->getBody(), true);
    if (isset($result['errors'])) {
        throw new \Exception($result['errors'][0]['message']);
    }
    return $result['data'];
}

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func graphql(accessToken, query string, variables map[string]interface{}) (map[string]interface{}, error) {
    payload, _ := json.Marshal(map[string]interface{}{
        "query":     query,
        "variables": variables,
    })
    req, _ := http.NewRequest("POST", "https://api-v3.happycolis.com/graphql", bytes.NewBuffer(payload))
    req.Header.Set("Authorization", "Bearer "+accessToken)
    req.Header.Set("Content-Type", "application/json")
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    if errs, ok := result["errors"]; ok {
        return nil, fmt.Errorf("%v", errs)
    }
    return result["data"].(map[string]interface{}), nil
}

Key Concepts

Concept	Description
Organization	Top-level tenant. All resources belong to an organization.
Location	Warehouse or fulfillment center where stock is held.
Product / Variant	Catalog items. Variants are the sellable SKU-level items.
StockReference	Links a Variant to a Location with inventory quantities.
Order	Customer purchase with lines to be fulfilled.
DeliveryOrder	Sub-order assigned to a specific fulfillment location.
TransferOrder	Stock replenishment order from a supplier to a fulfillment location.
Shipment	Physical package shipped to a customer.
Application	External integration that connects to HappyColis via OAuth and the GraphQL API.

API Resources

• Platform Overview — Architecture, environments, and key concepts
• Authentication — OAuth 2.0 client credentials and scopes
• Applications — Application types, integration tokens, and webhook subscriptions
• Search & Filters — Elasticsearch-backed search with complex filters
• Locations — Warehouse and fulfillment center management
• Products — Catalog, variants, and bundles
• Stock — Inventory management and stock movements
• Orders — Order lifecycle and fulfillment
• Delivery Orders — Per-location fulfillment tracking
• Transfer Orders — Stock replenishment and supplier transfers
• Shipments — Package tracking and delivery events
• Webhooks — Real-time event notifications
• Webhook Event Payloads — Complete JSON payload reference for all events