Purchase a label

POST Purchase

Purchase a draft label.

Wallet purchase: The amount is deducted from your atoship wallet. rate in the response = what you paid.

BYOCA purchase: When the draft has a carrier_account_id, the shipment is created via your own carrier credentials. rate in the response = the carrier's quoted rate. Your atoship wallet is NOT charged for the shipment cost — your carrier account (or the third party you specified via billing) is billed by the carrier directly.

Third-party billing (UPS only): Set billing.payer = "third_party" with the third party's UPS account number, country, and postal code. UPS will bill that account instead of yours. This is the standard pattern for ERPNext/ERP integrations where shipping costs flow back to a customer's own UPS account.

Authorization: By submitting a third-party billing request, you confirm the third party has authorized you to bill their UPS account. atoship logs the authorization timestamp for audit/dispute resolution.

Parameters

Path Parameters

id string Required

Label ID from POST /v1/labels. Must be in draft status.

Request Body (optional)

customs object

International shipments only. Overrides the customs data stored on the draft; anything you omit falls back to that stored value. This is the last point at which customs can be corrected — an invalid description is rejected, not guessed.

description: Plain-language contents. Generic words ("gift", "sample") are rejected by the carrier.
value: Declared customs value per item
contents_type: Defaults to merchandise
quantity: Defaults to 1
hs_code: HS tariff number
country_of_origin: 2-letter ISO. Defaults to US
tax_id: Recipient tax id, where the destination requires one
tax_id_type: Type of the recipient tax id

Billing

Billing (payer / accountNumber / countryCode / postalCode) is set when the draft is created, on POST /v1/labels, and cannot be changed here. It is tied to the BYOCA carrier account chosen for the draft, so it is fixed once that draft exists.

Returns

200 Label purchased. Returns the tracking number, the final rate and label_url.

400 INVALID_STATE — the label is not a draft (already purchased, or voided).
NO_RATES — no rate could be obtained for this shipment.
RATE_NOT_FOUND — the quoted rate expired before purchase.
ROUTING_FAILED / PURCHASE_FAILED — the carrier declined the buy.
INSURANCE_NOT_ALLOWED / INSURANCE_NOT_AVAILABLE / INSURANCE_OVER_MAX — the requested coverage is not available on this service.
SERVICE_NOT_REGISTERED_FOR_ORIGIN / ORIGIN_NOT_REGISTERED / ORIGIN_ACCOUNT_UNUSABLE — this origin is not registered for the chosen service.
COMPLIANCE_NOT_SUPPORTED — the shipment cannot be shipped compliantly on this service.
ENTITLEMENT_CHECK_FAILED — entitlement could not be resolved; the purchase is refused rather than guessed.

401 Authentication required

402 INSUFFICIENT_FUNDS — the wallet balance does not cover the label.

403 FORBIDDEN — the label belongs to another account.
SHIPPING_HELD — shipping is on hold for this organization.
contract_required — a contract must be in place before this service can be bought.

404 NOT_FOUND — no such label.

500 Internal error

Labels