Download a purchased label's file and cancel a label that is no longer needed. If a label purchase returns `202` or its response is lost, read the order for the outcome — repeating the same effective purchase request replays that purchase operation instead of buying a second label. Cancellation carries no equivalent guarantee: it declares no idempotency key and no replay contract, so do not blindly repeat a cancellation whose outcome is unclear.
Operations
GET /api/v1/labels/{labelId}/download
Download label
Downloads the shipping label file by label ID. When `format` is omitted, the account's preferred LabelPrintingTechnology is used, falling back to PDF. PDF and ZPL files can be generated asynchronously, so the endpoint may return 202 while the requested file is still being processed. Errors come from two producers, and which one answered decides the shape. The endpoint's own responses — the pending 202 and its 404, 409, 500 and 503 failures — are a flat JSON error object (`code`, `description`, `category`, `metadata`). Failures raised around the endpoint — authentication, `X-SubAccount-Id` validation, request binding and unexpected server errors — use the standard `{success, data, errors}` JSON envelope. 404, 409 and 500 have both producers and are published as `oneOf` of the two; 400 and 401 are always the envelope, 202 and 503 always the flat object. 403 is the one response with no body at all: authorization refuses a non-integration token before anything can write one.
Authentication: JWTBearerAuth, Bearer http, JWT
Parameters
| Name | In | Type | Required | Description |
|---|
labelId | path | string (guid) | required | Example: f6c7d8e9-0a1b-4c2d-8e3f-4a5b6c7d8e9f |
|---|
format | query | LabelFormat | optional | Label file format: PDF (1), ZPL300DPI (2), ZPL203DPI (3), ZPL600DPI (4). When omitted, falls back to the account's LabelPrintingTechnology, then to PDF. Example: 1 |
|---|
X-SubAccount-Id | header | string (uuid) | optional | Optional but has no effect on this operation: the label is looked up by account only, regardless of which sub-account it (or its shipment) is tagged with or which sub-account this header specifies. Example: 3a7d9e21-6b48-4c15-9f2e-7d0c5b83a614 |
|---|
Responses
| Status | Description | Body |
|---|
200 | Label file | application/pdf — string (binary)
application/zpl — string (binary)
|
|---|
202 | Requested label file is pending or still being generated | application/json — LabelFileError
|
|---|
400 | The request could not be read as sent — for example an `X-SubAccount-Id` header that is not a GUID. | application/json — ErrorEnvelope
|
|---|
401 | Not authenticated | application/json — ErrorEnvelope
|
|---|
403 | Authenticated, but not with an Open API integration token. Sent without a body. | No response body. |
|---|
404 | Label not found or requested format not generated | application/json — object
|
|---|
409 | Label generation conflicts with current state | application/json — object
|
|---|
500 | Label generation failed or internal server error | application/json — object
|
|---|
503 | The carrier is temporarily unavailable. Nothing to correct; retry later | application/json — LabelFileError
|
|---|
DELETE /api/v1/labels/{labelId}
Cancel label
Cancels a shipping label by label ID.
Authentication: JWTBearerAuth, Bearer http, JWT
Parameters
| Name | In | Type | Required | Description |
|---|
labelId | path | string (guid) | required | Example: f6c7d8e9-0a1b-4c2d-8e3f-4a5b6c7d8e9f |
|---|
X-SubAccount-Id | header | string (uuid) | optional | Optional but has no effect on this operation: the label is looked up and cancelled by account only, regardless of which sub-account it (or its shipment) is tagged with or which sub-account this header specifies. Example: 3a7d9e21-6b48-4c15-9f2e-7d0c5b83a614 |
|---|
Responses
| Status | Description | Body |
|---|
200 | Label canceled successfully | application/json — CancelLabelResponseEnvelope
|
|---|
400 | Invalid request | application/json — ErrorEnvelope
|
|---|
401 | Not authenticated | application/json — ErrorEnvelope
|
|---|
403 | Authenticated, but not with an Open API integration token. Sent without a body. | No response body. |
|---|
404 | The label, its shipment, or its carrier does not exist for your account | application/json — ErrorEnvelope
|
|---|
409 | The sub-account given in `X-SubAccount-Id` is not active. | application/json — ErrorEnvelope
|
|---|
422 | The label cannot be cancelled as it stands — its shipment has no tracking code to cancel against | application/json — ErrorEnvelope
|
|---|
500 | The request could not be completed because of an unexpected server-side failure. | application/json — ErrorEnvelope
|
|---|
Schemas
The public schemas the operations above reference. Each is listed once; a type name in the tables above links to its fields here.ApiError
One thing that went wrong.
| Field | Type | Required | Description |
|---|
code | string | required | Machine-readable error identifier, dotted and stable — for example Order.NotFound. Branch
on this rather than on message. |
|---|
message | string | required | Readable explanation of the failure. Wording may change; do not parse it. |
|---|
metaData | object nullable | optional | Extra detail about this particular failure. Its shape depends on code. |
|---|
CancelLabelResponse
The outcome of cancelling a label.
| Field | Type | Required | Description |
|---|
isSuccess | boolean | required | Whether the carrier accepted the cancellation. A cancelled label can no longer be
downloaded. |
|---|
CancelLabelResponseEnvelope
The envelope every JSON operation answers with: a success flag and either a result or errors.
| Field | Type | Required | Description |
|---|
data | CancelLabelResponse nullable | required | The operation's result. Absent when the call failed. |
|---|
errors | ApiError[] nullable | required | What went wrong. Absent when the call succeeded. |
|---|
success | boolean | required | Whether the operation succeeded. When false, read errors. |
|---|
ErrorEnvelope
The envelope every JSON operation answers with: a success flag and either a result or errors.
| Field | Type | Required | Description |
|---|
data | object nullable | required | The operation's result. Absent when the call failed. |
|---|
errors | ApiError[] | required | What went wrong. Absent when the call succeeded. |
|---|
success | boolean | required | Whether the operation succeeded. When false, read errors. |
|---|
LabelFileError
The flat error body the label file operations produce themselves. A file download is not a JSON
operation, so its own failures are reported flat rather than inside the success/errors envelope
the JSON operations use. Failures raised around the endpoint — authentication, sub-account
validation, request binding, unexpected server errors — still use that envelope, so a status can
be published as either shape.
| Field | Type | Required | Description |
|---|
category | string | required | Broad class the failure falls into, which is what the HTTP status is derived from — for example
Validation, NotFound, Conflict or Upstream. Allowed values: General, Validation, Authorization, NotFound, Conflict, Infrastructure, Upstream |
|---|
code | string | required | Machine-readable error identifier, dotted and stable — for example Label.Processing. Branch
on this rather than on description. |
|---|
description | string | required | Readable explanation of the failure. Wording may change; do not parse it. |
|---|
metadata | object nullable | required | Extra detail about this particular failure. Its shape depends on code. |
|---|
LabelFormat
Label file format. ZPL members are resolution-specific: a label is generated and stored
separately for each supported printer resolution. Published as the numeric value:
1 = Pdf.
2 = Zpl300Dpi.
3 = Zpl203Dpi.
4 = Zpl600Dpi.
2 and 3 are deliberately not in resolution order: 2 predates the split and already meant 300 dpi.
Allowed values: 1, 2, 3, 4
Type integer.