Shipments and labels
Quote, create, update and buy a label for a shipment, and cancel it before pickup.
A label is bought in steps: you create a shipment, choose one of its rates, and buy it. Until you buy, nothing is charged and the shipment can still change.
Quote before you create
To show prices before you store anything, send the shipment you would create to the rates endpoint. It answers with every service available and its price.
Create the shipment
accountId accepts the account uid, its account number (CU…) or its external account number. Set externalReferenceCode to your own order number to match the shipment to your order.
The answer is the Shipment object. Its parcel_rates lists the services the shipment can be sent with; each rate has a uid.
Update it
PATCH changes only the fields you send. Send the whole sender, recipient or parcels when you change one of them. The rates are calculated again, so read the new parcel_rates from the answer: an old rate uid may no longer apply.
Buy the label
For each shipment, send its uid as shipmentId and the chosen rate's uid as rateId, grouped by how the parcels reach the carrier:
dropoff: you take them to a drop-off point.pickup: the carrier collects them; sendpickupDateandpickupTime.
How it is paid
The purchase is booked in your WeShipYou wallet. Your balance is used first; only the remainder is charged to paymentMethod, either "credit_line" (accounts with a credit line) or a saved card as { "paymentMethodId": "pm_…" }. You can leave paymentMethod out when the balance covers everything.
Reading the answer
The answer has one entry per batch: fulfilled when every label of the batch was bought, rejected with a reason otherwise. Read each shipment (GET /shipments/{shipmentId}) for its tracking number in label.trackingNumber.
Cancel a label
A label the carrier has not picked up yet can be cancelled with its tracking number. What you paid for it is credited back to your WeShipYou wallet. A 409 means the shipment changed state while cancelling: read it again and retry if it can still be cancelled.
Delete a shipment
A shipment that has no label yet (state created) can be deleted. To cancel one whose label is bought, cancel the label.