shipmentCreate

Creates a shipment manually and associates it with a DeliveryOrder. Use this mutation when the warehouse does not automatically create shipments — for example when integrating with a carrier outside of the standard fulfillment flow.

Required scope: create_shipments

---

Mutation

mutation ShipmentCreate($input: ShipmentInput!) {
  shipmentCreate(input: $input) {
    id
    shipment {
      id
      tracking
      trackingUrl
      state
    }
  }
}

---

Input — ShipmentInput

Field	Type	Required	Description
deliveryOrderId	String	✅	ID of the parent delivery order
carrierName	String	✅	Carrier name (e.g. "Colissimo", "DHL", "UPS")
tracking	String	❌	Carrier tracking number
trackingUrl	String	❌	Full URL to track the parcel on the carrier website
reference	String	❌	Internal reference for this shipment
weight	Float	❌	Package weight in kilograms
details	[ShipmentDetailInput!]	❌	List of items packed (SKU + quantity)

ShipmentDetailInput

Field	Type	Required	Description
sku	String	✅	Product variant SKU
quantity	Int	✅	Number of units packed

---

Example Variables

{
  "input": {
    "deliveryOrderId": "do_123",
    "carrierName": "Colissimo",
    "tracking": "6C12345678901",
    "trackingUrl": "https://www.laposte.fr/outils/suivre-vos-envois?code=6C12345678901",
    "reference": "REF-2024-001",
    "weight": 1.5,
    "details": [
      { "sku": "TSHIRT-S-BLUE", "quantity": 2 }
    ]
  }
}

---

Example Response

{
  "data": {
    "shipmentCreate": {
      "id": "req_abc123",
      "shipment": {
        "id": "ship_550e8400-e29b-41d4-a716-446655440000",
        "tracking": "6C12345678901",
        "trackingUrl": "https://www.laposte.fr/outils/suivre-vos-envois?code=6C12345678901",
        "state": "OPENED"
      }
    }
  }
}

---

Code Examples

curl

curl -X POST https://api-v3.happycolis.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "query": "mutation ShipmentCreate($input: ShipmentInput!) { shipmentCreate(input: $input) { id shipment { id tracking trackingUrl state } } }",
    "variables": {
      "input": {
        "deliveryOrderId": "do_123",
        "carrierName": "Colissimo",
        "tracking": "6C12345678901",
        "trackingUrl": "https://www.laposte.fr/outils/suivre-vos-envois?code=6C12345678901",
        "reference": "REF-2024-001",
        "weight": 1.5,
        "details": [{ "sku": "TSHIRT-S-BLUE", "quantity": 2 }]
      }
    }
  }'

Node.js

async function createShipment(accessToken, input) {
  const response = await fetch('https://api-v3.happycolis.com/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`,
    },
    body: JSON.stringify({
      query: `
        mutation ShipmentCreate($input: ShipmentInput!) {
          shipmentCreate(input: $input) {
            id
            shipment {
              id
              tracking
              trackingUrl
              state
            }
          }
        }
      `,
      variables: { input },
    }),
  });

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

const result = await createShipment(process.env.ACCESS_TOKEN, {
  deliveryOrderId: 'do_123',
  carrierName: 'Colissimo',
  tracking: '6C12345678901',
  trackingUrl: 'https://www.laposte.fr/outils/suivre-vos-envois?code=6C12345678901',
  reference: 'REF-2024-001',
  weight: 1.5,
  details: [{ sku: 'TSHIRT-S-BLUE', quantity: 2 }],
});

console.log(result.shipment.id);

Python

import os
import requests

def create_shipment(access_token: str, input_data: dict) -> dict:
    mutation = """
    mutation ShipmentCreate($input: ShipmentInput!) {
      shipmentCreate(input: $input) {
        id
        shipment {
          id
          tracking
          trackingUrl
          state
        }
      }
    }
    """
    response = requests.post(
        'https://api-v3.happycolis.com/graphql',
        headers={
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json',
        },
        json={'query': mutation, 'variables': {'input': input_data}},
    )
    result = response.json()
    if 'errors' in result:
        raise Exception(result['errors'][0]['message'])
    return result['data']['shipmentCreate']

result = create_shipment(os.environ['ACCESS_TOKEN'], {
    'deliveryOrderId': 'do_123',
    'carrierName': 'Colissimo',
    'tracking': '6C12345678901',
    'trackingUrl': 'https://www.laposte.fr/outils/suivre-vos-envois?code=6C12345678901',
    'reference': 'REF-2024-001',
    'weight': 1.5,
    'details': [{'sku': 'TSHIRT-S-BLUE', 'quantity': 2}],
})
print(result['shipment']['id'])

PHP

<?php
$mutation = <<<'GQL'
mutation ShipmentCreate($input: ShipmentInput!) {
  shipmentCreate(input: $input) {
    id
    shipment {
      id
      tracking
      trackingUrl
      state
    }
  }
}
GQL;

$payload = json_encode([
    'query'     => $mutation,
    'variables' => [
        'input' => [
            'deliveryOrderId' => 'do_123',
            'carrierName'     => 'Colissimo',
            'tracking'        => '6C12345678901',
            'trackingUrl'     => 'https://www.laposte.fr/outils/suivre-vos-envois?code=6C12345678901',
            'reference'       => 'REF-2024-001',
            'weight'          => 1.5,
            'details'         => [['sku' => 'TSHIRT-S-BLUE', 'quantity' => 2]],
        ],
    ],
]);

$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);

echo $result['data']['shipmentCreate']['shipment']['id'];

Go

package main

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

func createShipment(accessToken string, input map[string]any) (map[string]any, error) {
	mutation := `
		mutation ShipmentCreate($input: ShipmentInput!) {
			shipmentCreate(input: $input) {
				id
				shipment {
					id
					tracking
					trackingUrl
					state
				}
			}
		}`

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

	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["shipmentCreate"].(map[string]any), nil
}

func main() {
	result, err := createShipment(os.Getenv("ACCESS_TOKEN"), map[string]any{
		"deliveryOrderId": "do_123",
		"carrierName":     "Colissimo",
		"tracking":        "6C12345678901",
		"trackingUrl":     "https://www.laposte.fr/outils/suivre-vos-envois?code=6C12345678901",
		"reference":       "REF-2024-001",
		"weight":          1.5,
		"details":         []map[string]any{{"sku": "TSHIRT-S-BLUE", "quantity": 2}},
	})
	if err != nil {
		panic(err)
	}
	shipment := result["shipment"].(map[string]any)
	fmt.Println(shipment["id"])
}