Relay API v2 (2.0.106)

The Relay v2 Shipping API is designed to let retailers and marketplaces start shipping with Relay fast.

You'll need to contact Relay at dev-support@relaytech.co to request an API key and register your retailer locations (warehouses).

The Relay API uses HTTP Bearer Authentication. This means that to let us know it's really you calling the Relay API, you'll need to include a header in your request of the form Relay-Authorization: Bearer $YOUR_API_KEY. We also require that all requests to the API be made over HTTPS.

We attempt to follow a few conventions throughout the API:

• Metric system: Weights, measures, distances, etc. are all reported using SI units and their multiples/submultiples.
• UTC time: Dates and times are all reported in Coordinated Universal Time.
• ISO formats: Where a commonly-used ISO format exists to represent structured data, such as dates, country codes, etc., we aim to use these standard formats.

The current shipment status and its history can be accessed through the status and events fields respectively. Events offer more context for status changes but please note that multiple events can map to the same status.

Events

Events tell you what happened to a parcel, in more detail than its status alone. Several events can lead to the same status.

We send event names in one of two sets:

• 2.1 — the current set, and what we recommend for new integrations.
• 2.0 — the original set, still sent to existing integrations.

Your integration receives one set or the other, so use the matching tab below: the same moment in a parcel's journey can have a different name in each. If you're not sure which set you receive, email dev-support@relaytech.co.

Build your tracking logic on event_name. It is the most specific signal we send — 2.1 gives separate names to situations that 2.0 reported under a single name, while status and event_category are deliberately broader.

In the 2.1 table, the Shipment Status column shows the status a shipment holds when the event is sent; a dash means the event leaves the shipment's status unchanged.

Statuses

Event Categories

Locations where end customers can pick up / drop off their parcels

Manage creating and tracking shipments

The services Relay supports between two points

Network coverage and exclusions

Webhook subscription management and event notifications

When events occur, Relay sends a POST request to your webhook URL with a JSON payload:

{
  "event_name": "handed_to_customer",
  "event_category": "delivered",
  "occurred_at": "2024-01-15T14:30:00Z",
  "shipment_code": "RELAY123456",
  "status": "delivered",
  "status_description": "Delivered",
  "event_history": [...],
  "event_details": {...}
}

Some webhook events include additional details in an event_details field (only available with the default presenter).

Events with Event Details

Address Change Example

{
  "old_address": {
    "organisation": null,
    "line1": "123 Example Street",
    "line2": "Flat 4",
    "line3": null,
    "line4": null,
    "town": "London",
    "county": null,
    "postcode": "SW1A 1AA",
    "country_iso": "GBR",
    "lat": null,
    "lon": null
  },
  "old_pudo_code": "PST001",
  "new_address": {
    "organisation": null,
    "line1": "123 Example Street",
    "line2": "Flat 4",
    "line3": null,
    "line4": null,
    "town": "London",
    "county": null,
    "postcode": "SW1A 1AA",
    "country_iso": "GBR",
    "lat": null,
    "lon": null
  },
  "new_pudo_code": "PST002",
  "changed_at": "2024-01-15T14:30:00.000000+00:00"
}

Proof of Delivery Example

[{
  "image": "https://storage.googleapis.com/example/pod-image.jpg",
  "captured_at": "2024-01-15T14:30:00.000000+00:00",
  "coordinates": {
    "lat": 51.5074,
    "lon": -0.1278
  }
}, {
  "image": "https://storage.googleapis.com/example/pod-image-2.jpg",
  "captured_at": "2024-01-15T14:30:00.000000+00:00",
  "coordinates": {
    "lat": 51.5074,
    "lon": -0.1278
  }
}]

Handover Details Example

{
  "handover_code": "RELHO12345678",
  "handover_qr_code": "https://relay-production.relaytechapis.co/v0/customer-portal/qr-code?collection_code=RELHO12345678",
  "pudo_code": "PST001",
  "handover_window_begins": "2024-01-15T08:00:00.000000+00:00",
  "handover_window_ends": "2024-01-22T18:00:00.000000+00:00"
}

Delivery Failure Example

{
  "failure_reason": "no_answer_from_customer",
  "failure_reason_description": "No Answer from Customer"
}

Oversized Evidence Example

{
  "dimensions": {
    "length_cm": 120.0,
    "width_cm": 80.0,
    "height_cm": 60.0
  },
  "images": null
}

All webhook requests include an x-relay-signature header containing an HMAC-SHA256 signature of the payload. Use your webhook signing key to verify the signature and ensure the request is from Relay.