# Manifest selected orders by API
URL: https://support.starshipit.com/articles/1792426266569-manifest-selected-orders-by-api
Canonical: https://support.starshipit.com/articles/1792426266569-manifest-selected-orders-by-api
Markdown: https://support.starshipit.com/articles/1792426266569-manifest-selected-orders-by-api.md
Updated: 2026-10-19

> For the complete documentation index, see [llms.txt](https://support.starshipit.com/llms.txt).

> Manifest a selected batch across supported couriers, check reports and partial failures, and avoid retrying completed shipments.

Use the Starshipit API to manifest a specific set of printed orders, including orders from different supported couriers. Check the result for every courier before retrying a batch that only partly succeeds.

## Before you begin

- Set up the authentication headers described in [Starshipit API fundamentals](/articles/14700000001018-starshipit-api-fundamentals).
- Obtain the numeric Starshipit order IDs for the account your API key accesses. Order numbers and tracking numbers are not substitutes for `order_ids`.
- Confirm the selected orders have labels, an assigned courier and a status eligible for that courier's manifesting workflow.
- Check your [courier's manifesting requirements](/articles/360001997955-manifesting-faq). A mixed batch does not make an unsupported courier or shipment eligible, and a manifest does not confirm collection.

## Submit the selected orders

Send a request to [POST /api/orders/manifest](/developers/api-reference/starshipit#endpoint-shipments-post-api-orders-manifest-manifest-orders).

| Field | What to send |
| --- | --- |
| `order_ids` | A non-empty array of numeric order IDs accessible to the authenticated account. |
| `manifest_all` | Omit this field or set it to `false` to process only the selected IDs. |
| `awb_label_count` | Optional count for couriers that use it, including DHL Express Globalmail and Deutsche Post. It is passed to each selected courier group. |

Repeated IDs are processed once. If an ID is missing or inaccessible in the account, Starshipit rejects the selection before starting any courier operation. Unselected awaiting-dispatch orders are not added to the batch.

Starshipit processes the selected orders in courier groups. Each courier's booking, eligibility and order-status rules still apply.

## Read the response and reports

For a selection containing more than one courier, check all of these fields:

| Field | How to interpret it |
| --- | --- |
| `success` | `true` when every courier group completes without a reported error. |
| `errors` | Failed courier groups and their original selected order IDs. Other groups are still attempted after a group reports an error. |
| `pdf` | Available PDF reports combined into one base64-encoded PDF. Decode it before opening or printing it. |
| `label_type` | `ManifestReport` when a PDF is returned. |

A successful courier operation can return no PDF. Non-PDF files, such as NZ Post CSV manifests, are not converted into the combined PDF; retrieve them from manifest history. If no group returns a PDF, `pdf` and `label_type` remain unset.

A PDF can be returned alongside errors. Its presence does not prove that every selected order was manifested.

## Check a partial failure before retrying

Completed courier operations remain completed when another group fails.

1. Read each entry in `errors` to identify the affected courier and selected order IDs.
2. Check the current status and manifest history of those orders in Starshipit. A group can contain both completed and unsuccessful orders.
3. Keep any available reports from completed operations.
4. Correct the reported problem, then retry only orders that still need manifesting.

Do not resubmit the whole batch solely because `success` is `false`. You could repeat an operation that the courier has already accepted.

## Verify the integration

Use an approved test account and eligible test shipments before sending production manifests. Select orders from at least two configured couriers and leave another eligible order unselected.

Confirm that the available PDF opens, the selected orders have the expected courier-specific status, and the unselected order is unchanged. Also check your integration handles a successful result without a PDF and a partial failure without automatically repeating completed operations.

## FAQs

<!-- faq:start -->

<!-- faq:question -->Does this change manifest-all or single-courier requests?<!-- /faq:question -->

Those requests retain their existing behaviour. `manifest_all: true` uses the existing awaiting-dispatch selection and limit, so it is a different workflow from an explicitly selected batch. Always inspect `errors`: the existing single-courier and manifest-all responses can return `success: true` alongside errors when a PDF is available.

<!-- faq:question -->Does this also book a pickup?<!-- /faq:question -->

Pickup behaviour depends on the courier's existing manifesting workflow. Check [Book a courier pickup](/articles/360000133996-book-a-courier-pickup) and the courier's guide; do not assume a successful manifest means a pickup is booked or the freight has been collected.

<!-- faq:end -->