The Trackberry API

Goal #

Read your organization’s shipment data from a script, a spreadsheet tool, a BI dashboard or your own system, without exporting files by hand.

The API is read-only, with a few exceptions: a token you create as “Read and write” can also make and revoke the tracking links you give your customers (see Customer links), upload documents for Trackberry to read (see Documents to data), pre-allocate boxes to your customers (see Pre-allocations) and add notes to a shipment (see Shipment notes), plus a few reversible actions on a shipment (see Shipment actions). Everything else returns what you can already see in Trackberry, as JSON, for one organization at a time. Changing or approving shipments still happens by email, upload or in the app.

For AI agents and code generators #

The whole API is described in one OpenAPI 3.1 file that needs no token: https://trackberry.com/api/v1/openapi.json. Give that URL to your coding agent, or load it into a code generator or an API client such as Postman or Insomnia. It has every endpoint, parameter, enum value and field, each with a plain-language description of what it means for the business (for example how effective_eta, eta, original_eta and predicted_eta differ). It always describes the latest API version.

A few facts worth knowing before generating code:

• Every field is always present. A field with no value is null, never missing, so declare nullable types instead of optional ones.
• Ignore fields and enum values you don’t recognize. New ones are added without a new version.
• Lists of shipments, alerts, checks, companies, products, purchase orders and expected containers are paged with limit and starting_after; the other lists are not paged.
• The file is also linked from llms.txt, for agents that start there.

The rest of this page is the same contract written for people.

Create a token #

1. Go to Organization settings → API & webhooks (API if you are not an admin), at /your-slug/settings/api.
2. Click Create token, give it a name that says where it will live (“Power BI refresh”, “ERP sync”), pick when it expires and choose its access (below).
3. Copy the token. It is shown once. Trackberry only keeps a fingerprint of it, so nobody, including our team, can show it to you again. If you lose it, revoke it and create a new one.

A token belongs to you and to one organization. It can read everything you can read in that organization. Its access is one of:

• Read only (the default): it can call every GET endpoint.
• Read and write: it can also create and revoke customer tracking links, upload documents, pre-allocate boxes and write shipment notes, and nothing else; no other part of the API writes yet. Choose it only for the system that needs it, such as your ERP, and keep Power BI and other readers on read-only tokens.

A read-and-write token is only as powerful as you are. If an admin makes you a read-only member, its write calls stop working while its reads continue. The settings list shows each token’s access.

Members can create tokens for themselves; Viewers can’t. Admins and owners can see and revoke every token in the organization.

You can hold up to 10 live tokens per organization. Expired and revoked tokens don’t count. If you try to create an 11th, the form shows “You already have 10 active tokens for this organization. Revoke one first.” Click Revoke next to a token you no longer use, then try again.

A token stops working when:

• it expires (30 days, 90 days, 1 year, or never, chosen when you create it),
• someone revokes it in settings,
• you leave the organization or are removed from it.

Tokens start with tb_ followed by 40 letters and digits. If you run a secret scanner, this pattern finds them: \btb_[A-Za-z0-9]{40}\b. Treat a token like a password: keep it in your secret store, never in a spreadsheet cell or a public repository.

Make a request #

The base URL is https://trackberry.com/api/v1. Send the token in the Authorization header:

curl https://trackberry.com/api/v1/organization \
  -H "Authorization: Bearer tb_your_token"

{
  "object": "organization",
  "id": "org_42",
  "name": "Fresh Imports Ltd",
  "slug": "fresh-imports",
  "api_version": "2026-10-01",
  "token": { "id": "tok_7", "name": "ERP sync", "scopes": ["read"], "expires_at": "2027-09-29T10:00:00Z", "user_email": "[email protected]" }
}

There is no organization slug in the URLs: the token already says which organization you are reading.

Versions #

The API is versioned, so an integration you write today keeps working as the API grows.

• Each version is named after the day it was released, such as 2026-10-01.
• Your organization is pinned to the latest version the first time it calls the API without a Trackberry-Version header. Every later response uses that shape until an admin moves the organization forward from Organization settings → API & webhooks.
• To try a newer version before switching, send it with a single request: Trackberry-Version: 2026-10-01. That does not change the pin.
• Successful responses include a Trackberry-Version header with the version they were built for.

New fields, new endpoints and new values in a status list are added to every version, so your code should ignore fields it doesn’t recognize. Anything that removes, renames or changes the meaning of a field gets a new version, dated like the ones above, and the change is announced in these docs. There have been no breaking changes since 2026-10-01, the first version.

IDs, lists and formats #

• IDs are strings with a prefix that names the kind of object: shp_ for shipments, ctr_ containers, doc_ documents, alr_ alerts, chk_ checks, pkl_ packing lists, lbl_ labels, org_ organizations, cmp_ companies, tok_ tokens, leg_ route legs, evt_ tracking events, eta_ ETA revisions, plt_ pallets, pln_ packing lines, shl_ customer links, whs_ warehouses, wcl_ warehouse closures, prd_ products, por_ purchase orders, pol_ purchase order lines and exs_ expected containers. Treat them as opaque; pass them back exactly as you received them. An id with the wrong prefix, or from another organization, is a 404 when it is in the path.
• Lists come back as { "object": "list", "data": [...], "has_more": true }, newest first. Ask for up to 100 items with limit (default 25). To get the next page, pass the id of the last item you received as starting_after, and stop when has_more is false. Items that arrive while you page don’t cause gaps or repeats.
• Times are UTC in ISO 8601 (2026-09-29T14:03:00Z); calendar days are 2026-09-29. Filters accept either.
• Weights are kilograms (net_weight_kg), even for an organization that shows pounds on screen. Temperatures are Celsius (temperature_celsius), and statuses are lowercase strings (in_transit).
• Fields with no value are null, never missing. Empty lists are [].

Endpoints #

All endpoints are GET, except the two that make and revoke customer links, the one that uploads a document, the three that change pre-allocations and the two that write a shipment’s notes, and the ones listed under Shipment actions.

Searching shipments #

/shipments accepts these parameters, all optional:

curl "https://trackberry.com/api/v1/shipments?status=in_transit&eta_before=2026-10-07" \
  -H "Authorization: Bearer tb_your_token"

Sharing a tracking link #

