order

Retrieve a single order by its internal ID or by an external reference from your system.

Required scope: view_orders

---

Query

query GetOrder($id: String, $byExternalReference: OrderByExternalReferenceInput) {
  order(id: $id, byExternalReference: $byExternalReference) {
    id
    externalReference
    invoiceNumber
    state
    type
    dispatchingType
    priority
    inventoryPolicy
    total
    totalTaxInclusive
    currency
    locked
    deliveryContact {
      fullname
      email
      address
      city
      zipcode
      country
      phone
    }
    lines {
      id
      sku
      label
      quantity
      fulfilledQuantity
      status
    }
    fulfillmentData {
      deliveryOrders {
        id
        orderNumber
        status
      }
    }
  }
}

---

Arguments

You must provide one of the following:

Argument	Type	Description
id	String	The internal UUID of the order
byExternalReference	OrderByExternalReferenceInput	Lookup by your system's reference

OrderByExternalReferenceInput

Field	Type	Required	Description
externalReference	String	✅	The external reference string (your system's order ID)
tpAppId	String	✅	The third-party application ID that owns the reference

---

Example Variables

Fetch by internal ID:

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Fetch by external reference:

{
  "byExternalReference": {
    "externalReference": "EXT-2024-001",
    "tpAppId": "my-ecommerce-app"
  }
}

---

Example Response

{
  "data": {
    "order": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "externalReference": "EXT-2024-001",
      "invoiceNumber": "INV-2024-001",
      "state": "OPENED",
      "type": "B2C",
      "dispatchingType": "AUTOMATIC",
      "priority": "NORMAL",
      "inventoryPolicy": "DENY",
      "total": 59.98,
      "totalTaxInclusive": 71.98,
      "currency": "EUR",
      "locked": false,
      "deliveryContact": {
        "fullname": "John Doe",
        "email": "john.doe@example.com",
        "address": "123 Main Street",
        "city": "Paris",
        "zipcode": "75001",
        "country": "FR",
        "phone": "+33612345678"
      },
      "lines": [
        {
          "id": "line-uuid-001",
          "sku": "TSHIRT-S-BLUE",
          "label": "Classic T-Shirt - Small Blue",
          "quantity": 2,
          "fulfilledQuantity": 0,
          "status": "PENDING"
        }
      ],
      "fulfillmentData": {
        "deliveryOrders": [
          {
            "id": "do-uuid-001",
            "orderNumber": "DO-2024-0001",
            "status": "PENDING"
          }
        ]
      }
    }
  }
}

---

Code Examples

curl

curl -X POST https://api-v3.happycolis.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "query": "query GetOrder($id: String) { order(id: $id) { id externalReference state lines { id sku quantity status } } }",
    "variables": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }'

Node.js

const response = await fetch('https://api-v3.happycolis.com/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.ACCESS_TOKEN}`,
  },
  body: JSON.stringify({
    query: `
      query GetOrder($id: String) {
        order(id: $id) {
          id
          externalReference
          state
          lines {
            id
            sku
            quantity
            status
          }
        }
      }
    `,
    variables: {
      id: '550e8400-e29b-41d4-a716-446655440000',
    },
  }),
});

const { data } = await response.json();
console.log(data.order);

Python

import os
import requests

query = """
query GetOrder($id: String) {
  order(id: $id) {
    id
    externalReference
    state
    lines {
      id
      sku
      quantity
      status
    }
  }
}
"""

response = requests.post(
    'https://api-v3.happycolis.com/graphql',
    headers={
        'Authorization': f'Bearer {os.environ["ACCESS_TOKEN"]}',
    },
    json={
        'query': query,
        'variables': {
            'id': '550e8400-e29b-41d4-a716-446655440000',
        },
    },
)

data = response.json()['data']
print(data['order'])

PHP

<?php
$query = <<<'GQL'
query GetOrder($id: String) {
  order(id: $id) {
    id
    externalReference
    state
    lines {
      id
      sku
      quantity
      status
    }
  }
}
GQL;

$payload = json_encode([
    'query'     => $query,
    'variables' => ['id' => '550e8400-e29b-41d4-a716-446655440000'],
]);

$ch = curl_init('https://api-v3.happycolis.com/graphql');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Authorization: Bearer ' . getenv('ACCESS_TOKEN'),
    ],
]);

$result = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($result['data']['order']);

Go

package main

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

func main() {
	query := `
		query GetOrder($id: String) {
			order(id: $id) {
				id
				externalReference
				state
				lines {
					id
					sku
					quantity
					status
				}
			}
		}`

	body, _ := json.Marshal(map[string]any{
		"query":     query,
		"variables": map[string]any{"id": "550e8400-e29b-41d4-a716-446655440000"},
	})

	req, _ := http.NewRequest("POST", "https://api-v3.happycolis.com/graphql", bytes.NewBuffer(body))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer "+os.Getenv("ACCESS_TOKEN"))

	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()

	var result map[string]any
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result["data"])
}