> For the complete documentation index, see [llms.txt](https://docs.terminal.africa/tship/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.terminal.africa/tship/changelog.md).

# Changelog

Integration changes and preparation guidance for the Terminal Shipping API.

## 19 November 2026 — Hub issues: every drop-off hub issue in one object

When a parcel reaches a Terminal drop-off hub, the hub can find a problem with it, correct its booking or repackage it for a fee. These now reach your integration in one place. Follow the [Hub Issues Workflow](https://docs.terminal.africa/tship/guides/hub-issues-workflow.md) to integrate.

### One object

`hub_issues` lists every issue in one array, whatever its kind, in the words we send your customer. It says what waits for an answer, the total and the deadline. [Get Shipment](https://docs.terminal.africa/tship/shipment/get-shipment.md) returns it as `data.hub_issues`, and [Get Hub Issues](https://docs.terminal.africa/tship/shipment/get-hub-issues.md) returns it on its own. See [The Hub Issues Object](https://docs.terminal.africa/tship/shipment.md#the-hub-issues-object).

### One answer

[Approve Hub Issues](https://docs.terminal.africa/tship/shipment/approve-hub-issues.md) and [Decline Hub Issues](https://docs.terminal.africa/tship/shipment/decline-hub-issues.md) answer everything waiting on a shipment at once, with [Quote Hub Issues](https://docs.terminal.africa/tship/shipment/quote-hub-issues.md) for the amount in your wallet's currency. A parcel can only go on once every issue is settled, so they are answered together.

### Three events

`hub_issue.reported`, `hub_issue.updated` and `hub_issue.reminder` each carry the whole `hub_issues` object. See [Hub Issue Events](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/hub-issue.md). In the sandbox, [Simulate Webhook](https://docs.terminal.africa/tship/webhooks/simulate-webhook.md) sends a test delivery of each from one of your shipments.

### Integration checklist

1. Subscribe your webhook to the three `hub_issue.*` events. See [Create Webhook](https://docs.terminal.africa/tship/webhooks/create-webhook.md).
2. When `hub_issues.action` is not `null`, get an answer before `action.answer_by`. An approval that gets no answer lapses: the shipment is cancelled and the parcel kept at the hub for collection.
3. Show `title` and `message` to your customer as they are, or decide on their behalf.
4. Keep the delivery with the latest `hub_issues.as_of`: an answer covering two issues can send two `hub_issue.updated` events a moment apart, in either order.

`transaction.success` and `shipment.tracking_updated` keep firing as before.

## 29 October 2026 — Hub Relabelling: prepare your integration

Hub parcel corrections are being prepared for rollout. The hub can correct the weight, size, parcel count or contents of an existing shipment. A correction may need a replacement carrier waybill or an additional charge approved by the customer. This notice describes what your integration should handle when the feature is enabled.

### Replacement waybill event

Subscribe to `shipment.tracking_updated`. It is sent when a hub correction replaces the carrier waybill and includes `data.tracking_change`:

```json
{
    "previous_tracking_number": "7412089553",
    "tracking_number": "7412090123",
    "shipping_label_url": "https://api.terminal.africa/v1/shipments/label/SH-EXAMPLE000001?v=1793268000000",
    "reason": "hub_correction",
    "correction_id": "HCR-EXAMPLE000001",
    "changed_at": "2026-10-29T10:00:00.000Z"
}
```

The values above are illustrative. Keep `shipment_id` as the stable reference for your shipment and update the stored carrier tracking number and label link. Handle this named event explicitly; a generic `shipment.updated` subscription does not replace it. See the [full shipment event example](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/shipment.md).

### Correction charge event

The existing `transaction.success` event also covers an additional charge captured for an approved hub correction. Its `shipment` field links it to the shipment; `amount` and `currency` describe the additional debit. A wallet hold alone is not a debit, and a correction with no added charge has no correction-charge transaction. See [Transaction payloads](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/transaction.md#hub-correction-charges).

A waybill change does not necessarily mean a charge, and a price-only charge does not necessarily change the waybill. Handle the two events independently.

### Existing tracking references keep working

A replaced waybill number continues to resolve to the same live shipment through `GET /v1/shipments/track/:shipment_id`. The Terminal shipment ID is unchanged. Use the replacement label for shipping; the former label is retired. See [Track a Shipment](https://docs.terminal.africa/tship/shipment/track-a-shipment.md).

### Integration checklist

1. Ensure your webhook subscriptions include `shipment.tracking_updated` and `transaction.success`. See [Create Webhook](https://docs.terminal.africa/tship/webhooks/create-webhook.md).
2. Store the Terminal `shipment_id` separately from the carrier tracking number, and update your current number and label link when a waybill changes.
3. Verify webhook signatures and make processing idempotent. Deduplicate correction-charge deliveries using `transaction_id`, and recognize repeated tracking changes using the shipment, correction reference and replacement number.
4. Do not assume the tracking-change event and transaction event arrive in order. Fetch [Get Shipment](https://docs.terminal.africa/tship/shipment/get-shipment.md) when you need the latest shipment.
5. Test the documented examples before relying on the real rollout events. Shipment and transaction events retain the `{ "event": "...", "data": {} }` envelope; the pickup-specific event ID and version fields are not added by this change.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.terminal.africa/tship/changelog.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