Every shipment object has a public_tracking_url: the shipment’s public tracking page, which anyone with the link can open without logging in. Send it to a customer or partner instead of giving them access to Trackberry. It is the English page; put /es before /track to get the Spanish one (https://trackberry.com/es/track/...).

The field is null when your organization has public tracking pages turned off (in the organization’s settings), or when the shipment is archived or not yet validated, because the page does not show those. The link can’t be guessed, and it changes if someone regenerates the shipment’s link in Trackberry, so read it from the API when you need it rather than storing it.

Customer links #

A customer link is a tracking link made for one of your own customers. It opens the ordinary public tracking page, but leads with the customer’s own order number (“Your order: PO-4471”) instead of a container number they never asked about. It can be switched off on its own without touching the generic link or any other customer’s. You can make them by hand from the shipment page; the API lets your ERP do it for you.

A typical flow for an importer whose ERP holds the sales orders:

1. When the order is confirmed or the delivery note is printed, find the shipment: GET /shipments?q=MSCU1234567 with the container number or B/L from the order, and take the id of the match.
2. Make the link with that id and your order number:

   curl -X POST https://trackberry.com/api/v1/shipments/shp_812/share_links \
     -H "Authorization: Bearer tb_your_write_token" \
     -H "Content-Type: application/json" \
     -d '{"customer_reference": "PO-4471", "label": "Fresh Direct"}'

The response is the link, and its url is what you give the customer. 3. Store the url on the sales order or print it on the delivery note. You can read it again at any time with GET /share_links/{id}. 4. If the order is cancelled, DELETE /share_links/{id} revokes it. The URL stops opening at once and the customer’s tracking emails through it stop.

Creating is safe to repeat. If the shipment already has an active link with the same customer_reference (compared after trimming extra spaces, and case-sensitive), you get that link back with a 200 instead of a second one with a 201, so a retry after a timeout never doubles up. A repeat returns the existing link unchanged: its label is not updated, and a different label on the retry is ignored. Revoke a link and ask again and you get a new one. label is a note for your own team; the customer never sees it.

Creating needs public tracking pages to be turned on for your organization and a shipment that is live (validated or further along, and not archived), the same rules as the button on the shipment page. Otherwise the call is a 400 with code not_shareable. Every link made or revoked this way is recorded in the shipment’s activity log, marked as made through the API, with the member who owns the token. An admin or owner can revoke any link; a member can revoke only links made with their own tokens or on the shipment page.

Pre-allocations #

A pre-allocation sets boxes of one packing line aside for a customer, with an optional tentative price, the same as the “Pre-allocate” action on a packing table in Trackberry. The API lets a script or an assistant see what is taken and change it.

1. Read the packing lists with GET /shipments/{id}/packing_lists. Each line has a box_count and a preallocated_boxes, the boxes already set aside; the difference is what is still free.
2. See who holds what with GET /shipments/{id}/preallocations: every pre-allocation on the shipment, with the packing_line_id and pallet_id it belongs to.
3. Set boxes aside with POST /packing_lines/{packing_line_id}/preallocations:

   curl -X POST https://trackberry.com/api/v1/packing_lines/pln_5521/preallocations \
     -H "Authorization: Bearer tb_your_write_token" \
     -H "Content-Type: application/json" \
     -d '{"allocatee": "Fresh Direct", "boxes": 40, "unit_price": 12.5, "currency": "EUR"}'

The boxes on a line cannot add up to more than its box_count; if they would, the call is a 400 naming boxes that says how many are left. unit_price is the price per box, or, with "price_basis": "total", the total for these boxes (it is stored as a price per box). Without a price there is no currency and no value. 4. Change or release it with PATCH /preallocations/{id} (only the fields you send change; "unit_price": null removes the price) and DELETE /preallocations/{id}.

Each POST adds one pre-allocation: sending it twice sets the boxes aside twice (or fails if there are not enough boxes), so after a timeout list the shipment’s pre-allocations before you retry. Every change is recorded in the activity log of the pallet, marked as made through the API, with the member who owns the token. A token owned by a read-only member can read pre-allocations but not change them (403 read_only_member).

Shipment notes #

Every shipment has free-text notes, written in Markdown, shown on its page and returned as notes on GET /shipments/{id}. Two calls write them:

• POST /shipments/{shipment_id}/notes with {"text": "..."} adds a paragraph after what is there, separated by a blank line. It never removes anything, so a script or an assistant cannot wipe what a colleague wrote. Sending the same text twice adds it twice.
• PUT /shipments/{shipment_id}/notes with {"notes": "..."} replaces the whole text, and an empty string clears it. Use it only when you hold the full text and mean to overwrite it.

Both answer with the notes as they now stand. The notes are limited to 20,000 characters (a 400 naming text or notes otherwise). A change is recorded in the shipment’s activity log as a notes change made through the API, and, like edits in the app, several changes by the same person within two minutes are shown as one entry.

Shipment actions #

A few reversible actions on a shipment, its checks and its alerts need a “Read and write” token, and are what the same buttons do in the app:

• Labels. POST /shipments/{shipment_id}/labels with {"label": "urgent"} (the words a person would use, which find “🔥 Urgent”, or an id from GET /labels) and DELETE /shipments/{shipment_id}/labels/{label}. Labels are not created through the API; an unknown name is a 404 that lists the existing ones, and one that fits several is a 400 ambiguous_label naming them with their ids. Both are idempotent.
• Checks. POST /shipments/{shipment_id}/check_runs queues the shipment’s checks again. POST /checks/{check_id}/acknowledgement with a reason accepts a failing check and DELETE on it withdraws that (admins and owners only, like the app); there is no “skip”, which overwrites the result.
• Tracking. POST /shipments/{shipment_id}/tracking_refreshes asks for fresh tracking. Each refresh costs a request to the tracking service, so a shipment is refreshed at most once every 5 minutes (429 refresh_too_soon with Retry-After).
• Alerts. POST /alerts/{alert_id}/snooze (days: 1, 3 or 7), /dismissal and /restoration hide an alert for a while, for as long as the problem lasts, and bring it back.
• Archive and warehouse. POST and DELETE /shipments/{shipment_id}/archive, and POST /shipments/{shipment_id}/warehouse_arrival (admins and owners only), which sets the status to in_warehouse.

Repeating a call that already took effect answers the same and changes nothing. Changes to labels, archiving, acknowledgements and warehouse arrivals are recorded in the shipment’s activity log as made through the API, with the member who owns the token; snoozing, dismissing and restoring an alert are recorded as alert.snoozed, alert.dismissed and alert.restored. A token owned by a read-only member can read but not change anything (403 read_only_member).

Documents to data #

Trackberry reads loading sheets, packing lists, invoices and bills of lading and turns them into fields your ERP can import, the same way it reads the documents you email in. The API lets your system send it files directly, whether or not you track the shipment with Trackberry.

A typical flow for an importer whose ERP needs the figures from a supplier’s loading sheet:

1. Upload the file with the container number it belongs to, and a key of your own so a retry is safe:

   curl https://trackberry.com/api/v1/documents \
     -H "Authorization: Bearer tb_your_write_token" \
     -H "Idempotency-Key: 6f1c2a9e-1b7d-4c55-9a43-3f0e8d2b7c10" \
     -F [email protected] \
     -F container_number=MSCU1234566

The response is the document, with parse_status pending and data_available false. Keep its id. 2. Trackberry scans the file for viruses, works out what kind of document it is and reads it, usually within a few minutes. Poll GET /documents/{id} every 30 seconds or so until data_available is true (stop if parse_status becomes failed), or subscribe to the document.processed webhook instead of polling. 3. Read the fields with GET /documents/{id}/data.

Where the document goes depends on what you send with it:

• shipment_id: on that shipment. An id that isn’t one of your shipments is a 400 naming shipment_id.
• container_number: on the live, unarchived shipment carrying that container, as one of its containers or as its reference. If none does, Trackberry makes a new draft shipment with the container number as its reference. If two shipments carry it, the call is a 400 with code ambiguous_container; send shipment_id instead.
• Neither: on a new draft shipment.

A shipment made this way is not tracked. It holds the documents and their checks, and Trackberry doesn’t follow a vessel or container for it. It counts toward your bill like any other shipment once its first document has been read. If your organization’s billing doesn’t allow a new shipment, the upload is refused with a 403 and code billing_blocked, and nothing is saved; see Billing.

The extracted figures reach your ERP export only after the same checks and review as any other document’s; see Ready for ERP.

Send an Idempotency-Key header with every upload, such as a UUID or your own line id. Repeating a key within 24 hours with the same file and the same shipment_id or container_number returns the first document with a 200 instead of making a second one with a 201. Using a key again for a different file or target is a 400 with code idempotency_key_reused. Without a key, sending the same file to the same shipment again also returns the first document, but an upload with neither shipment_id nor container_number makes a new draft shipment every time.

Files can be PDFs (digital or scanned), JPEG, PNG or TIFF images, Excel workbooks (.xlsx, .xls) or CSV files, up to 50 MB. Trackberry reads the type from the file’s contents, not its name. Each token can upload 120 files an hour. Every upload is recorded in the shipment’s activity log, marked as made through the API, with the member who owns the token.

BI feeds #

Three endpoints return a whole table in one response, ready for Power BI, Excel or any tool that reads CSV or JSON from a URL. They use the same token as the rest of the API.

The metrics in the KPI feed are listed under What the KPI feed measures.

Add .csv or .json to the path (/feed/shipments.csv); with no extension you get JSON. Column names are snake_case and stable, new columns are only ever added at the end, and dates are ISO 8601. Narrow a feed with from and to (dates or date-times); the shipments feed also takes status and archived. The response is streamed, so a large organization is not a problem, and a feed is not paged. In JSON it is { "object": "feed", "name": "shipments", "columns": [...], "data": [...] } with one flat object per row. A CSV cell that starts with =, +, - or @ gets a leading apostrophe so a spreadsheet will not run it as a formula.

Prefer JSON for Power BI. Numbers arrive typed and no regional setting can misread a decimal point. CSV works too: it is UTF-8 with a byte order mark, line breaks inside a cell become spaces, and in Power BI you should pick Using locale → English (United States) when you change a column’s type.

The KPI periods are the month a shipment was created in, not the month it sailed or arrived, and the figures include archived and orphaned shipments, exactly as the Statistics page does.

Feeds are heavy, so an organization can run one at a time (a second request while one is running is a 429 with code feed_in_progress and a Retry-After header) and a token may request at most 6 feeds a minute. A feed that fails while it streams ends the connection abnormally, so your tool sees an error rather than a short table. Columns are only ever added at the end; Power BI ignores a new column until you edit the query.

Create one token per report, and name it after the report. The token is stored inside the .pbix file, so don’t share the file; if it leaks, revoke the token under Organization settings → API & webhooks. Always send the token in the Authorization header, never in the URL, where it would end up in logs and browser history. That page has these URLs ready to copy.

Power BI template #

The quickest start is our ready-made report. Download the Power BI template (trackberry.pbit), open it in Power BI Desktop, and paste a read-only token when it asks for TrackberryToken. It loads all three feeds into four pages:

• Overview: shipments in transit and arriving in the next 7 days, containers close to or past their last free day, shipments created and on-time arrivals by month, and every shipment in transit sorted by ETA.
• Carriers and lanes: on-time arrivals by carrier and by lane, and every lane with its shipment count, average transit and average delay.
• Free time: containers on the demurrage clock with their days left, and median days in each destination port.
• Incidents and CO2: incidents by month and type, incidents per 100 shipments by carrier and by forwarder, and CO₂ by month.

The template holds no data and no token, so it is safe to pass around. Once you have pasted a token, save your report as a .pbix and keep it as private as the token itself. Power BI loads the three tables at the same time while Trackberry runs one feed per organization at a time, so the template waits and asks again when a feed is busy, which can add a few seconds to a refresh. Days left on the Free time page are calendar days, so they can differ by a day from Trackberry’s count when your free time is counted in working days. To change the token later, use Transform data → Edit parameters.

To build your own report instead, connect to the feeds directly.

Power BI Desktop #

1. Get data → Web → Advanced. Start with a .json URL.
2. In URL parts paste https://trackberry.com/api/v1/feed/shipments.json.
3. Under HTTP request header parameters add the header Authorization with the value Bearer tb_your_token.
4. Click OK. If Power BI asks how to connect, choose Anonymous: the header already carries the token.
5. Check the preview, then Load (or Transform Data; for JSON, expand the data list to a table and then its records).

For a scheduled refresh in the Power BI service, publish the report and open the semantic model’s settings. Set the data source credentials to Anonymous, its privacy level to Organizational, and tick Skip test connection. The header is stored with the query. Create a token that never expires, or put a reminder in your calendar before it does.

Excel #

1. Data → Get Data → From Other Sources → From Web, then choose Advanced.
2. Paste the feed URL and add the Authorization header with the value Bearer tb_your_token.
3. Choose Anonymous if asked, then Load. Data → Refresh All pulls fresh rows.

What the KPI feed measures #

The KPI feed carries the figures of the Statistics page, computed by the same code, so a number in Power BI is the number on screen. Each row has the columns metric, period_start, period_end, dimension, dimension_value, value and unit. A monthly metric has one row per calendar month. A window metric has one row per carrier, lane, country or port, covering the whole window from the first day of the first month to today. The feed covers the last 12 months by default, and from reaches back up to 24.

For the long tail behind a top 10, build it from the shipments feed, which has every shipment. How incidents are detected is in the Statistics guide.

Errors #

Errors have one shape, whatever went wrong:

{ "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "limit must be an integer between 1 and 100", "param": "limit" } }

Limits #

Each token can make 600 requests every 5 minutes, which is plenty for a sync that runs every few minutes. Requests from one IP address are capped at 1,200 every 5 minutes across all tokens, and requests with no token at all (including a fetch of openapi.json) are capped at 30 every 5 minutes per IP address. On top of these, each token can upload 120 documents an hour. When you hit a limit you get a 429 with a Retry-After header.

Endpoint reference #

Every request takes the optional Trackberry-Version header described under Versions. Every response body below shows all of its fields: a field with no value is null, never missing. Times are UTC. Successful responses carry a Trackberry-Version header, and a 404 or 400 caused by a parameter does too. Errors have the shape described under Errors.

Get the organization and token behind the request #

GET /organization (operation get_organization)

Use this first to check that a token works and to learn which organization it reads, which API version that organization is pinned to, and when the token expires. Read-only and cheap.

No parameters.

Example response, 200:

{
  "object": "organization",
  "id": "org_42",
  "name": "Fresh Imports Ltd",
  "slug": "fresh-imports",
  "api_version": "2026-10-01",
  "token": {
    "id": "tok_7",
    "name": "ERP sync",
    "scopes": [
      "read"
    ],
    "expires_at": "2027-09-29T10:00:00Z",
    "user_email": "[email protected]"
  }
}

Errors: 400, 401, 429.

List and search shipments #

GET /shipments (operation list_shipments)

Use this to find shipments, to sync all shipments, or to answer questions like “what is arriving next week” (eta_after and eta_before) or “which shipments are in transit” (status). Newest first, keyset paged. Shipments still waiting for approval are never listed. Archived shipments are left out unless archived says otherwise. Each item is the full shipment object, the same as get_shipment. All parameters are optional and combine with AND.

Example response, 200:

{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "object": "shipment",
      "id": "shp_812",
      "reference": "SHIP-20260915-K7QX",
      "erp_reference": "PO-88231",
      "transport_reference": "MEDURU156671",
      "transport_reference_type": "bill_of_lading",
      "transport_type": "ocean",
      "load_type": null,
      "house_bl": null,
      "forwarder_reference": null,
      "forwarder_eta": null,
      "cargo_type": "reefer",
      "temperature_celsius": 2.0,
      "status": "in_transit",
      "archived": false,
      "archived_at": null,
      "validated_at": "2026-09-16T08:30:00Z",
      "approved_at": "2026-09-15T12:05:00Z",
      "origin": {
        "location": "Callao",
        "country": "Peru",
        "timezone": "-05:00",
        "code": "PECLL"
      },
      "destination": {
        "location": "Rotterdam",
        "country": "Netherlands",
        "timezone": "+02:00",
        "code": "NLRTM"
      },
      "etd": "2026-09-10T18:00:00Z",
      "eta": "2026-10-05T06:00:00Z",
      "effective_eta": "2026-10-05T06:00:00Z",
      "original_eta": "2026-10-02T06:00:00Z",
      "predicted_eta": null,
      "availability_date": "2026-10-07",
      "carrier": {
        "name": "MSC",
        "scac": "MSCU"
      },
      "tracking": {
        "state": "available",
        "status": "in_transit",
        "unavailable_reason": null,
        "halted_reason": null,
        "last_tracked_at": "2026-09-29T09:41:00Z",
        "carrier_updated_at": "2026-09-29T06:12:00Z"
      },
      "parties": {
        "consignor": "Agro Andes SAC",
        "consignee": "Fresh Imports Ltd",
        "notify_party": null
      },
      "supplier": {
        "id": "cmp_41",
        "name": "Agro Andes SAC"
      },
      "forwarder": null,
      "customer": {
        "id": "cmp_57",
        "name": "Fresh Imports Ltd"
      },
      "produce": [
        "Grapes"
      ],
      "organic": false,
      "cargo": {
        "pallets": 20,
        "boxes": 2400,
        "net_weight_kg": 9600.0,
        "gross_weight_kg": 10320.0
      },
      "containers": [
        {
          "object": "container",
          "id": "ctr_1301",
          "number": "MSCU1234567",
          "seal_numbers": ["ES123456"],
          "vessel": "MSC AURORA",
          "voyage": "2609W",
          "port_of_loading": "Callao",
          "port_of_discharge": "Rotterdam",
          "etd": "2026-09-10T18:00:00Z",
          "eta": "2026-10-05T06:00:00Z",
          "cargo_type": "reefer",
          "temperature_celsius": 2.0
        }
      ],
      "labels": [
        {
          "object": "label",
          "id": "lbl_3",
          "name": "Priority",
          "color": "red",
          "color_hex": "#ef4444"
        }
      ],
      "checks": {
        "total": 6,
        "passed": 4,
        "failed": 1,
        "warnings": 1,
        "skipped": 0,
        "pending": 0,
        "acknowledged": 0
      },
      "notes": null,
      "public_tracking_url": "https://trackberry.com/track/acme-produce/shipments/Qw3rTy9uIoPaSdFgHjKlZxCvBnM4s7Ab",
      "created_at": "2026-09-15T12:00:00Z",
      "updated_at": "2026-09-29T09:41:00Z"
    }
  ]
}

