---
title: "Create a tracking link for one of your customers"
method: POST
path: "/shipments/{shipment_id}/share_links"
tags: ["Customer links"]
---

# Create a tracking link for one of your customers

`POST /shipments/{shipment_id}/share_links`

## Request

- Base URL: `https://trackberry.com/api/v1`
- URL: `https://trackberry.com/api/v1/shipments/{shipment_id}/share_links`
- Auth: HTTP bearer

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.

## Path parameters

- `shipment_id` string, required

## Headers

- `Trackberry-Version` string

## Request body

- object: The link to make.
  - `customer_reference` string, required: The customer's own reference for this order, such as a purchase order or sales order number. Shown to the customer on the tracking page.
  - `label` string: A note to tell your links apart. Only your team sees it; the customer never does.

## Response `200`

The shipment already had an active link for this `customer_reference`; it is returned unchanged.

- ShareLink: 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.
  - `object` 'share_link', required: Always `share_link`.
  - `id` string, required: The customer link id.
  - `shipment_id` string, required: The shipment the link opens.
  - `customer_reference` string, required: The customer's own reference for the order, as shown to the customer.
  - `label` string, nullable, required: Your own note to tell links apart. Never shown to the customer. Null when none was given.
  - `url` string, nullable, required: The link to give the customer. The secret part of the link is only ever inside this URL. Null once the link is revoked.
  - `active` boolean, required: False once the link has been revoked.
  - `revoked_at` string, date-time, nullable, required: When the link was revoked. Null while it is active.
  - `created_at` string, date-time, required: When the link was created.

## Other responses

- `201`: The link was created.
- `400`: A parameter or header is invalid (`invalid_parameter`, with `param` naming it), a customer link cannot be made for this shipment (`not_shareable`), an uploaded file is empty, over 50 MB or of a type Trackberry does not read (`file_empty`, `file_too_large`, `unsupported_file_type`), an upload's container number is on more than one live shipment (`ambiguous_container`), an `Idempotency-Key` was already used for a different request (`idempotency_key_reused`) or `Trackberry-Version` names an unpublished version (`invalid_version`, with `param` set to `Trackberry-Version`). A parameter that must be a single value but was sent as an array or hash (`status[]=x`, `q[a]=1`) is also a 400.
- `401`: No token was sent (`missing_token`) or the token is wrong, expired, revoked, or its user left the organization (`invalid_token`). The response has a `WWW-Authenticate` header.
- `403`: The token may not do this. `insufficient_scope`: a write endpoint was called with a read-only token. `read_only_member`: a write endpoint was called by a token whose owner is now a read-only member of the organization. `revoke_not_allowed`: the link can only be revoked by an admin or by the member who made it. `billing_blocked`: an upload needed a new shipment and the organization's billing does not allow one.
- `404`: No such object in this organization (`resource_missing`). This is also the answer for an id of another organization, an id with the wrong prefix, or a malformed id, so the API never confirms that an object exists elsewhere.
- `429`: A rate limit was hit (`rate_limited`). Wait the number of seconds in `Retry-After`. A BI feed answers the same way (`feed_in_progress`) when another feed for the organization is still being produced.

---

[API](https://skmtc.dev/trackberry/apis/trackberry-api.md) · [All operations](https://skmtc.dev/trackberry/apis/trackberry-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trackberry/apis/trackberry-api/revisions/be06ee7c17f3?raw)