---
title: "List the customer links of a shipment"
method: GET
path: "/shipments/{shipment_id}/share_links"
tags: ["Customer links"]
---

# List the customer links of a shipment

`GET /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 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.

## Path parameters

- `shipment_id` string, required

## Query parameters

- `limit` integer
- `starting_after` string

## Headers

- `Trackberry-Version` string

## Response `200`

A page of customer links.

- object: The envelope every list endpoint returns.
  - `object` 'list', required: Always `list`.
  - `data` object[], required: The items of this page, in the order the endpoint documents. Each item is an object of the kind the endpoint returns.
    - `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.
  - `has_more` boolean, required: True when more items exist after this page. Pass the last item's `id` as `starting_after` to fetch them. Always false for unpaged lists.

## Other responses

- `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)