Errors: 400, 401, 429.

Get one shipment #

GET /shipments/{id} (operation get_shipment)

Use this when you already have a shipment id and want its current state: status, ETAs, route, carrier, tracking health, parties, produce, cargo totals, containers, labels and check counts. Archived shipments are still found. For tracking events and ETA history use get_shipment_timeline; for demurrage and detention use get_shipment_free_time.

Example response, 200:

{
  "object": "shipment",
  "id": "shp_812",
  "reference": "SHIP-20260915-K7QX",
  "erp_reference": "PO-88231",
  "transport_reference": "MEDURU156671",
  "transport_reference_type": "bill_of_lading",
  "transport_type": "ocean",
  "load_type": null,
  "house_bl": null,
  "forwarder_reference": null,
  "forwarder_eta": null,
  "cargo_type": "reefer",
  "temperature_celsius": 2.0,
  "status": "in_transit",
  "archived": false,
  "archived_at": null,
  "validated_at": "2026-09-16T08:30:00Z",
  "approved_at": "2026-09-15T12:05:00Z",
  "origin": {
    "location": "Callao",
    "country": "Peru",
    "timezone": "-05:00",
    "code": "PECLL"
  },
  "destination": {
    "location": "Rotterdam",
    "country": "Netherlands",
    "timezone": "+02:00",
    "code": "NLRTM"
  },
  "etd": "2026-09-10T18:00:00Z",
  "eta": "2026-10-05T06:00:00Z",
  "effective_eta": "2026-10-05T06:00:00Z",
  "original_eta": "2026-10-02T06:00:00Z",
  "predicted_eta": null,
  "availability_date": "2026-10-07",
  "carrier": {
    "name": "MSC",
    "scac": "MSCU"
  },
  "tracking": {
    "state": "available",
    "status": "in_transit",
    "unavailable_reason": null,
    "halted_reason": null,
    "last_tracked_at": "2026-09-29T09:41:00Z",
    "carrier_updated_at": "2026-09-29T06:12:00Z"
  },
  "parties": {
    "consignor": "Agro Andes SAC",
    "consignee": "Fresh Imports Ltd",
    "notify_party": null
  },
  "supplier": {
    "id": "cmp_41",
    "name": "Agro Andes SAC"
  },
  "forwarder": null,
  "customer": {
    "id": "cmp_57",
    "name": "Fresh Imports Ltd"
  },
  "produce": [
    "Grapes"
  ],
  "organic": false,
  "cargo": {
    "pallets": 20,
    "boxes": 2400,
    "net_weight_kg": 9600.0,
    "gross_weight_kg": 10320.0
  },
  "containers": [
    {
      "object": "container",
      "id": "ctr_1301",
      "number": "MSCU1234567",
      "seal_numbers": ["ES123456"],
      "vessel": "MSC AURORA",
      "voyage": "2609W",
      "port_of_loading": "Callao",
      "port_of_discharge": "Rotterdam",
      "etd": "2026-09-10T18:00:00Z",
      "eta": "2026-10-05T06:00:00Z",
      "cargo_type": "reefer",
      "temperature_celsius": 2.0
    }
  ],
  "labels": [
    {
      "object": "label",
      "id": "lbl_3",
      "name": "Priority",
      "color": "red",
      "color_hex": "#ef4444"
    }
  ],
  "checks": {
    "total": 6,
    "passed": 4,
    "failed": 1,
    "warnings": 1,
    "skipped": 0,
    "pending": 0,
    "acknowledged": 0
  },
  "notes": null,
  "public_tracking_url": "https://trackberry.com/track/acme-produce/shipments/Qw3rTy9uIoPaSdFgHjKlZxCvBnM4s7Ab",
  "created_at": "2026-09-15T12:00:00Z",
  "updated_at": "2026-09-29T09:41:00Z"
}

Errors: 400, 401, 404, 429.

Get the route, tracking events and ETA revisions of a shipment #

GET /shipments/{shipment_id}/timeline (operation get_shipment_timeline)

Use this to answer “where is it and what happened” and “how has the ETA moved”. Returns the route legs in order, every tracking event (both events that happened and estimated ones, oldest first) and every recorded revision of the estimated arrival, oldest first. Not paged.

Example response, 200:

{
  "object": "timeline",
  "shipment_id": "shp_812",
  "legs": [
    {
      "object": "shipment_leg",
      "id": "leg_5501",
      "position": 0,
      "transport_type": "ocean",
      "carrier": "MSC",
      "transport_reference": "MEDURU156671",
      "origin": {
        "location": "Callao",
        "country": "Peru",
        "timezone": "-05:00",
        "code": "PECLL"
      },
      "destination": {
        "location": "Rotterdam",
        "country": "Netherlands",
        "timezone": "+02:00",
        "code": "NLRTM"
      },
      "etd": "2026-09-10T18:00:00Z",
      "eta": "2026-10-05T06:00:00Z"
    }
  ],
  "events": [
    {
      "object": "tracking_event",
      "id": "evt_90211",
      "milestone": "loaded",
      "actual": true,
      "occurred_at": "2026-09-10T14:20:00Z",
      "occurred_at_local": "2026-09-10T09:20:00-05:00",
      "container_number": "MSCU1234567",
      "leg_index": 1,
      "location": {
        "name": "Callao",
        "code": "PECLL",
        "country_code": "PE"
      },
      "vessel": {
        "name": "MSC AURORA",
        "imo": "9876543",
        "voyage": "2609W"
      },
      "flight_number": null,
      "position": {
        "latitude": -12.05,
        "longitude": -77.15
      }
    },
    {
      "object": "tracking_event",
      "id": "evt_90233",
      "milestone": "arrived",
      "actual": false,
      "occurred_at": "2026-10-05T06:00:00Z",
      "occurred_at_local": "2026-10-05T08:00:00+02:00",
      "container_number": "MSCU1234567",
      "leg_index": 1,
      "location": {
        "name": "Rotterdam",
        "code": "NLRTM",
        "country_code": "NL"
      },
      "vessel": {
        "name": "MSC AURORA",
        "imo": "9876543",
        "voyage": "2609W"
      },
      "flight_number": null,
      "position": {
        "latitude": null,
        "longitude": null
      }
    }
  ],
  "eta_revisions": [
    {
      "object": "eta_revision",
      "id": "eta_4401",
      "observed_at": "2026-09-11T05:00:00Z",
      "previous_eta": null,
      "new_eta": "2026-10-02T06:00:00Z",
      "slip_seconds": null,
      "first_estimate": true,
      "backfilled": false
    },
    {
      "object": "eta_revision",
      "id": "eta_4470",
      "observed_at": "2026-09-25T05:00:00Z",
      "previous_eta": "2026-10-02T06:00:00Z",
      "new_eta": "2026-10-05T06:00:00Z",
      "slip_seconds": 259200.0,
      "first_estimate": false,
      "backfilled": false
    }
  ]
}

Errors: 400, 401, 404, 429.

Get the map data of a shipment #

GET /shipments/{shipment_id}/map (operation get_shipment_map)

Use this to draw a shipment’s voyage on a map: the sea or air route split into the part already travelled and the part remaining, the carrier’s ports, the vessel’s upcoming calls, the recorded position trail and the vessel marker. It is the data behind the map on the shipment’s page in Trackberry. Long lines are thinned and coordinates rounded to four decimals. When the carrier has published nothing to draw, map has the same shape and draws the shipment’s legs between the places its own located tracking events put their ends; it is null only when nothing can be placed. Not paged.

Example response, 200:

{
  "object": "shipment_map",
  "shipment_id": "shp_812",
  "map": {
    "routeSegments": [
      {
        "path": [
          {
            "lat": -12.05,
            "lng": -77.15
          },
          {
            "lat": 8.9,
            "lng": -79.5
          },
          {
            "lat": 51.95,
            "lng": 4.14
          }
        ],
        "routeType": "SEA"
      }
    ],
    "locations": [
      {
        "name": "Callao",
        "type": "pol",
        "locode": "PECLL",
        "country": "Peru",
        "coordinates": {
          "lat": -12.05,
          "lng": -77.15
        }
      },
      {
        "name": "Rotterdam",
        "type": "pod",
        "locode": "NLRTM",
        "country": "Netherlands",
        "coordinates": {
          "lat": 51.95,
          "lng": 4.14
        }
      }
    ],
    "vesselCalls": [],
    "routeSplit": {
      "segmentIndex": 0,
      "pointIndex": 1,
      "position": {
        "lat": 8.9,
        "lng": -79.5
      }
    },
    "positionTrail": [
      {
        "lat": 8.2,
        "lng": -79.3,
        "label": "about 3 hours ago"
      }
    ],
    "vesselMarker": {
      "lat": 8.2,
      "lng": -79.3,
      "source": "fix",
      "seenAt": "about 3 hours ago",
      "heading": 12
    },
    "vesselName": "MSC AURORA",
    "airRoute": false
  }
}

Errors: 400, 401, 404, 429.

Get the demurrage and detention clocks of a shipment #

GET /shipments/{shipment_id}/free_time (operation get_shipment_free_time)

Use this to answer “how many free days are left on this shipment” or “what will demurrage cost us”. Returns one demurrage clock and one detention clock per container, plus the clock that matters most right now (active_clock). Clocks only exist for ocean shipments, for each container that has loading, discharge, gate-out or empty-return events, and stay not_started until the container is discharged. For any other shipment the clock lists are empty and active_clock is null. Free days come from the shipment itself, the latest arrival notice, or the organization’s carrier terms, in that order (see free_days_source).

Example response, 200:

{
  "object": "free_time_summary",
  "shipment_id": "shp_790",
  "shipment_reference": "SHIP-20260901-B2MD",
  "transport_reference": "MAEU123456789",
  "at_risk": true,
  "terms_unknown": false,
  "demurrage": [
    {
      "object": "free_time_clock",
      "kind": "demurrage",
      "container_number": "TGHU7654321",
      "state": "running",
      "free_days": 5,
      "free_days_source": "carrier",
      "free_days_basis": "calendar",
      "started_on": "2026-09-25",
      "ended_on": null,
      "last_free_day": "2026-09-29",
      "days_left": 1,
      "elapsed_days": null,
      "used_days": null,
      "overdue_days": null,
      "carrier": "Maersk"
    }
  ],
  "detention": [
    {
      "object": "free_time_clock",
      "kind": "detention",
      "container_number": "TGHU7654321",
      "state": "not_started",
      "free_days": 10,
      "free_days_source": "carrier",
      "free_days_basis": "calendar",
      "started_on": null,
      "ended_on": null,
      "last_free_day": null,
      "days_left": null,
      "elapsed_days": null,
      "used_days": null,
      "overdue_days": null,
      "carrier": "Maersk"
    }
  ],
  "active_clock": {
    "object": "free_time_clock",
    "kind": "demurrage",
    "container_number": "TGHU7654321",
    "state": "running",
    "free_days": 5,
    "free_days_source": "carrier",
    "free_days_basis": "calendar",
    "started_on": "2026-09-25",
    "ended_on": null,
    "last_free_day": "2026-09-29",
    "days_left": 1,
    "elapsed_days": null,
    "used_days": null,
    "overdue_days": null,
    "carrier": "Maersk"
  },
  "collect_by": "2026-09-29",
  "collect_by_calendars": [
    "DE-BY",
    "DE-HH"
  ]
}

Errors: 400, 401, 404, 429.

List the documents of a shipment #

GET /shipments/{shipment_id}/documents (operation list_shipment_documents)

Use this to see which paperwork Trackberry holds for a shipment (bill of lading, packing list, invoice, certificates) and whether each was read successfully. Only current documents are listed: replaced versions, reference-only attachments and internal page-split records are left out. Oldest first, not paged. Download a file with download_document_file when its downloadable is true.

