shipmentAddEvent

Appends a tracking event to a shipment. Use this mutation to push carrier milestones into the platform — either by polling a carrier API or receiving carrier webhooks — so that shipment status stays in sync.

Required scope: edit_shipments

---

Mutation

mutation ShipmentAddEvent($input: ShipmentAddEventInput!) {
  shipmentAddEvent(input: $input) {
    id
    lastEvent
    events {
      nodes {
        event
        date
        message
      }
    }
  }
}

---

Input — ShipmentAddEventInput

Field	Type	Required	Description
shipmentId	String	✅	ID of the shipment to update
event	ShippingEventEnum	✅	Event type (see Shipping Events)
date	DateTime	✅	Timestamp when the event occurred (ISO 8601)
message	String	❌	Human-readable description of the event
location	String	❌	Facility or location name (e.g. "Distribution Center")
city	String	❌	City where the event occurred
country	String	❌	ISO 3166-1 alpha-2 country code (e.g. "FR")

---

Example Variables

{
  "input": {
    "shipmentId": "ship_123",
    "event": "IN_TRANSIT",
    "date": "2024-01-15T14:30:00Z",
    "message": "Package in transit",
    "location": "Distribution Center",
    "city": "Lyon",
    "country": "FR"
  }
}

---

Example Response

{
  "data": {
    "shipmentAddEvent": {
      "id": "ship_123",
      "lastEvent": "IN_TRANSIT",
      "events": {
        "nodes": [
          {
            "event": "NEW",
            "date": "2024-01-15T08:00:00.000Z",
            "message": "Label created"
          },
          {
            "event": "IN_TRANSIT",
            "date": "2024-01-15T14:30:00.000Z",
            "message": "Package in transit"
          }
        ]
      }
    }
  }
}

---

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 ShipmentAddEvent($input: ShipmentAddEventInput!) { shipmentAddEvent(input: $input) { id lastEvent events { nodes { event date message } } } }",
    "variables": {
      "input": {
        "shipmentId": "ship_123",
        "event": "IN_TRANSIT",
        "date": "2024-01-15T14:30:00Z",
        "message": "Package in transit",
        "location": "Distribution Center",
        "city": "Lyon",
        "country": "FR"
      }
    }
  }'

Node.js

async function shipmentAddEvent(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 ShipmentAddEvent($input: ShipmentAddEventInput!) {
          shipmentAddEvent(input: $input) {
            id
            lastEvent
            events {
              nodes {
                event
                date
                message
              }
            }
          }
        }
      `,
      variables: { input },
    }),
  });

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

const result = await shipmentAddEvent(process.env.ACCESS_TOKEN, {
  shipmentId: 'ship_123',
  event: 'IN_TRANSIT',
  date: '2024-01-15T14:30:00Z',
  message: 'Package in transit',
  location: 'Distribution Center',
  city: 'Lyon',
  country: 'FR',
});

console.log(result.lastEvent); // "IN_TRANSIT"

Python

import os
import requests

def shipment_add_event(access_token: str, input_data: dict) -> dict:
    mutation = """
    mutation ShipmentAddEvent($input: ShipmentAddEventInput!) {
      shipmentAddEvent(input: $input) {
        id
        lastEvent
        events {
          nodes {
            event
            date
            message
          }
        }
      }
    }
    """
    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']['shipmentAddEvent']

result = shipment_add_event(os.environ['ACCESS_TOKEN'], {
    'shipmentId': 'ship_123',
    'event': 'IN_TRANSIT',
    'date': '2024-01-15T14:30:00Z',
    'message': 'Package in transit',
    'location': 'Distribution Center',
    'city': 'Lyon',
    'country': 'FR',
})
print(result['lastEvent'])

PHP

<?php
$mutation = <<<'GQL'
mutation ShipmentAddEvent($input: ShipmentAddEventInput!) {
  shipmentAddEvent(input: $input) {
    id
    lastEvent
    events {
      nodes {
        event
        date
        message
      }
    }
  }
}
GQL;

$payload = json_encode([
    'query'     => $mutation,
    'variables' => [
        'input' => [
            'shipmentId' => 'ship_123',
            'event'      => 'IN_TRANSIT',
            'date'       => '2024-01-15T14:30:00Z',
            'message'    => 'Package in transit',
            'location'   => 'Distribution Center',
            'city'       => 'Lyon',
            'country'    => 'FR',
        ],
    ],
]);

$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']['shipmentAddEvent']['lastEvent'];

Go

package main

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

func shipmentAddEvent(accessToken string, input map[string]any) (map[string]any, error) {
	mutation := `
		mutation ShipmentAddEvent($input: ShipmentAddEventInput!) {
			shipmentAddEvent(input: $input) {
				id
				lastEvent
				events {
					nodes {
						event
						date
						message
					}
				}
			}
		}`

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

func main() {
	result, err := shipmentAddEvent(os.Getenv("ACCESS_TOKEN"), map[string]any{
		"shipmentId": "ship_123",
		"event":      "IN_TRANSIT",
		"date":       "2024-01-15T14:30:00Z",
		"message":    "Package in transit",
		"location":   "Distribution Center",
		"city":       "Lyon",
		"country":    "FR",
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(result["lastEvent"])
}