ship

Buy a shipping label

Buy the outbound shipping label for one quote_id, with confirm true; CONSEQUENTIAL -- it charges that quote's price_cents in credits and buys real postage -- and returns the printable label_url (PDF) and the tracking number, plus a USPS QR code if qr_code is true. Sensitive write: it requires the human's approval of that quote's carrier, delivery days and price. A short balance returns 402 with a topup_url. A replay with the same idempotency_key returns the original label and never buys twice.

post/v1/labels

Request

  • Base URL: https://api.noerrands.com/c/ship
  • URL: https://api.noerrands.com/c/ship/v1/labels
  • Auth: HTTP bearer

Request body

quote_idstring required

One quote_id from get_shipping_rates, the option the human approved.

confirmtrue required

Must be true. Set it only after the human approved this exact action and price.

qr_codeboolean

USPS only: also return a QR code the human can show at any post office instead of printing the label.

idempotency_keystring

Use one key per human request. Replays within 24 hours return the original result instead of buying twice.

Response

Success.

shipment_idstring required

Opaque id, "sh_...". Use it with get_shipment.

kind'outbound' | 'return' required
status'unknown' | 'pre_transit' | 'in_transit' | 'out_for_delivery' | 'delivered' | 'available_for_pickup' | 'return_to_sender' | 'failure' | 'cancelled' | 'error' required

The carrier's tracking status. pre_transit means the label exists and nothing has been scanned yet.

carrierstring required
servicestring required
tracking_codestring required
label_urlstring uri

The printable PDF label. Gone after the retention window.

qr_code_urlstring uri

USPS QR code image. The human shows it at a post office counter and the clerk prints the label.

tracking_urlstring uri

The carrier's public tracking page.

est_delivery_datestring
credits_charged_centsinteger required

Net credits this label cost: zero once a refund has been confirmed.

refund_status'none' | 'submitted' | 'refunded' | 'rejected' required

none, or after void_label: submitted (waiting on the carrier), refunded (credits are back), rejected (the label was used or too old).

created_atstring date-time required
balance_centsinteger required

General credit left after the charge.

Changes

No recorded changes to this operation across all 1 revision of this API.