Example response, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "document",
      "id": "doc_301",
      "shipment_id": "shp_812",
      "type": "packing_list",
      "filename": "PL_MEDURU156671.xlsx",
      "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "byte_size": 48211,
      "source": "email_upload",
      "parse_status": "parsed",
      "downloadable": true,
      "page_range": null,
      "data_available": true,
      "created_at": "2026-09-15T12:01:00Z",
      "updated_at": "2026-09-15T12:03:00Z"
    }
  ]
}

Errors: 400, 401, 404, 429.

List the packing lists of a shipment with pallets and lines #

GET /shipments/{shipment_id}/packing_lists (operation list_shipment_packing_lists)

Use this to read what is physically in the shipment: for each current packing list, its declared totals, its pallets, and each pallet’s produce lines (produce, variety, calibre, box counts and weights). Only current packing lists (not replaced by a newer document) are listed, oldest first, not paged. Pallets that belong to no packing list are not reachable here (they still count in cargo.pallets of the shipment).

Example response, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "packing_list",
      "id": "pkl_55",
      "shipment_id": "shp_812",
      "document_id": "doc_301",
      "container_id": "ctr_1301",
      "reference": "PL-2026-0915",
      "declared_box_count": 240,
      "declared_net_weight_kg": 960.0,
      "totals": {
        "pallets": 2,
        "boxes": 240,
        "net_weight_kg": 960.0
      },
      "pallets": [
        {
          "object": "pallet",
          "id": "plt_9001",
          "pallet_number": "PAL0001",
          "container_id": "ctr_1301",
          "lines": [
            {
              "object": "packing_line",
              "id": "pln_70001",
              "line_index": 1,
              "produce_name": "Grapes",
              "produce_type": "Organic",
              "variety": "Sweet Globe",
              "calibre": "L",
              "quality_category": "Class I",
              "pack_format": "4.0 kg carton",
              "label": "Andes Gold",
              "ggn": "4049929123456",
              "comment": null,
              "box_count": 120,
              "preallocated_boxes": 40,
              "box_weight_kg": 4.0,
              "net_weight_kg": 480.0,
              "gross_weight_kg": 522.0
            }
          ]
        },
        {
          "object": "pallet",
          "id": "plt_9002",
          "pallet_number": "PAL0002",
          "container_id": "ctr_1301",
          "lines": [
            {
              "object": "packing_line",
              "id": "pln_70002",
              "line_index": 1,
              "produce_name": "Grapes",
              "produce_type": "Organic",
              "variety": "Sweet Globe",
              "calibre": "L",
              "quality_category": "Class I",
              "pack_format": "4.0 kg carton",
              "label": "Andes Gold",
              "ggn": "4049929123456",
              "comment": null,
              "box_count": 120,
              "preallocated_boxes": 0,
              "box_weight_kg": 4.0,
              "net_weight_kg": 480.0,
              "gross_weight_kg": 522.0
            }
          ]
        }
      ]
    }
  ]
}

Errors: 400, 401, 404, 429.

List the customer links of a shipment #

GET /shipments/{shipment_id}/share_links (operation list_shipment_share_links)

Use this to see which customers already have a tracking link for a shipment, and which links were switched off. Active and revoked links are listed, newest first, with keyset paging. Needs the read scope.

Example response, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "share_link",
      "id": "shl_41",
      "shipment_id": "shp_812",
      "customer_reference": "PO-4471",
      "label": "Fresh Direct",
      "url": "https://trackberry.com/acme/s/Zk3p9QmT7vXw2LrB5nHc8DfGaJ4yEsUe",
      "active": true,
      "revoked_at": null,
      "created_at": "2026-10-02T09:15:00Z"
    }
  ]
}

Errors: 400, 401, 403, 404, 429.

Create a tracking link for one of your customers #

POST /shipments/{shipment_id}/share_links (operation create_shipment_share_link)

Use this when an order is confirmed or a delivery note is printed, to get a tracking link carrying the customer’s own order number. It is idempotent by customer_reference: if the shipment already has an active link for the same reference (compared after trimming and collapsing spaces, case-sensitive) that link is returned with a 200 and left unchanged (the label is not updated, even if the retry sends a different or too long one), so a retry never makes a second one. A new link is a 201. Needs the write scope. Refused with not_shareable (400) unless the organization has public tracking pages switched on and the shipment is live and shared publicly. Recorded in the audit log as made through the API.

Send the body as JSON with Content-Type: application/json:

Example request body:

{
  "customer_reference": "PO-4471",
  "label": "Fresh Direct"
}

Example response, 201 (a 200 with the same body when the link already existed):

{
  "object": "share_link",
  "id": "shl_41",
  "shipment_id": "shp_812",
  "customer_reference": "PO-4471",
  "label": "Fresh Direct",
  "url": "https://trackberry.com/acme/s/Zk3p9QmT7vXw2LrB5nHc8DfGaJ4yEsUe",
  "active": true,
  "revoked_at": null,
  "created_at": "2026-10-02T09:15:00Z"
}

Errors: 400, 401, 403, 404, 429.

Get one customer link #

GET /share_links/{id} (operation get_share_link)

Use this to check whether a customer link is still active and to read its URL again. A revoked link stays readable, with active false and url null. Needs the read scope.

The response is the same object as above.

Errors: 400, 401, 403, 404, 429.

Revoke a customer link #

DELETE /share_links/{id} (operation revoke_share_link)

Use this when an order is cancelled or the customer should stop seeing the shipment. The link stops opening at once and the customer’s tracking emails through it stop. It is a soft delete: the link is returned with active false and url null. Revoking a link that is already revoked returns it again and changes nothing. Needs the write scope. An admin or owner may revoke any link; a member only the ones their own token made (403 revoke_not_allowed otherwise). Recorded in the audit log as made through the API.

Example response, 200:

{
  "object": "share_link",
  "id": "shl_41",
  "shipment_id": "shp_812",
  "customer_reference": "PO-4471",
  "label": "Fresh Direct",
  "url": null,
  "active": false,
  "revoked_at": "2026-10-09T16:40:00Z",
  "created_at": "2026-10-02T09:15:00Z"
}

Errors: 400, 401, 403, 404, 429.

List the pre-allocations of a shipment #

GET /shipments/{shipment_id}/preallocations (operation list_shipment_preallocations)

Use this to see which customers have boxes of a shipment set aside, on which packing line and pallet, and at what tentative price. Every pre-allocation on the shipment is listed, oldest first, with the line and pallet it belongs to. Rows on lines merged into another, or on a superseded packing list, are left out. Not paged: bounded by one shipment. Needs the read scope.

Example response, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "preallocation",
      "id": "pre_96",
      "packing_line_id": "pln_5521",
      "pallet_id": "plt_3310",
      "allocatee": "Fresh Direct",
      "boxes": 40,
      "unit_price": 12.5,
      "currency": "EUR",
      "value": 500,
      "created_at": "2026-10-05T08:30:00Z",
      "updated_at": "2026-10-05T08:30:00Z"
    }
  ]
}

Errors: 400, 401, 403, 404, 429.

Pre-allocate boxes of a packing line to a customer #

POST /packing_lines/{packing_line_id}/preallocations (operation create_packing_line_preallocation)

Use this to set boxes of one packing line aside for a customer, with an optional tentative price. The same rules as the web app apply: the boxes allocated on a line cannot add up to more than the line’s box_count (a 400 naming boxes says how many are left). A price is unit_price per box, or, with price_basis total, the total for these boxes, which is stored as a price per box. currency is a three-letter code, required with a price (a price without one is a 400 naming currency) and ignored without one. A line merged into another, or on a superseded packing list, cannot be pre-allocated (404). Each call adds one pre-allocation; there is no idempotency, so do not retry a request that may have succeeded without listing first. Needs the write scope and a token owner who is not a read-only member (403 read_only_member otherwise). Recorded in the audit log as made through the API.

Send the body as JSON with Content-Type: application/json:

Example request body:

{
  "allocatee": "Fresh Direct",
  "boxes": 40,
  "unit_price": 12.5,
  "currency": "EUR"
}

Example response, 201:

{
  "object": "preallocation",
  "id": "pre_96",
  "packing_line_id": "pln_5521",
  "pallet_id": "plt_3310",
  "allocatee": "Fresh Direct",
  "boxes": 40,
  "unit_price": 12.5,
  "currency": "EUR",
  "value": 500,
  "created_at": "2026-10-05T08:30:00Z",
  "updated_at": "2026-10-05T08:30:00Z"
}

Errors: 400, 401, 403, 404, 429.

Change a pre-allocation #

PATCH /preallocations/{id} (operation update_preallocation)

Use this to change the customer, the boxes or the price of a pre-allocation. Only the fields you send change; send unit_price as null to remove the price (its currency goes with it). Send at least one field. price_basis is only accepted together with unit_price (400 naming price_basis otherwise). The boxes are checked against the line again, as when creating. Needs the write scope and a token owner who is not a read-only member. Recorded in the audit log as made through the API.

Send the body as JSON with Content-Type: application/json:

Example request body:

{
  "boxes": 60,
  "unit_price": 12,
  "currency": "EUR"
}

Example response, 200:

{
  "object": "preallocation",
  "id": "pre_96",
  "packing_line_id": "pln_5521",
  "pallet_id": "plt_3310",
  "allocatee": "Fresh Direct",
  "boxes": 60,
  "unit_price": 12,
  "currency": "EUR",
  "value": 720,
  "created_at": "2026-10-05T08:30:00Z",
  "updated_at": "2026-10-06T10:02:00Z"
}

Errors: 400, 401, 403, 404, 429.

Remove a pre-allocation #

DELETE /preallocations/{id} (operation delete_preallocation)

Use this to release the boxes a pre-allocation set aside. It is a hard delete: the pre-allocation is returned one last time, as it was, and is gone afterwards (a second delete is a 404). Needs the write scope and a token owner who is not a read-only member. Recorded in the audit log as made through the API.

The response, 200, is the same object as when creating.

Errors: 400, 401, 403, 404, 429.

Add a paragraph to a shipment’s notes #

POST /shipments/{shipment_id}/notes (operation append_shipment_note)

Use this to leave a note on a shipment without touching what is already there: the text is trimmed and added after the existing notes, separated by a blank line (or becomes the notes when there are none), so a colleague’s notes are never wiped. text cannot be blank (400) and the notes together are limited to 20,000 characters. Notes are Markdown. Needs the write scope and a token owner who is not a read-only member. Recorded in the audit log as shipment.notes_changed, made through the API. Not idempotent: sending the same text twice adds it twice.

Send the body as JSON with Content-Type: application/json:

Example request body:

{
  "text": "Customs cleared, delivery booked for Thursday."
}

Example response, 200:

{
  "object": "shipment_notes",
  "shipment_id": "shp_812",
  "notes": "Call the forwarder about the seal.\n\nCustoms cleared, delivery booked for Thursday."
}

Errors: 400, 401, 403, 404, 429.

Replace a shipment’s notes #

PUT /shipments/{shipment_id}/notes (operation replace_shipment_notes)

Use this when you hold the whole text and mean to overwrite it, for example after reading the notes from get_shipment and editing them. It replaces everything: whatever a colleague added since is lost, so prefer append_shipment_note for adding. notes must be present and a string; an empty string clears the notes (they read back as null). Limited to 20,000 characters. Needs the write scope and a token owner who is not a read-only member. Recorded in the audit log as shipment.notes_changed, made through the API.

Send the body as JSON with Content-Type: application/json:

Example request body:

{
  "notes": "Call the forwarder about the seal.\n\nCustoms cleared, delivery booked for Thursday."
}

The response, 200, is the same object as above.

Errors: 400, 401, 403, 404, 429.

Put a label on a shipment #

POST /shipments/{shipment_id}/labels (operation add_shipment_label)

Use this to tag a shipment with one of the organization’s labels, for example “Urgent”. Pass the label as label: its id (lbl_ prefix) or the words a person would use. The id wins; then the exact name (case and spaces ignored); then the name with emoji, punctuation and case set aside, so “urgent” finds “🔥 Urgent”; then a name that holds every word given. The first step that finds exactly one label is used. Several at the same step is a 400 ambiguous_label naming them with their ids: pick one by id. Nothing found is a 404 whose message lists the organization’s label names. Labels are never created here. list_labels (with q) is only needed to show what exists. Idempotent: a shipment that already has the label answers the same and is not audited a second time. Needs the write scope and a token owner who is not a read-only member. Recorded in the audit log as shipment.label_added, made through the API.

