Fake Shipment Tracking API

Q: Are the tracking numbers valid for real carriers?

No. SHP-... identifiers, carrier names and codes are explicitly fictional fixtures and must never be sent to a carrier tracking service.

Q: What do from and to constrain?

They bound the lifecycle anchor: shippedAt for handed-off shipments, or the label-created event for labelCreated/cancelled fixtures.

MOCK DATA

Coherent fake shipment tracking fixtures with status-specific nullable dates, chronological events, fictional carriers and country/date filters.

Generated test data for fixtures and development

Base URL: /api/shipments
Category: Commerce & Finance
Capabilities: 1 route Seedable
Last updated: July 29, 2026

GET /api/shipments Generate coherent fictional shipment timelines Returns a list

Live requestRuns against the public API

No key required

GET/api/shipments?service=express&originCountry=DK&destinationCountry=DE&count=5&seed=42

Request parameters

status

Pin every shipment to this lifecycle status. Omit for a weighted mix.

service

Pin economy, standard or express service; this controls transit duration.

originCountry

Pin the origin ISO alpha-2 code, case-insensitively. Supported: AU, BR, CA, DE, DK, ES, FR, GB, IT, JP, MX, NL, NO, SE, SG, US.

destinationCountry

Pin the destination ISO alpha-2 code; domestic (same-code) fixtures are allowed. Supported: AU, BR, CA, DE, DK, ES, FR, GB, IT, JP, MX, NL, NO, SE, SG, US.

from

Earliest lifecycle anchor. Defaults to 30 days before the resolved to value.

to

Latest lifecycle anchor. Defaults to the next UTC midnight, or 30 days after an explicit from. Must be ≥ from.

Advanced response options7 options

countdefault 10

How many records to generate (1–100).

seed

Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).

fields

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

exclude

Return all fields except these (comma-separated).

formatdefault json

Response format: json envelope, ndjson (one record per line) or csv.

prettydefault false

Pretty-print the JSON response.

unwrapdefault false

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples 13 params · 12 fields · 4 examples

Code samples Ready-to-copy requests in 4 languages

curl JavaScript Python PHP

curl "https://randomapi.dev/api/shipments?originCountry=DK&destinationCountry=DE&service=express&count=5&seed=42"

const res = await fetch("https://randomapi.dev/api/shipments?originCountry=DK&destinationCountry=DE&service=express&count=5&seed=42");
const { data, meta } = await res.json();

import requests

data = requests.get("https://randomapi.dev/api/shipments?originCountry=DK&destinationCountry=DE&service=express&count=5&seed=42").json()["data"]

$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/shipments?originCountry=DK&destinationCountry=DE&service=express&count=5&seed=42"
), true);
$data = $json["data"];

Parameters Route-specific request inputs 6

Parameter	Type	Default & allowed	Description
`status`	enum	allowed: labelCreated \| inTransit \| outForDelivery \| delivered \| exception \| cancelled example: inTransit	Pin every shipment to this lifecycle status. Omit for a weighted mix.
`service`	enum	allowed: economy \| standard \| express example: express	Pin economy, standard or express service; this controls transit duration.
`originCountry`	string	allowed: 2 – 2 example: DK	Pin the origin ISO alpha-2 code, case-insensitively. Supported: AU, BR, CA, DE, DK, ES, FR, GB, IT, JP, MX, NL, NO, SE, SG, US.
`destinationCountry`	string	allowed: 2 – 2 example: DE	Pin the destination ISO alpha-2 code; domestic (same-code) fixtures are allowed. Supported: AU, BR, CA, DE, DK, ES, FR, GB, IT, JP, MX, NL, NO, SE, SG, US.
`from`	date	example: 2026-05-01	Earliest lifecycle anchor. Defaults to 30 days before the resolved to value.
`to`	date	example: 2026-05-31	Latest lifecycle anchor. Defaults to the next UTC midnight, or 30 days after an explicit from. Must be ≥ from.

status enum

Pin every shipment to this lifecycle status. Omit for a weighted mix.

example: status=inTransit

service enum

Pin economy, standard or express service; this controls transit duration.

allowed: economy | standard | express

example: service=express

originCountry string

Pin the origin ISO alpha-2 code, case-insensitively. Supported: AU, BR, CA, DE, DK, ES, FR, GB, IT, JP, MX, NL, NO, SE, SG, US.

allowed: 2 – 2

example: originCountry=DK

destinationCountry string

