Java bridge reference
This older, unversioned documentation link describes the three Java API-key bridge endpoints. It is not the original V1 JWT API or the new V2 resource API. Choose the version used by your integration.
Developer APIPurchase a label
/v1/shipping/buyPermissions: labels.buy
Request fields
shippingAccountId, rateId | The shipping account and rate identifiers returned by the selected rate. |
|---|---|
rateRequest | The shipment request used to obtain the rate, including addresses and packages. |
clientReferenceId | Your stable reference for this purchase. Reuse it when retrying the same purchase; use a different reference for a new purchase. |
Response
Returns shipmentId, trackingNumber, shippingCost, insuranceCost, currency and available labelBase64 / labelMimeType. In this legacy response, shipmentId is the provider's identifier and shippingCost / insuranceCost are provider costs, not a receipt for the amount charged to your wallet. Multi-package results can include packages and forms. A replay of an already successful purchase returns that purchase without label bytes; retain the original label response.
Responses use { code, message, data }. Check both the HTTP status and response code; provider errors are not successful purchases.
Important notes
This operation purchases a real label and can charge the account. Keep the same clientReferenceId after a timeout; do not start another purchase with a new reference while the first result is uncertain. If you cannot recover the label, contact support before purchasing again. A label response alone does not confirm wallet settlement.