Send the body as JSON with Content-Type: application/json:

Example request body:

{
  "label": "Urgent"
}

Example response, 200:

{
  "object": "shipment_labels",
  "shipment_id": "shp_812",
  "labels": [
    {
      "object": "label",
      "id": "lbl_12",
      "name": "Urgent",
      "color": "red",
      "color_hex": "#ef4444"
    }
  ]
}

Errors: 400, 401, 403, 404, 429.

Take a label off a shipment #

DELETE /shipments/{shipment_id}/labels/{label} (operation remove_shipment_label)

Use this to remove a label from a shipment, naming it by its id or by its name (URL-encoded), matched as in add_shipment_label (400 ambiguous_label when several fit). Idempotent: a shipment that does not carry the label answers the same and nothing is audited. The label stays in the organization’s catalogue. Needs the write scope and a token owner who is not a read-only member. Recorded in the audit log as shipment.label_removed, made through the API.

Example response, 200:

{
  "object": "shipment_labels",
  "shipment_id": "shp_812",
  "labels": []
}

Errors: 400, 401, 403, 404, 429.

Run a shipment’s checks again #

POST /shipments/{shipment_id}/check_runs (operation run_shipment_checks)

Use this after documents changed, or to refresh list_checks on one shipment. It queues the same quality checks the Run checks button does and answers at once; the results appear in list_checks when the job has run, usually within a minute. Changes no data itself and is safe to repeat. Needs the write scope and a token owner who is not a read-only member.

The body is empty: send {}, or nothing.

Example response, 200:

{
  "object": "check_run",
  "shipment_id": "shp_812",
  "status": "queued"
}

Errors: 400, 401, 403, 404, 429.

Ask for fresh tracking on a shipment #

POST /shipments/{shipment_id}/tracking_refreshes (operation refresh_shipment_tracking)

Use this when the user wants the latest carrier information now, as the Check now button does. It queues the refresh and answers at once; read the shipment again shortly after. Each refresh costs a request to the tracking service, so a shipment is refreshed at most once every 5 minutes, whoever asks, and one that was tracked in the last 5 minutes by the regular sweep counts too: inside that window the answer is a 429 refresh_too_soon with Retry-After. A shipment with no transport reference, or that has arrived, is a 400 not_trackable. Needs the write scope and a token owner who is not a read-only member.

The body is empty: send {}, or nothing.

Example response, 200:

{
  "object": "tracking_refresh",
  "shipment_id": "shp_812",
  "status": "queued"
}

Errors: 400, 401, 403, 404, 429.

Archive a shipment #

POST /shipments/{shipment_id}/archive (operation archive_shipment)

Use this to take a finished shipment off the active lists. It stays readable (archived shipments are still found by id and listed with archived) and unarchive_shipment brings it back. Idempotent: an archived shipment answers the same and is not audited again. Needs the write scope and a token owner who is not a read-only member. Recorded in the audit log as shipment.archived, made through the API.

The body is empty: send {}, or nothing.

The response, 200, is the shipment, as GET /shipments/{id} gives it.

Errors: 400, 401, 403, 404, 429.

Bring an archived shipment back #

DELETE /shipments/{shipment_id}/archive (operation unarchive_shipment)

Use this to put an archived shipment back on the active lists. Idempotent: a shipment that is not archived answers the same and is not audited. Needs the write scope and a token owner who is not a read-only member. Recorded in the audit log as shipment.unarchived, made through the API.

The response, 200, is the shipment, as GET /shipments/{id} gives it.

Errors: 400, 401, 403, 404, 429.

Mark a shipment as received at the warehouse #

POST /shipments/{shipment_id}/warehouse_arrival (operation mark_shipment_in_warehouse)

Use this when the user says the cargo has been received. The shipment’s status becomes in_warehouse, as when an admin presses the button on the shipment page, and nothing here moves it back. Admins and owners only: another member’s token is a 403 admin_required. A shipment already in the warehouse answers the same and is not audited again; one still waiting for approval, or in error, is a 400 cannot_mark_in_warehouse. Needs the write scope. Recorded in the audit log as shipment.in_warehouse, made through the API.

The body is empty: send {}, or nothing.

The response, 200, is the shipment, as GET /shipments/{id} gives it.

Errors: 400, 401, 403, 404, 429.

Accept a failing check, with a reason #

POST /checks/{check_id}/acknowledgement (operation acknowledge_check)

Use this when the user has looked at a failed or warning check from list_checks and decided it is acceptable, and tells you why. The check keeps saying what it said; it stops holding the shipment back until it says something else. reason is required, up to 1,000 characters. Admins and owners only: another member’s token is a 403 admin_required. A check that is passed or skipped is a 400 nothing_to_acknowledge. Repeating the same reason changes nothing and is not audited again. Needs the write scope. Recorded in the audit log as shipment.check_acknowledged, made through the API.

Send the body as JSON with Content-Type: application/json:

Example request body:

{
  "reason": "The supplier confirmed the box count by phone."
}

Example response, 200:

{
  "object": "check_acknowledgement",
  "check_id": "chk_5120",
  "shipment_id": "shp_812",
  "acknowledged_at": "2026-10-01T09:30:00Z",
  "reason": "The supplier confirmed the box count by phone."
}

Errors: 400, 401, 403, 404, 429.

Withdraw the acceptance of a check #

DELETE /checks/{check_id}/acknowledgement (operation unacknowledge_check)

Use this when the user asks to undo an acceptance made with acknowledge_check or in Trackberry: the failing check holds the shipment back again. Admins and owners only: another member’s token is a 403 admin_required. A check that is not accepted answers the same and is not audited. Needs the write scope. Recorded in the audit log as shipment.check_unacknowledged, made through the API.

Example response, 200:

{
  "object": "check_acknowledgement",
  "check_id": "chk_5120",
  "shipment_id": "shp_812",
  "acknowledged_at": null,
  "reason": null
}

Errors: 400, 401, 403, 404, 429.

Hide an alert for a few days #

POST /alerts/{alert_id}/snooze (operation snooze_alert)

Use this when the user wants an alert out of the way for now. It disappears from the issues page for days (1, 3 or 7) and comes back on its own, or sooner if it escalates to critical. Snoozing again replaces the earlier snooze. restore_alert undoes it. Needs the write scope and a token owner who is not a read-only member. Recorded in the audit log as alert.snoozed, made through the API.

Send the body as JSON with Content-Type: application/json:

Example request body:

{
  "days": 3
}

Example response, 200:

{
  "object": "monitoring_alert",
  "id": "alr_2210",
  "shipment_id": "shp_812",
  "shipment_reference": "SHIP-20260915-K7QX",
  "key": "eta_drift",
  "group": "schedule",
  "severity": "warning",
  "title": "ETA has slipped",
  "summary": "ETA has moved 3 days later than first quoted (2026-10-02 → 2026-10-05).",
  "since": "2026-10-02T06:00:00Z",
  "first_detected_at": "2026-09-25T03:00:00Z",
  "last_detected_at": "2026-09-29T03:00:00Z",
  "resolved_at": null,
  "dismissed_at": null,
  "snoozed_until": "2026-10-04T09:30:00Z"
}

Errors: 400, 401, 403, 404, 429.

Hide an alert while the problem lasts #

POST /alerts/{alert_id}/dismissal (operation dismiss_alert)

Use this when the user says an alert is not worth acting on. It stays hidden on the issues page for as long as the problem persists, and does not come back as new. It is not deleted: restore_alert brings it back, and it is still listed by list_alerts with dismissed_at. Dismissing a dismissed alert changes nothing. Needs the write scope and a token owner who is not a read-only member. Recorded in the audit log as alert.dismissed, made through the API.

The body is empty: send {}, or nothing.

Example response, 200:

{
  "object": "monitoring_alert",
  "id": "alr_2210",
  "shipment_id": "shp_812",
  "shipment_reference": "SHIP-20260915-K7QX",
  "key": "eta_drift",
  "group": "schedule",
  "severity": "warning",
  "title": "ETA has slipped",
  "summary": "ETA has moved 3 days later than first quoted (2026-10-02 → 2026-10-05).",
  "since": "2026-10-02T06:00:00Z",
  "first_detected_at": "2026-09-25T03:00:00Z",
  "last_detected_at": "2026-09-29T03:00:00Z",
  "resolved_at": null,
  "dismissed_at": "2026-10-01T09:30:00Z",
  "snoozed_until": null
}

Errors: 400, 401, 403, 404, 429.

Bring a snoozed or dismissed alert back #

POST /alerts/{alert_id}/restoration (operation restore_alert)

Use this to undo snooze_alert or dismiss_alert: the alert is back on the issues page. An alert that was neither answers the same. Needs the write scope and a token owner who is not a read-only member. Recorded in the audit log as alert.restored, made through the API.

The body is empty: send {}, or nothing.

Example response, 200:

{
  "object": "monitoring_alert",
  "id": "alr_2210",
  "shipment_id": "shp_812",
  "shipment_reference": "SHIP-20260915-K7QX",
  "key": "eta_drift",
  "group": "schedule",
  "severity": "warning",
  "title": "ETA has slipped",
  "summary": "ETA has moved 3 days later than first quoted (2026-10-02 → 2026-10-05).",
  "since": "2026-10-02T06:00:00Z",
  "first_detected_at": "2026-09-25T03:00:00Z",
  "last_detected_at": "2026-09-29T03:00:00Z",
  "resolved_at": null,
  "dismissed_at": null,
  "snoozed_until": null
}

Errors: 400, 401, 403, 404, 429.

List shipments whose demurrage free time is nearly or already used up #

GET /free_time/at_risk (operation list_free_time_at_risk)

Use this for a daily “what do I need to collect today” view. Returns one free-time summary per shipment that has a demurrage clock running with 2 days or fewer left (or already overdue), most urgent first. Only ocean shipments that are not archived, not yet received into the warehouse, and were discharged in the last 45 days are considered. Not paged. Shipments with unknown free-time terms never appear here; terms_unknown on get_shipment_free_time says when terms are missing.

No parameters.

Example response, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "free_time_summary",
      "shipment_id": "shp_790",
      "shipment_reference": "SHIP-20260901-B2MD",
      "transport_reference": "MAEU123456789",
      "at_risk": true,
      "terms_unknown": false,
      "demurrage": [
        {
          "object": "free_time_clock",
          "kind": "demurrage",
          "container_number": "TGHU7654321",
          "state": "running",
          "free_days": 5,
          "free_days_source": "carrier",
          "free_days_basis": "calendar",
          "started_on": "2026-09-25",
          "ended_on": null,
          "last_free_day": "2026-09-29",
          "days_left": 1,
          "elapsed_days": null,
          "used_days": null,
          "overdue_days": null,
          "carrier": "Maersk"
        }
      ],
      "detention": [
        {
          "object": "free_time_clock",
          "kind": "detention",
          "container_number": "TGHU7654321",
          "state": "not_started",
          "free_days": 10,
          "free_days_source": "carrier",
          "free_days_basis": "calendar",
          "started_on": null,
          "ended_on": null,
          "last_free_day": null,
          "days_left": null,
          "elapsed_days": null,
          "used_days": null,
          "overdue_days": null,
          "carrier": "Maersk"
        }
      ],
      "active_clock": {
        "object": "free_time_clock",
        "kind": "demurrage",
        "container_number": "TGHU7654321",
        "state": "running",
        "free_days": 5,
        "free_days_source": "carrier",
        "free_days_basis": "calendar",
        "started_on": "2026-09-25",
        "ended_on": null,
        "last_free_day": "2026-09-29",
        "days_left": 1,
        "elapsed_days": null,
        "used_days": null,
        "overdue_days": null,
        "carrier": "Maersk"
      },
      "collect_by": "2026-09-29",
      "collect_by_calendars": [
        "DE-BY",
        "DE-HH"
      ]
    }
  ]
}

Errors: 400, 401, 429.

List companies #

GET /companies (operation list_companies)

Use this to find a supplier, forwarder or customer and its id, for “who is our supplier Progum” or to filter list_shipments by supplier, forwarder or customer. Newest first, keyset paged. q matches the name or any other spelling of it (a company is known by every spelling seen on documents). role limits the list to one role and, like the Companies page, leaves out the organization’s own companies (own is true for those); without it every company is listed. A company that was merged into another no longer exists: its spellings are aliases of the company it was merged into.