Pin the destination ISO alpha-2 code; domestic (same-code) fixtures are allowed. Supported: AU, BR, CA, DE, DK, ES, FR, GB, IT, JP, MX, NL, NO, SE, SG, US.

allowed: 2 – 2

example: destinationCountry=DE

from date

Earliest lifecycle anchor. Defaults to 30 days before the resolved to value.

example: from=2026-05-01

to date

Latest lifecycle anchor. Defaults to the next UTC midnight, or 30 days after an explicit from. Must be ≥ from.

example: to=2026-05-31

Universal parameters Shared response and formatting options 7

Parameter	Type	Default & allowed	Description
`count`	int	default: 10 allowed: 1 – 100 example: 3	How many records to generate (1–100).
`seed`	int	example: 42	Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).
`fields`	list	example: id,trackingNumber	Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
`exclude`	list	example: events	Return all fields except these (comma-separated).
`format`	enum	default: json allowed: json \| ndjson \| csv example: csv	Response format: json envelope, ndjson (one record per line) or csv.
`pretty`	boolean	default: false example: true	Pretty-print the JSON response.
`unwrap`	boolean	default: false example: true	Drop the envelope: return the raw array/object without data/meta wrapper.

count int

How many records to generate (1–100).

default: 10

allowed: 1 – 100

example: count=3

seed int

Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).

example: seed=42

fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=id,trackingNumber

exclude list

Return all fields except these (comma-separated).

example: exclude=events

format enum

Response format: json envelope, ndjson (one record per line) or csv.

default: json

allowed: json | ndjson | csv

example: format=csv

pretty boolean

Pretty-print the JSON response.

default: false

example: pretty=true

unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false

example: unwrap=true

Response schema Fields returned in each record 12

Field	Type	Description	Example
`id`	string	Distinct shp_-prefixed synthetic shipment ID.	shp_42ce8f30a91bd572_00
`trackingNumber`	string	Clearly generic SHP-{internal carrier}-{fixture} value; not a real carrier format.	SHP-PLM-7QK4M8X2RP-00
`carrier`	object	Fictional carrier name and internal three-letter fixture code.	{"name":"Parcel Loom (fictional)","code":"PLM"}
`status`	string	labelCreated \| inTransit \| outForDelivery \| delivered \| exception \| cancelled.	inTransit
`service`	string	economy \| standard \| express; controls the synthetic transit-day range.	standard
`origin`	object	Synthetic city plus canonical supported ISO country code and country name.	{"countryCode":"DK","country":"Denmark","city":"Copenhagen"}
`destination`	object	Synthetic destination city/country. Domestic shipments are allowed.	{"countryCode":"DE","country":"Germany","city":"Berlin"}
`weightKg`	float	Synthetic parcel weight from 0.1 to 30 kilograms.	4.75
`shippedAt` nullable	string (ISO 8601)	Handoff time for inTransit/outForDelivery/delivered/exception; null for labelCreated and pre-handoff cancelled fixtures.	2026-06-03T09:15:00.000Z
`estimatedDelivery` nullable	string (ISO 8601)	Synthetic estimate after handoff; null for labelCreated and cancelled fixtures.	2026-06-07T09:15:00.000Z
`deliveredAt` nullable	string (ISO 8601)	Final delivery time only when status=delivered; null for every other status.	null
`events`	object[]	Chronological synthetic lifecycle events; the last event status always equals the top-level status.	[{"status":"labelCreated","timestamp":"2026-06-02T12:00:00.000Z","location":"Copenhagen, Denmark","description":"Shipping label created"}]

id string

Distinct shp_-prefixed synthetic shipment ID.

example: shp_42ce8f30a91bd572_00

trackingNumber string

Clearly generic SHP-{internal carrier}-{fixture} value; not a real carrier format.

example: SHP-PLM-7QK4M8X2RP-00

carrier object

Fictional carrier name and internal three-letter fixture code.

example: {"name":"Parcel Loom (fictional)","code":"PLM"}

status string

example: inTransit

service string

economy | standard | express; controls the synthetic transit-day range.

example: standard

origin object

Synthetic city plus canonical supported ISO country code and country name.

example: {"countryCode":"DK","country":"Denmark","city":"Copenhagen"}

destination object

Synthetic destination city/country. Domestic shipments are allowed.

example: {"countryCode":"DE","country":"Germany","city":"Berlin"}

weightKg float

Synthetic parcel weight from 0.1 to 30 kilograms.

example: 4.75

shippedAt string (ISO 8601) nullable

Handoff time for inTransit/outForDelivery/delivered/exception; null for labelCreated and pre-handoff cancelled fixtures.

