shipment

Retrieve a single shipment by its internal ID, including all tracking events, addresses, packed items, and the associated delivery order.

Required scope: view_shipments

---

Query

query GetShipment($shipmentId: String!) {
  shipment(shipmentId: $shipmentId) {
    id
    reference
    tracking
    trackingUrl
    carrierName
    state
    lastEvent
    addresses {
      type
      fullname
      address
      city
      zipcode
      country
    }
    details {
      sku
      quantity
    }
    events {
      nodes {
        event
        date
        message
        location
        city
        country
      }
    }
    location { id name }
    deliveryOrder { id orderNumber }
  }
}

---

Arguments

Argument	Type	Required	Description
shipmentId	String	✅	The internal UUID of the shipment

---

Example Variables

{
  "shipmentId": "ship_550e8400-e29b-41d4-a716-446655440000"
}

---

Example Response

{
  "data": {
    "shipment": {
      "id": "ship_550e8400-e29b-41d4-a716-446655440000",
      "reference": "REF-2024-001",
      "tracking": "6C12345678901",
      "trackingUrl": "https://www.laposte.fr/outils/suivre-vos-envois?code=6C12345678901",
      "carrierName": "Colissimo",
      "state": "OPENED",
      "lastEvent": "IN_TRANSIT",
      "addresses": [
        {
          "type": "RECIPIENT",
          "fullname": "Jane Smith",
          "address": "42 Rue de la Paix",
          "city": "Paris",
          "zipcode": "75001",
          "country": "FR"
        }
      ],
      "details": [
        { "sku": "TSHIRT-S-BLUE", "quantity": 2 }
      ],
      "events": {
        "nodes": [
          {
            "event": "NEW",
            "date": "2024-01-15T08:00:00.000Z",
            "message": "Label created",
            "location": null,
            "city": null,
            "country": null
          },
          {
            "event": "IN_TRANSIT",
            "date": "2024-01-15T14:30:00.000Z",
            "message": "Package in transit",
            "location": "Distribution Center",
            "city": "Lyon",
            "country": "FR"
          }
        ]
      },
      "location": {
        "id": "loc_123",
        "name": "paris-warehouse"
      },
      "deliveryOrder": {
        "id": "do_456",
        "orderNumber": "DO-2024-0001"
      }
    }
  }
}

---

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 GetShipment($shipmentId: String!) { shipment(shipmentId: $shipmentId) { id reference tracking trackingUrl carrierName state lastEvent addresses { type fullname address city zipcode country } details { sku quantity } events { nodes { event date message location city country } } location { id name } deliveryOrder { id orderNumber } } }",
    "variables": {
      "shipmentId": "ship_550e8400-e29b-41d4-a716-446655440000"
    }
  }'

Node.js

async function getShipment(accessToken, shipmentId) {
  const response = await fetch('https://api-v3.happycolis.com/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`,
    },
    body: JSON.stringify({
      query: `
        query GetShipment($shipmentId: String!) {
          shipment(shipmentId: $shipmentId) {
            id
            reference
            tracking
            trackingUrl
            carrierName
            state
            lastEvent
            addresses {
              type
              fullname
              address
              city
              zipcode
              country
            }
            details {
              sku
              quantity
            }
            events {
              nodes {
                event
                date
                message
                location
                city
                country
              }
            }
            location { id name }
            deliveryOrder { id orderNumber }
          }
        }
      `,
      variables: { shipmentId },
    }),
  });

  const { data, errors } = await response.json();
  if (errors) throw new Error(errors[0].message);
  return data.shipment;
}

const shipment = await getShipment(process.env.ACCESS_TOKEN, 'ship_550e8400-e29b-41d4-a716-446655440000');
console.log(shipment);

Python

import os
import requests

def get_shipment(access_token: str, shipment_id: str) -> dict:
    query = """
    query GetShipment($shipmentId: String!) {
      shipment(shipmentId: $shipmentId) {
        id
        reference
        tracking
        trackingUrl
        carrierName
        state
        lastEvent
        addresses {
          type
          fullname
          address
          city
          zipcode
          country
        }
        details {
          sku
          quantity
        }
        events {
          nodes {
            event
            date
            message
            location
            city
            country
          }
        }
        location { id name }
        deliveryOrder { id orderNumber }
      }
    }
    """
    response = requests.post(
        'https://api-v3.happycolis.com/graphql',
        headers={
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json',
        },
        json={'query': query, 'variables': {'shipmentId': shipment_id}},
    )
    result = response.json()
    if 'errors' in result:
        raise Exception(result['errors'][0]['message'])
    return result['data']['shipment']

shipment = get_shipment(os.environ['ACCESS_TOKEN'], 'ship_550e8400-e29b-41d4-a716-446655440000')
print(shipment)

PHP

<?php
$query = <<<'GQL'
query GetShipment($shipmentId: String!) {
  shipment(shipmentId: $shipmentId) {
    id
    reference
    tracking
    trackingUrl
    carrierName
    state
    lastEvent
    addresses {
      type
      fullname
      address
      city
      zipcode
      country
    }
    details {
      sku
      quantity
    }
    events {
      nodes {
        event
        date
        message
        location
        city
        country
      }
    }
    location { id name }
    deliveryOrder { id orderNumber }
  }
}
GQL;

$payload = json_encode([
    'query'     => $query,
    'variables' => ['shipmentId' => 'ship_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']['shipment']);

Go

package main

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

func getShipment(accessToken, shipmentID string) (map[string]interface{}, error) {
	query := `
		query GetShipment($shipmentId: String!) {
			shipment(shipmentId: $shipmentId) {
				id
				reference
				tracking
				trackingUrl
				carrierName
				state
				lastEvent
				addresses {
					type
					fullname
					address
					city
					zipcode
					country
				}
				details {
					sku
					quantity
				}
				events {
					nodes {
						event
						date
						message
						location
						city
						country
					}
				}
				location { id name }
				deliveryOrder { id orderNumber }
			}
		}`

	body, _ := json.Marshal(map[string]any{
		"query":     query,
		"variables": map[string]any{"shipmentId": shipmentID},
	})

	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 "+accessToken)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	var result map[string]any
	json.NewDecoder(resp.Body).Decode(&result)

	if errs, ok := result["errors"]; ok {
		return nil, fmt.Errorf("graphql error: %v", errs)
	}
	data := result["data"].(map[string]any)
	return data["shipment"].(map[string]any), nil
}

func main() {
	shipment, err := getShipment(os.Getenv("ACCESS_TOKEN"), "ship_550e8400-e29b-41d4-a716-446655440000")
	if err != nil {
		panic(err)
	}
	fmt.Println(shipment)
}