Example response, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "company",
      "id": "cmp_41",
      "name": "Agro Andes SAC",
      "roles": [
        "supplier"
      ],
      "own": false,
      "country": "PE",
      "erp_code": "S-1042",
      "aliases": [
        "AGRO ANDES S.A.C.",
        "Agro Andes Peru"
      ],
      "open_shipments": {
        "supplier": 3,
        "forwarder": 0,
        "customer": 0
      },
      "created_at": "2026-03-02T10:15:00Z",
      "updated_at": "2026-09-14T08:30:00Z"
    }
  ]
}

Errors: 400, 401, 429.

Get one company #

GET /companies/{id} (operation get_company)

Use this to read a company’s roles, other spellings, country, ERP code and how many live shipments it is on. An id from another organization, or of a company that was merged into another, is a 404.

Example response, 200:

{
  "object": "company",
  "id": "cmp_41",
  "name": "Agro Andes SAC",
  "roles": [
    "supplier"
  ],
  "own": false,
  "country": "PE",
  "erp_code": "S-1042",
  "aliases": [
    "AGRO ANDES S.A.C.",
    "Agro Andes Peru"
  ],
  "open_shipments": {
    "supplier": 3,
    "forwarder": 0,
    "customer": 0
  },
  "created_at": "2026-03-02T10:15:00Z",
  "updated_at": "2026-09-14T08:30:00Z"
}

Errors: 400, 401, 403, 404, 429.

List open monitoring alerts #

GET /alerts (operation list_alerts)

Use this to find shipments that Trackberry’s monitoring says have a problem right now: tracking gone quiet, ETA overdue or slipped, cargo sitting at the terminal, and similar. Only open alerts of the kinds customers can see are listed, across all shipments (archived ones included), newest first, keyset paged. Pass shipment to look at one shipment. An alert a member snoozed or dismissed on the issues page is still open and is listed with its state (snoozed_until, dismissed_at); pass hidden to leave those out, as the issues page does, or to list only them.

Example response, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "monitoring_alert",
      "id": "alr_2210",
      "shipment_id": "shp_812",
      "shipment_reference": "SHIP-20260915-K7QX",
      "key": "eta_drift",
      "group": "schedule",
      "severity": "warning",
      "title": "ETA has slipped",
      "summary": "ETA has moved 3 days later than first quoted (2026-10-02 → 2026-10-05).",
      "since": "2026-10-02T06:00:00Z",
      "first_detected_at": "2026-09-25T03:00:00Z",
      "last_detected_at": "2026-09-29T03:00:00Z",
      "resolved_at": null,
      "dismissed_at": null,
      "snoozed_until": null
    }
  ]
}

Errors: 400, 401, 429.

List document checks across shipments #

GET /checks (operation list_checks)

Use this to find paperwork and data problems: missing documents, packing list totals that disagree with the declared ones, invalid container numbers, and similar. By default only checks that failed or warned are listed; pass status to see others. Across all shipments (archived ones included), newest first, keyset paged. Pass shipment to look at one shipment.

Example response, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "shipment_check",
      "id": "chk_9001",
      "shipment_id": "shp_812",
      "shipment_reference": "SHIP-20260915-K7QX",
      "key": "has_commercial_invoice",
      "category": "documents",
      "status": "warning",
      "title": "Commercial invoice",
      "message": "No commercial invoice has been received for this shipment yet.",
      "ran_at": "2026-09-29T03:00:00Z"
    }
  ]
}

Errors: 400, 401, 429.

List the organization’s warehouses #

GET /warehouses (operation list_warehouses)

Use this to learn where the organization receives containers and which weekdays and public-holiday calendar that site works to. A warehouse exists so delivery and collect-by dates skip the days nobody is there. Today there is one per organization, but this is a list. Archived (retired) warehouses are left out unless include_archived=true. Newest first, keyset paged. Opening hours are not recorded, only the weekdays in open_days.

Example response, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "warehouse",
      "id": "whs_12",
      "name": "Main warehouse",
      "street": "Hafenstrasse 1",
      "postal_code": "80331",
      "city": "Munich",
      "country_code": "DE",
      "open_days": [
        "mon",
        "tue",
        "wed",
        "thu",
        "fri"
      ],
      "holiday_region": "DE-BY",
      "effective_holiday_region": "DE-BY",
      "located": true,
      "default": true,
      "archived": false
    }
  ]
}

Errors: 400, 401, 429.

List a warehouse’s closures #

GET /warehouses/{id}/closures (operation list_warehouse_closures)

Use this to see the days the warehouse has been marked shut (stock-taking, the week between Christmas and New Year) or marked open against its calendar (a public holiday it works through). A closure’s word beats the weekly schedule and the holidays alike. By default only closures ending today or later are listed; pass from for earlier ones. Listed in date order, the closure that ends first leading, keyset paged. For a day-by-day answer use the delivery days of the warehouse instead.

Example response, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "warehouse_closure",
      "id": "wcl_41",
      "warehouse_id": "whs_12",
      "starts_on": "2026-12-24",
      "ends_on": "2026-12-24",
      "open": false,
      "note": "Christmas Eve"
    }
  ]
}

Errors: 400, 401, 404, 429.

Get which days a warehouse can receive containers, and why not #

GET /warehouses/{id}/delivery_days (operation get_warehouse_delivery_days)

Use this to answer “is the warehouse open on the 26th” or “why is the collect-by date Tuesday and not Monday”. Each day in the range is usable or not, with the reason: open (an ordinary open day), closure_open (a closure opens it), closure (a closure shuts it), weekday (not one of open_days), warehouse_holiday (a public holiday where the warehouse is) or port_holiday (a public holiday at the port). The first reason that applies wins, in the order closure, weekday, warehouse holiday, port holiday. Port holidays need a shipment, because the port is the one its free-time clock runs at (the same calendar collect_by uses): without shipment they are not counted. The range defaults to 14 days from today and is at most 62 days. Not paged.

Example response, 200:

{
  "object": "warehouse_delivery_days",
  "warehouse_id": "whs_12",
  "shipment_id": null,
  "from": "2026-12-23",
  "to": "2026-12-28",
  "calendars": [
    "DE-BY"
  ],
  "days": [
    {
      "date": "2026-12-23",
      "weekday": "wed",
      "usable": true,
      "reason": "open"
    },
    {
      "date": "2026-12-24",
      "weekday": "thu",
      "usable": false,
      "reason": "closure"
    },
    {
      "date": "2026-12-25",
      "weekday": "fri",
      "usable": false,
      "reason": "warehouse_holiday"
    },
    {
      "date": "2026-12-26",
      "weekday": "sat",
      "usable": false,
      "reason": "weekday"
    },
    {
      "date": "2026-12-27",
      "weekday": "sun",
      "usable": false,
      "reason": "weekday"
    },
    {
      "date": "2026-12-28",
      "weekday": "mon",
      "usable": true,
      "reason": "open"
    }
  ]
}

Errors: 400, 401, 404, 429.

List the product catalogue #

GET /products (operation list_products)

Use this to look up the organization’s own products (the item master loaded from its ERP) and what each supplier calls them: the supplier’s reference and description, and the factor that converts the supplier’s quantity into the organization’s unit. Answers “what is our SKU for the code printed on this supplier’s document” and “which products does this supplier ship us”. Newest first, keyset paged. q searches the SKU, the description and any supplier’s reference (ignoring case, spaces and punctuation in a reference).

Example response, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "product",
      "id": "prd_310",
      "sku": "AVO-HASS-4KG",
      "description": "Hass avocado, 4 kg box",
      "unit": "box",
      "properties": {
        "family": "Avocado"
      },
      "discontinued_at": null,
      "supplier_references": [
        {
          "supplier": {
            "id": "cmp_41",
            "name": "Agrofresh Peru"
          },
          "reference": "OR-2-369",
          "description": "Palta Hass 4 kg",
          "conversion_factor": 1,
          "status": "confirmed",
          "confirmed_at": "2026-10-02T09:15:00Z"
        }
      ],
      "supplier_descriptions": [
        {
          "supplier": {
            "id": "cmp_41",
            "name": "Agrofresh Peru"
          },
          "description": "Hass avocados 12 x 4 kg",
          "trusted": true,
          "confirmations": 3,
          "last_confirmed_at": "2026-10-20T11:00:00Z"
        }
      ],
      "created_at": "2026-09-01T08:00:00Z",
      "updated_at": "2026-10-20T11:00:00Z"
    }
  ]
}

Errors: 400, 401, 403, 429.

Get one product #

GET /products/{id} (operation get_product)

Use this to read one product with every supplier reference and description for it. The id comes from list_products, or from a purchase order line’s product_id.

Example response, 200:

{
  "object": "product",
  "id": "prd_310",
  "sku": "AVO-HASS-4KG",
  "description": "Hass avocado, 4 kg box",
  "unit": "box",
  "properties": {
    "family": "Avocado"
  },
  "discontinued_at": null,
  "supplier_references": [
    {
      "supplier": {
        "id": "cmp_41",
        "name": "Agrofresh Peru"
      },
      "reference": "OR-2-369",
      "description": "Palta Hass 4 kg",
      "conversion_factor": 1,
      "status": "confirmed",
      "confirmed_at": "2026-10-02T09:15:00Z"
    }
  ],
  "supplier_descriptions": [
    {
      "supplier": {
        "id": "cmp_41",
        "name": "Agrofresh Peru"
      },
      "description": "Hass avocados 12 x 4 kg",
      "trusted": true,
      "confirmations": 3,
      "last_confirmed_at": "2026-10-20T11:00:00Z"
    }
  ],
  "created_at": "2026-09-01T08:00:00Z",
  "updated_at": "2026-10-20T11:00:00Z"
}

Errors: 400, 401, 403, 404, 429.

List purchase orders with their lines #

GET /purchase_orders (operation list_purchase_orders)

Use this to see what the organization has ordered from its suppliers and how much of it has arrived or been matched to paperwork. Answers “what is still to come from Supplier X” and “has PO 4512 shipped”. Lines are grouped by supplier and order number, newest order first, keyset paged by order. Only orders with an open line are listed by default (lines the latest ERP export still carries), each with all its lines; pass status for closed ones or all. Each line has the ERP’s ordered and received quantities, the quantity still remaining, and what has since been matched to supplier invoices and packing lists on shipments, so a line with nothing invoiced or packed has not been seen on a shipment yet.

Example response, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "purchase_order",
      "id": "por_5100",
      "order_number": "AA/4512",
      "supplier": {
        "id": "cmp_41",
        "name": "Agrofresh Peru"
      },
      "status": "open",
      "lines": [
        {
          "id": "pol_5100",
          "line_number": "10",
          "product_id": "prd_310",
          "article_code": "AVO-HASS-4KG",
          "supplier_reference": "OR-2-369",
          "description": "Hass avocado, 4 kg box",
          "quantity_ordered": 1000,
          "quantity_received": 200,
          "quantity_remaining": 800,
          "quantity_invoiced": 800,
          "quantity_packed": 800,
          "unit_price": 1.5,
          "currency": "EUR",
          "expected_on": "2026-12-01",
          "status": "open",
          "closed_at": null
        }
      ],
      "shipment_ids": [
        "shp_812"
      ]
    }
  ]
}

Errors: 400, 401, 403, 429.

List expected containers #

GET /expected_shipments (operation list_expected_shipments)

Use this to see the containers suppliers have agreed to send, including ones that have no shipping document and are not tracked yet. Answers “what is expected from Supplier X in the coming weeks” and “which expected containers are overdue”. Each has the supplier, order number, produce, boxes, the expected week, the documents received for it (proformas and others) and, once Trackberry matched it to a tracked shipment, that shipment’s id. Planned containers by default; pass status for matched or cancelled ones. Newest first, keyset paged.

