postsale labels

Buy labels one shipment at a time, reprint an existing label, and void a label you no longer need.

Updated September 3, 20262 min readPostsale CLI

Label purchase, void, and reprint.

Deep docs: Shipping, labels, rates · Safety

Subcommands

Command	Safety	Notes
`purchase`	money-moving	`--shipment-id` (one or more), label type; requires `--yes`
`void`	money-moving	requires `--yes`
`reprint <shipment_id>`	read	Re-fetch existing label PDF URL; no charge. CLI-only (not in schema list). Optional `--output` to download PDF

bash

postsale labels purchase --label-type pdf --yes \
  --shipment-id 019a4f2c-7b31-7d5e-9f04-2c8e6b1a4d77 \
  019a4f2c-7b31-7d5e-9f04-2c8e6b1a4d78
postsale labels void --shipment-id 019a4f2c-7b31-7d5e-9f04-2c8e6b1a4d77 --yes
postsale labels reprint <shipment_id>
postsale labels reprint <shipment_id> --output ./label.pdf

Label types: pdf (default), jpeg, png, zpl, epl. purchase and void accept --idempotency-key. Verify flags with postsale labels purchase --help.

purchase buys through POST /v2/shipment/labels, which takes one shipment per request: the command sends one request per id, in the order given, and prints a single { labels, errors } result. Shipment ids must be UUIDs (the id of a shipment, not an order number) and at most 10 per call; both are checked before anything is bought. With several ids the idempotency key gets a -<n> suffix per shipment, listed in _cli_meta.idempotency_keys. If a request fails part-way, what was bought before it stays bought and is printed with _cli_meta.partial: true before the error. A shipment with an entry in errors has no label. The backend prices each label from the shipment's own rate selection at purchase time.

With POSTSALE_TEST_LABEL_MODE set, purchase reads every shipment before the first request and refuses the whole batch (test_label_required, exit 64) unless each is a test shipment; the result then carries _cli_meta.test_label_verified, the list of shipment ids the CLI verified. See the safety model.