example: 2026-06-03T09:15:00.000Z

estimatedDelivery string (ISO 8601) nullable

Synthetic estimate after handoff; null for labelCreated and cancelled fixtures.

example: 2026-06-07T09:15:00.000Z

deliveredAt string (ISO 8601) nullable

Final delivery time only when status=delivered; null for every other status.

example: null

events object[]

Chronological synthetic lifecycle events; the last event status always equals the top-level status.

example: [{"status":"labelCreated","timestamp":"2026-06-02T12:00:00.000Z","location":"Copenhagen, Denmark","description":"Shipping label created"}]

Documented examples

Build-generated requests and complete responses 4

Express parcels from Denmark to Germany /api/shipments?originCountry=DK&destinationCountry=DE&service=express&count=5&seed=42

GET /api/shipments?originCountry=DK&destinationCountry=DE&service=express&count=5&seed=42

{
  "data": [
    {
      "id": "shp_cfb6a5c85eac58cd_00",
      "trackingNumber": "SHP-NSP-5KA8ZDMSNG-00",
      "carrier": {
        "name": "Northstar Parcel (fictional)",
        "code": "NSP"
      },
      "status": "outForDelivery",
      "service": "express",
      "origin": {
        "countryCode": "DK",
        "country": "Denmark",
        "city": "Aarhus"
      },
      "destination": {
        "countryCode": "DE",
        "country": "Germany",
        "city": "Hamburg"
      },
      "weightKg": 23.24,
      "shippedAt": "2026-07-09T13:44:41.776Z",
      "estimatedDelivery": "2026-07-10T13:44:41.776Z",
      "deliveredAt": null,
      "events": [
        {
          "status": "labelCreated",
          "timestamp": "2026-07-08T23:44:41.776Z",
          "location": "Aarhus, Denmark",
          "description": "Shipping label created"
        },
        {
          "status": "inTransit",
          "timestamp": "2026-07-09T13:44:41.776Z",
          "location": "Aarhus, Denmark",
          "description": "Parcel accepted into the fictional carrier network"
        },
        {
          "status": "outForDelivery",
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

Delivered shipment histories /api/shipments?status=delivered&count=10&seed=8

GET /api/shipments?status=delivered&count=10&seed=8

{
  "data": [
    {
      "id": "shp_c498125864a0ce7e_00",
      "trackingNumber": "SHP-ATD-4AM4NKJCSZ-00",
      "carrier": {
        "name": "Atlas Dispatch (fictional)",
        "code": "ATD"
      },
      "status": "delivered",
      "service": "standard",
      "origin": {
        "countryCode": "SE",
        "country": "Sweden",
        "city": "Stockholm"
      },
      "destination": {
        "countryCode": "NO",
        "country": "Norway",
        "city": "Bergen"
      },
      "weightKg": 22.83,
      "shippedAt": "2026-07-01T01:29:49.539Z",
      "estimatedDelivery": "2026-07-07T01:29:49.539Z",
      "deliveredAt": "2026-07-07T01:29:49.539Z",
      "events": [
        {
          "status": "labelCreated",
          "timestamp": "2026-06-30T09:29:49.539Z",
          "location": "Stockholm, Sweden",
          "description": "Shipping label created"
        },
        {
          "status": "inTransit",
          "timestamp": "2026-07-01T01:29:49.539Z",
          "location": "Stockholm, Sweden",
          "description": "Parcel accepted into the fictional carrier network"
        },
        {
          "status": "outForDelivery",
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

Exception states in a fixed window /api/shipments?status=exception&from=2026-05-01&to=2026-05-31&count=8&seed=19

GET /api/shipments?status=exception&from=2026-05-01&to=2026-05-31&count=8&seed=19

{
  "data": [
    {
      "id": "shp_6c926a42926470d3_00",
      "trackingNumber": "SHP-RFN-V74WDRDDK6-00",
      "carrier": {
        "name": "Route Finch (fictional)",
        "code": "RFN"
      },
      "status": "exception",
      "service": "economy",
      "origin": {
        "countryCode": "BR",
        "country": "Brazil",
        "city": "Rio de Janeiro"
      },
      "destination": {
        "countryCode": "NO",
        "country": "Norway",
        "city": "Oslo"
      },
      "weightKg": 21.17,
      "shippedAt": "2026-05-25T10:36:28.924Z",
      "estimatedDelivery": "2026-06-01T10:36:28.924Z",
      "deliveredAt": null,
      "events": [
        {
          "status": "labelCreated",
          "timestamp": "2026-05-24T22:36:28.924Z",
          "location": "Rio de Janeiro, Brazil",
          "description": "Shipping label created"
        },
        {
          "status": "inTransit",
          "timestamp": "2026-05-25T10:36:28.924Z",
          "location": "Rio de Janeiro, Brazil",
          "description": "Parcel accepted into the fictional carrier network"
        },
        {
          "status": "exception",
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

Domestic label-created fixtures /api/shipments?status=labelCreated&originCountry=US&destinationCountry=US&count=5&seed=3

GET /api/shipments?status=labelCreated&originCountry=US&destinationCountry=US&count=5&seed=3

{
  "data": [
    {
      "id": "shp_b5997db2587da780_00",
      "trackingNumber": "SHP-CPP-9NX5K2P7KC-00",
      "carrier": {
        "name": "Copper Post (fictional)",
        "code": "CPP"
      },
      "status": "labelCreated",
      "service": "standard",
      "origin": {
        "countryCode": "US",
        "country": "United States",
        "city": "New York"
      },
      "destination": {
        "countryCode": "US",
        "country": "United States",
        "city": "New York"
      },
      "weightKg": 25.15,
      "shippedAt": null,
      "estimatedDelivery": null,
      "deliveredAt": null,
      "events": [
        {
          "status": "labelCreated",
          "timestamp": "2026-06-30T19:45:32.203Z",
          "location": "New York, United States",
          "description": "Shipping label created"
        }
      ]
    },
    {
      "id": "shp_df9c8647128ae163_01",
      "trackingNumber": "SHP-ATD-TWQ3MXZZES-01",
      "carrier": {
        "name": "Atlas Dispatch (fictional)",
        "code": "ATD"
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

About this API

Coverage, behavior and common use cases

Coverage & behavior

Generates parcel-tracking fixtures whose lifecycle fields agree with one another. Everything is synthetic: carrier brands, internal codes and SHP-... tracking values deliberately do not claim compatibility with DHL, UPS, FedEx or any postal operator.

Status controls a strict shape while every nullable date key remains present:

labelCreated: one label event; shippedAt, estimatedDelivery and deliveredAt are null.
cancelled: a label then pre-handoff cancellation; all three top-level dates are null.
inTransit, outForDelivery and exception: a handoff time and estimate, but no delivery time.
delivered: handoff, out-for-delivery and delivery events in order; deliveredAt is non-null and no later than the synthetic estimate.

Events are chronological and the final event's status always equals the record's top-level status. service controls the transit range (economy slower, express faster). originCountry/destinationCountry accept a documented 16-code ISO subset case-insensitively; domestic shipments are intentionally allowed.

from/to constrain the lifecycle anchor: shippedAt after handoff, or the label-created event for labelCreated/cancelled. Omitted bounds resolve to the 30 days ending at the next UTC midnight and are echoed in meta.params, making a seeded request stable throughout the UTC day.

Use it for

Exercise every parcel-tracking timeline and empty-date UI state
Populate fulfilment dashboards with reproducible domestic and international fixtures
Test chronological event rendering and estimated-versus-delivered date logic

Frequently asked questions

Practical answers about this endpoint 4

Are the tracking numbers valid for real carriers?

No. SHP-... identifiers, carrier names and codes are explicitly fictional fixtures and must never be sent to a carrier tracking service.

Do shipment dates match the selected status?

Yes. Label-created and pre-handoff cancelled records keep all top-level dates null; only delivered records have deliveredAt, and all event timelines are chronological.

Can origin and destination use the same country?

Yes. Domestic shipment fixtures are valid; the two filters constrain countries, not individual physical addresses.

What do from and to constrain?

They bound the lifecycle anchor: shippedAt for handed-off shipments, or the label-created event for labelCreated/cancelled fixtures.

Useful next tools in the catalog

Fake Order Data API MOCK DATA

Internally consistent fake orders with exact line-item totals, currency precision, lifecycle dates, payment state and generic tracking fixtures.

Fake Transaction Data API MOCK DATA

Fake account transactions with realistic merchants, weighted statuses and currency-correct amounts — filter by type, status, amount range and date window.

Fake Product Data API MOCK DATA

Fake e-commerce products with category-themed names, prices in real currencies (whole yen for JPY), valid EAN-13 barcodes, SKUs, ratings and image URLs.

Fake Address API MOCK DATA

Locale-aware fake postal addresses — street, city, state, zip, country and coordinates that all agree, plus a one-line formatted form in the local layout.