Example response, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "expected_shipment",
      "id": "exs_90",
      "status": "planned",
      "supplier": {
        "id": "cmp_41",
        "name": "Agrofresh Peru"
      },
      "order_number": "PO-77",
      "produce_name": "Hass avocado",
      "variety": null,
      "calibre": null,
      "boxes": 1000,
      "pallets": 20,
      "expected_week_start": "2026-12-07",
      "expected_week_end": "2026-12-13",
      "overdue": false,
      "origin_location": "Callao",
      "destination_location": "Rotterdam",
      "unit_price": 9.5,
      "price_basis": "box",
      "currency": "USD",
      "notes": null,
      "shipment_id": null,
      "matched_at": null,
      "match_source": null,
      "cancelled_at": null,
      "documents": [
        {
          "kind": "proforma",
          "filename": "proforma-PO-77.pdf",
          "subject": "Proforma PO-77",
          "received_at": "2026-11-02T09:00:00Z"
        }
      ],
      "created_at": "2026-11-01T08:00:00Z",
      "updated_at": "2026-11-02T09:00:00Z"
    }
  ]
}

Errors: 400, 401, 403, 429.

List the organization’s labels #

GET /labels (operation list_labels)

Use this to see which labels the organization has, with their ids, names and colors: the catalogue that the labels of a shipment are drawn from. Newest first, keyset paged. q narrows it to the labels whose name holds every word given, in any case and ignoring emoji and punctuation.

Example response, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "label",
      "id": "lbl_4",
      "name": "Retail",
      "color": "blue",
      "color_hex": "#3b82f6"
    },
    {
      "object": "label",
      "id": "lbl_3",
      "name": "Priority",
      "color": "red",
      "color_hex": "#ef4444"
    }
  ]
}

Errors: 400, 401, 429.

List the inspection reports of a shipment with their per-pallet results #

GET /shipments/{shipment_id}/inspections (operation list_shipment_inspections)

Use this to read what quality inspectors found: for each inspection report read from an inspection document, who inspected, when and where, the overall score and impression, and one result per pallet (score, recommendation, defects, remarks). Oldest first, not paged. Photos are not served here: each report and result only says how many photos it has (photo_count); the report’s original file is the document in document_id.

Example response, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "inspection_report",
      "id": "ins_14",
      "shipment_id": "shp_812",
      "document_id": "doc_305",
      "report_number": "INS-2026-0420",
      "inspection_company": "PPECB",
      "inspection_date": "2026-09-20",
      "inspection_location": "Rotterdam",
      "inspector_name": "A. de Vries",
      "container_number": "MEDU1234567",
      "produce_description": "Table grapes",
      "total_pallets": 20,
      "overall_score": 7.5,
      "overall_impression": "Good condition",
      "overall_impression_category": "good",
      "letter_grade": "B",
      "general_remarks": "Cold chain held throughout.",
      "photo_count": 3,
      "results": [
        {
          "object": "inspection_result",
          "id": "inr_201",
          "inspection_report_id": "ins_14",
          "pallet_id": "plt_9001",
          "pallet_number": "PAL0001",
          "lot_code": "L2409",
          "produce_name": "Grapes",
          "variety": "Sweet Globe",
          "calibre": "L",
          "score": 8.0,
          "recommendation": "Release",
          "defects": {
            "decay": "2%"
          },
          "remarks": null,
          "photo_numbers": [
            1,
            2
          ],
          "pallet_match_approximate": false,
          "photo_count": 2
        }
      ],
      "created_at": "2026-09-21T08:00:00Z",
      "updated_at": "2026-09-21T08:00:00Z"
    }
  ]
}

Errors: 400, 401, 403, 404, 429.

List the emails filed on a shipment #

GET /shipments/{shipment_id}/messages (operation list_shipment_messages)

Use this to see which emails Trackberry attached to a shipment and what each one was about: its category (arrival notice, delay notice, customs update and so on), urgency, sender, subject, a short summary, and when it was received. A shipment split from a bill of lading shows the emails of the whole group, as the shipment page does, so shipment_id can be a sibling’s. The subject and summary come from the email and are not verified: trusted says whether the sender was recognized and authenticated, or a member released the email. held_at, released_at and dismissed_at tell whether an email from a sender Trackberry did not recognize was held for a member’s review, and whether it was then released or set aside. The email body is never returned. Newest first, keyset paged.

Example response, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "shipment_message",
      "id": "msg_5120",
      "shipment_id": "shp_812",
      "category": "delay_notice",
      "urgency": "warning",
      "trusted": true,
      "sender_name": "Anna Forwarder",
      "sender_email": "[email protected]",
      "subject": "MEDU1234567: vessel delayed",
      "summary": "The vessel is delayed by two days because of port congestion.",
      "received_at": "2026-09-28T09:15:00Z",
      "held_at": null,
      "released_at": null,
      "dismissed_at": null
    }
  ]
}

Errors: 400, 401, 403, 404, 429.

List the claim notices sent about a shipment #

GET /shipments/{shipment_id}/claim_notices (operation list_shipment_claim_notices)

Use this to see which notices of damage were sent to a carrier or forwarder about a shipment, to whom and when. Only notices that went out are listed (an attempt that failed is not), most recently sent first, not paged. The text of a notice is not in the list: it is the legal record of what was said, so read it with get_claim_notice.

Example response, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "claim_notice",
      "id": "cln_31",
      "shipment_id": "shp_812",
      "kind": "damage",
      "recipient_email": "[email protected]",
      "locale": "en",
      "sent_at": "2026-10-06T10:42:00Z"
    }
  ]
}

Errors: 400, 401, 403, 404, 429.

Get one claim notice with its text #

GET /claim_notices/{id} (operation get_claim_notice)

Use this to read exactly what was sent to the carrier or forwarder: the notice’s text, in the language it went out in, with the recipient and the time it was sent. The text is the record of what was said and when, and is never edited after sending. A notice that did not go out is a 404.

Example response, 200:

{
  "object": "claim_notice_detail",
  "id": "cln_31",
  "shipment_id": "shp_812",
  "kind": "damage",
  "recipient_email": "[email protected]",
  "locale": "en",
  "sent_at": "2026-10-06T10:42:00Z",
  "body": "Dear Sir or Madam,\n\nOn 2026-10-05 the inspection of container MEDU1234567 found damaged cartons on 4 pallets. We hold you responsible and ask you to acknowledge this notice."
}

Errors: 400, 401, 403, 404, 429.

List the organization’s carrier free-time terms #

GET /carrier_free_times (operation list_carrier_free_times)

Use this to see the free-time terms the organization has negotiated with each carrier: demurrage days, detention days and whether they count calendar or working days. These are the terms behind the free-time numbers of each shipment (free_days_source says when a shipment used them). Newest first, keyset paged.

Example response, 200:

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "carrier_free_time",
      "id": "cft_7",
      "carrier_name": "Maersk",
      "demurrage_days": 10,
      "detention_days": 7,
      "day_basis": "calendar",
      "updated_at": "2026-08-12T09:30:00Z"
    }
  ]
}

Errors: 400, 401, 403, 429.

Download every shipment as one flat table (CSV or JSON) #

GET /feed/shipments (operation list_feed_shipments)

One row per shipment with identifiers, mode, carrier, supplier, origin and destination, ports, ETD/ATD/ETA/ATA, transit and delay days, free time end, container and cargo totals, invoice value and created/archived dates. Not paged: the whole table is returned in one streamed response. Append .csv for CSV; .json or no extension returns JSON.

Example response, 200:

{
  "object": "feed",
  "name": "shipments",
  "columns": [
    "id",
    "reference",
    "erp_reference",
    "display_name",
    "transport_type",
    "load_type",
    "status",
    "archived",
    "transport_reference",
    "house_bl",
    "container_count",
    "produce",
    "organic",
    "carrier",
    "carrier_scac",
    "supplier",
    "customer",
    "forwarder",
    "consignor",
    "consignee",
    "origin_location",
    "origin_country",
    "destination_location",
    "destination_country",
    "pol",
    "pol_locode",
    "pod",
    "pod_locode",
    "etd",
    "atd",
    "eta",
    "original_eta",
    "ata",
    "availability_date",
    "transit_days",
    "delay_days",
    "free_time_end",
    "demurrage_state",
    "demurrage_free_days",
    "demurrage_overdue_days",
    "detention_last_free_day",
    "detention_overdue_days",
    "pallets",
    "boxes",
    "net_weight_kg",
    "gross_weight_kg",
    "co2_tonnes",
    "invoice_value",
    "invoice_currency",
    "created_at",
    "approved_at",
    "validated_at",
    "archived_at",
    "updated_at",
    "net_weight_lb",
    "gross_weight_lb",
    "origin_code",
    "destination_code"
  ],
  "data": [
    {
      "id": "shp_812",
      "reference": "SHIP-20260915-K7QX",
      "erp_reference": "PO-88213",
      "display_name": "MSCU1234567",
      "transport_type": "ocean",
      "load_type": "fcl",
      "status": "in_transit",
      "archived": false,
      "transport_reference": "MEDURU156671",
      "house_bl": "HBL20260917",
      "container_count": 2,
      "produce": "Avocado; Lime",
      "organic": false,
      "carrier": "MSC",
      "carrier_scac": "MSCU",
      "supplier": "Fruta del Sol SA",
      "customer": "Fresh Imports Ltd",
      "forwarder": "Kuehne+Nagel",
      "consignor": "Fruta del Sol SA",
      "consignee": "Fresh Imports Ltd",
      "origin_location": "Valencia",
      "origin_country": "Spain",
      "destination_location": "Rotterdam",
      "destination_country": "Netherlands",
      "pol": "Valencia",
      "pol_locode": "ESVLC",
      "pod": "Rotterdam",
      "pod_locode": "NLRTM",
      "etd": "2026-09-10T18:00:00Z",
      "atd": "2026-09-10T18:00:00Z",
      "eta": "2026-10-05T06:00:00Z",
      "original_eta": "2026-10-02T06:00:00Z",
      "ata": "2026-10-05T08:30:00Z",
      "availability_date": "2026-10-07",
      "transit_days": 25.6,
      "delay_days": 3.1,
      "free_time_end": "2026-10-12",
      "demurrage_state": "running",
      "demurrage_free_days": 7,
      "demurrage_overdue_days": 0,
      "detention_last_free_day": "2026-10-19",
      "detention_overdue_days": 0,
      "pallets": 22,
      "boxes": 2860,
      "net_weight_kg": 12870.0,
      "gross_weight_kg": 14100.0,
      "co2_tonnes": 4.25,
      "invoice_value": 48250.5,
      "invoice_currency": "USD",
      "created_at": "2026-09-15T08:00:00Z",
      "approved_at": "2026-09-15T08:05:00Z",
      "validated_at": "2026-09-15T09:00:00Z",
      "archived_at": null,
      "updated_at": "2026-10-05T09:00:00Z",
      "net_weight_lb": 28373.49,
      "gross_weight_lb": 31085.18,
      "origin_code": "ESVLC",
      "destination_code": "NLRTM"
    }
  ]
}

Errors: 400, 401, 429.

Download tracking events (milestones) as one flat table #

GET /feed/events (operation list_feed_events)

One row per tracking event, with its shipment id and reference so it joins to the shipments feed. Only the last 90 days by default. Append .csv for CSV; .json or no extension returns JSON.

Example response, 200:

{
  "object": "feed",
  "name": "events",
  "columns": [
    "id",
    "shipment_id",
    "shipment_reference",
    "container_number",
    "milestone",
    "actual",
    "occurred_at",
    "location_name",
    "location_code",
    "location_country_code",
    "vessel_name",
    "vessel_imo",
    "voyage",
    "flight_number",
    "latitude",
    "longitude"
  ],
  "data": [
    {
      "id": "evt_90211",
      "shipment_id": "shp_812",
      "shipment_reference": "SHIP-20260915-K7QX",
      "container_number": "MSCU1234567",
      "milestone": "discharged",
      "actual": true,
      "occurred_at": "2026-10-05T08:30:00Z",
      "location_name": "Rotterdam",
      "location_code": "NLRTM",
      "location_country_code": "NL",
      "vessel_name": "MSC AURORA",
      "vessel_imo": "9876543",
      "voyage": "FA640W",
      "flight_number": null,
      "latitude": 51.95,
      "longitude": 4.14
    }
  ]
}

Errors: 400, 401, 429.

Download the statistics page’s KPIs as rows of metric, period, dimension and value #

GET /feed/kpis (operation list_feed_kpis)

The KPIs of the Statistics page as rows, computed by the same code. Metrics, with the dimension each one uses: shipments_created (monthly, transport_type: ocean or air); shipments_by_carrier (carrier), shipments_by_lane (lane), shipments_by_origin_country and shipments_by_destination_country (the country): shipments in the window; arrivals_on_time, arrivals_late_up_to_5_days and arrivals_late_over_5_days (by carrier and by lane): arrivals against the original ETA; port_dwell_median_days, port_dwell_p10_days, port_dwell_p90_days, port_dwell_q1_days, port_dwell_q3_days and port_dwell_containers (destination_port): days containers sit in the destination port; on_time_arrival_pct and arrivals_measured (monthly, no dimension); co2_tonnes (monthly, no dimension); shipments_by_produce (monthly, produce); shipments_by_supplier (monthly, supplier: the 8 suppliers with most shipments); incidents (monthly, incident_type: delay, rollover, free_time_breach, document_error or customs_hold, unit incidents); and for each of carrier, forwarder and supplier (the 10 with most incidents) incidents_by_<dimension> (unit incidents), shipments_with_incidents_by_<dimension> (unit shipments) and incident_rate_by_<dimension> (unit per_100_shipments), all over the window. Incidents are counted by the month their shipment was created in; the rules are in the Statistics guide. Append .csv for CSV; .json or no extension returns JSON.

Example response, 200:

{
  "object": "feed",
  "name": "kpis",
  "columns": [
    "metric",
    "period_start",
    "period_end",
    "dimension",
    "dimension_value",
    "value",
    "unit"
  ],
  "data": [
    {
      "metric": "shipments_created",
      "period_start": "2026-09-01",
      "period_end": "2026-09-30",
      "dimension": "transport_type",
      "dimension_value": "ocean",
      "value": 14,
      "unit": "shipments"
    },
    {
      "metric": "arrivals_late_up_to_5_days",
      "period_start": "2026-04-01",
      "period_end": "2026-10-09",
      "dimension": "carrier",
      "dimension_value": "MSC",
      "value": 4,
      "unit": "shipments"
    }
  ]
}

Errors: 400, 401, 429.

Upload a document for extraction #

POST /documents (operation upload_document)

Use this to have Trackberry read a loading sheet, packing list, invoice or bill of lading and turn it into structured data, whether or not the shipment is tracked with Trackberry. Give shipment_id to file it on a shipment you already have, or container_number to file it on the live shipment carrying that container; with neither, or with a container no live shipment carries, a new draft shipment is made for it and is not tracked. The response is the document with parse_status pending: the file is virus-scanned, then classified and read within a few minutes. Poll get_document until data_available is true and then call get_document_data, or subscribe to the document.processed webhook. The data goes to your ERP only after the same review as any other document. Needs the write scope. A new shipment is refused with billing_blocked (403) when the organization’s billing does not allow one. Recorded in the audit log as made through the API. Limited to 120 uploads an hour per token.

Send the body as multipart/form-data:

curl https://trackberry.com/api/v1/documents \
  -H "Authorization: Bearer tb_your_write_token" \
  -H "Idempotency-Key: 6f1c2a9e-1b7d-4c55-9a43-3f0e8d2b7c10" \
  -F [email protected] \
  -F container_number=MSCU1234566

Example response, 201 (a 200 with the same body for a replay: the Idempotency-Key was already used for this request, or this file is already on this shipment):

{
  "object": "document",
  "id": "doc_514",
  "shipment_id": "shp_903",
  "type": "unknown",
  "filename": "loading-sheet-0412.pdf",
  "content_type": "application/pdf",
  "byte_size": 182344,
  "source": "api",
  "parse_status": "pending",
  "downloadable": false,
  "page_range": null,
  "data_available": false,
  "created_at": "2026-10-15T08:12:00Z",
  "updated_at": "2026-10-15T08:12:00Z"
}

Errors: 400, 401, 403, 429.

Get one document #

GET /documents/{id} (operation get_document)

Use this to describe a document you found through list_shipment_documents: its type, file name, size, source, processing status, and whether extracted data is available. download_document_file returns the file itself. Only current documents are found; a replaced or reference-only document is a 404.

Example response, 200:

{
  "object": "document",
  "id": "doc_301",
  "shipment_id": "shp_812",
  "type": "packing_list",
  "filename": "PL_MEDURU156671.xlsx",
  "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "byte_size": 48211,
  "source": "email_upload",
  "parse_status": "parsed",
  "downloadable": true,
  "page_range": null,
  "data_available": true,
  "created_at": "2026-09-15T12:01:00Z",
  "updated_at": "2026-09-15T12:03:00Z"
}

Errors: 400, 401, 404, 429.

Download a document’s file #

GET /documents/{id}/file (operation download_document_file)

Use this to fetch the original file of a document (the PDF, scan, spreadsheet or picture that was uploaded or emailed), for archiving it or reading what extraction did not cover. The body is the file, sent as an attachment with its own Content-Type and file name in Content-Disposition. Only a document whose downloadable is true has one: a document without a file, or whose file has not passed the security scan (still being scanned, or blocked), is a 404.

curl -H "Authorization: Bearer tb_..." -OJ https://trackberry.com/api/v1/documents/doc_301/file

Errors: 400, 401, 404, 429.

Get the data Trackberry extracted from a document #

GET /documents/{id}/data (operation get_document_data)

Use this to read the structured content Trackberry parsed out of a document (a packing list’s lines, an invoice’s totals, a bill of lading’s parties and departure and arrival days, a certificate’s numbers). Check data_available on the document first, or expect an empty result. When nothing was extracted, or the document type has no structured schema, the response is still a 200 with schema null and fields an empty object.

Example response, 200:

{
  "object": "document_data",
  "document_id": "doc_301",
  "type": "packing_list",
  "schema": "packing_list",
  "fields": {
    "packing_list_number": "PL-2026-0915",
    "exporter_name": "Agro Andes SAC",
    "exporter_port": "Callao",
    "exporter_country": "Peru",
    "importer_name": "Fresh Imports Ltd",
    "importer_country": "Netherlands",
    "total_net_weight": 960.0,
    "total_boxes": 240,
    "diagram_pallet_numbers": [],
    "container_number": "MSCU1234567",
    "line_items": [
      {
        "pallet_number": "PAL0001",
        "produce_name": "Grapes",
        "variety": "Sweet Globe",
        "size_calibre": "L",
        "quality_category": "Class I",
        "format": "4.0 kg carton",
        "label": "Andes Gold",
        "produce_type": "Organic",
        "ggn": "4049929123456",
        "comment": null,
        "number_of_boxes": 120,
        "net_weight_kg": 480.0,
        "box_weight_kg": 4.0,
        "gross_weight_kg": 522.0
      }
    ]
  }
}

Errors: 400, 401, 404, 429.

Get this OpenAPI description #

GET /openapi.json (operation get_openapi_document)

Use this to load the machine-readable description of the API into an agent, a code generator or a documentation tool. Public: no token needed. It describes the latest API version and does not depend on the organization or on Trackberry-Version. It counts against the per-IP limit for requests without a token. Cacheable for an hour.

No parameters.

Returns 200 with an OpenAPI 3.1 document as JSON (it is the file this reference is built from).

Errors: 429.

Objects #

Objects the API returns carry an object field naming their type, and most have an id. Nested objects are shown with dotted field names. The type column says or null where a field can be null. Place is a building block used inside other objects; List and Error are the envelopes for lists and errors.

Error object #

The single error body used by every failure.

List object #

The envelope every list endpoint returns.

Organization object #

The organization a token reads, with the token that made the request.

Shipment object #

A consignment of goods: one bill of lading or air waybill, its containers, and everything Trackberry knows about where it is and what is in it.

Place object #

An origin or a destination.

Container object #

One container of a shipment.

Label object #

A colored tag the organization uses to group shipments.

InspectionReport object #

A quality inspection report read from an inspection document, with one result per pallet. Photos are not served; only their counts are given.

InspectionResult object #

What an inspection report found on one pallet or lot.

ShipmentMessage object #

An email Trackberry filed on a shipment, without its body.

ClaimNotice object #

A notice of damage that was sent to a carrier or forwarder about a shipment, without its text. Read the text with get_claim_notice.

ClaimNoticeDetail object #

One sent claim notice with its text, the record of what was said and when.

CarrierFreeTime object #

The free-time terms the organization has negotiated with one carrier.

Timeline object #

The route, tracking events and ETA history of one shipment.

ShipmentLeg object #

One leg of a shipment’s planned route, for example a sea leg followed by a road leg.

TrackingEvent object #

One milestone of the cargo’s journey, actual or estimated.

EtaRevision object #

One observed change of a shipment’s estimated arrival. Revisions are recorded only when the ETA moves by 5 minutes or more.

ShipmentMap object #

The data to draw one shipment’s voyage on a map.

ShipmentMapData object #

What a map draws for one shipment. The keys are camelCase because they are the names the shipment page’s own map reads. All longitudes share one continuous scale: they can run past 180 or below -180 when a route crosses the antimeridian, which map libraries draw correctly.

MapPoint object #

A point on a map.

FreeTimeSummary object #

The demurrage and detention position of one shipment. Demurrage is the charge for leaving a container at the terminal past its free days; detention is the charge for keeping the empty container past its free days. Only ocean shipments have clocks.

FreeTimeClock object #

One demurrage or detention clock for one container. Demurrage starts at the container’s discharge and stops at gate out (or, without one, at the return of the empty container). Detention starts at gate out and stops at the return of the empty container. Days are counted in the local calendar of the port. This object has no id.

MonitoringAlert object #

A problem Trackberry’s monitoring found on a shipment and that is still open. An alert opens when a problem starts, can grow from warning to critical, and disappears from the API once resolved.

ShipmentCheck object #

The result of one document check run against one shipment, for example whether a packing list is present or whether its box count matches the declared total.

Document object #

A file attached to a shipment, such as a bill of lading, packing list, invoice or certificate, with its processing state. The file itself is not part of this object: GET /documents/{id}/file serves it when downloadable is true.

DocumentData object #

The structured data Trackberry extracted from one document. The set of fields depends on schema.

PackingList object #

A packing list read from a document, saying what the exporter states is in the container, by pallet and produce line.

Pallet object #

One pallet of a packing list.

PackingLine object #

One produce line on a pallet, a quantity of one variety, calibre and pack format.

ShareLink object #

A tracking link made for one of your customers. It opens the ordinary public tracking page, led by the customer’s own reference, and can be switched off without touching any other link.

Preallocation object #

Boxes of one packing line set aside for a customer, with the tentative price they were given.

CompanyReference object #

A company a shipment, product, purchase order or expected container is linked to, enough to name it and to look it up with get_company (the REST operation and the MCP tool of the same name).

Company object #

A supplier, forwarder or customer of the organization. There is no contact email; Trackberry does not store one.

ShipmentNotes object #

A shipment’s notes as they stand after a write.

ShipmentLabels object #

The labels a shipment carries after a label write.

CheckRun object #

A request to run a shipment’s checks again.

TrackingRefresh object #

A request for fresh tracking on a shipment.

CheckAcknowledgement object #

A failed or warning check somebody accepted, with the reason they gave. The check keeps its status.

Warehouse object #

The importer’s own site, where containers are delivered. It exists so the dates Trackberry promises skip the days nobody is there to receive the goods. Opening hours are not recorded, only the weekdays it opens.

WarehouseClosure object #

A run of dates a warehouse is shut or, with open, open although its calendar says otherwise. A closure’s word beats the weekly schedule and the public holidays alike.

WarehouseDeliveryDays object #

Each day of a range with whether a container can be received at the warehouse and why not, counted the way the free-time collect_by date is.

WarehouseDeliveryDay object #

One day of a warehouse’s delivery calendar.

Product object #

One product of the organization’s own catalogue (its item master, as loaded from its ERP) with what each supplier calls it. Trackberry has no separate ERP id for a product: the sku is the ERP’s item code.

PurchaseOrder object #

One purchase order: the lines of one order number from one supplier, as the organization’s ERP lists them, with how much of each has been matched to supplier invoices and packing lists. Every line of the order is included, whatever the request’s filters were; the filters only choose which orders are listed.

ExpectedShipment object #

A container a supplier has agreed to send, planned before any shipping document exists, with the documents received for it and, once matched, the tracked shipment it became.

ShipmentFeedRow object #

One row of the shipments feed: a shipment flattened for a BI tool. Every column is always present; a column with no value is empty in CSV and null in JSON.