Skip to main content

Select a Rate

Outcome​

You will inspect the Rates returned for a Shipment, choose one using your application's own criteria, and pass its identifier through rate.id to Label purchase. After a successful response, retain postageLabel.id as the returned Label identifier.

When to use​

Use this guide after either public Rate path:

When not to use​

This guide does not define cheapest, best, or fastest recommendation logic, carrier-specific SLA logic, guaranteed transit, Rate validity or expiration, financial reconciliation, or retry safety after an ambiguous purchase outcome. It does not cover tracking or webhook flows.

Prerequisites​

Before selecting a Rate, have:

  • valid credentials and token;
  • the intended Account context or an authorized optional Sub-account context;
  • an existing Shipment, or a create-and-rate response containing Rates;
  • valid Address and Parcel data;
  • applicable account setup.

Packed is not a prerequisite for Rate retrieval or Label purchase.

Conceptual explanation​

A Rate is a current Shipment pricing/service result. Selection is an application decision, not a Mailhub state mutation: choose one returned Rate identifier only for the purchase workflow currently being processed. The API Reference remains the complete source for all Rate and Label schemas.

End-to-end flow​

Shipment
  -> returned Rates
  -> application evaluates verified public fields
  -> client selects one returned Rate
  -> submit selected Rate identifier as rate.id
  -> receive postageLabel.id

Use Label purchase after selection. Use Download Label separately when you need the documented file-retrieval operation.

Request and response examples​

Returned Rate excerpt​

{
  "id": "<returned Rate identifier>",
  "rate": 0,
  "currency": "<returned currency>",
  "carrier": "<returned carrier value>",
  "serviceCode": "<returned service code>",
  "serviceName": "<returned service name>"
}

Label purchase request​

{
  "rate": {
    "id": "<selected Rate identifier>"
  }
}

Successful Label-purchase response​

{
  "postageLabel": {
    "id": "<returned Label identifier>"
  }
}

How to compare returned Rates​

Your application may compare fields that are useful to its own requirements:

  • rate is a returned price value.
  • currency is the returned value associated with rate.
  • carrier, serviceCode, and serviceName are returned public values.

The public contract does not define these returned carrier or service values as stable enums or immutable business keys. It also does not define a universal scoring algorithm, the numeric units or tax treatment of rate, a final charged amount, or carrier-specific availability, billing, or transit meaning.

Selection rules and non-rules​

Select only an identifier from the Rate results returned for the Shipment workflow you are currently processing.

Do not infer cheapest, best, fastest, recommended, or otherwise ranked meaning from the response order.

The current public contract does not define a Rate validity period. Selecting a Rate is an application decision; the public contract does not define a separate Rate-selection resource or mutation. Do not invent persistence behavior for selected Rates.

Failure and ambiguity handling​

For standard Order creation, inspect the actual public response and error envelope when there are no usable Rate results. For Create an Order with Rates, the documented 422 response can represent an invalid Order or a case where no carrier could rate the Shipment. Validate current request data and the intended Account or optional Sub-account scope before deciding what your application should do next.

For documented Label-purchase errors, inspect the actual public response and error envelope. After a timeout or lost response, resend the same purchase request within a bounded budget or read the Order — the same request is recognized server-side and replays its outcome rather than buying a second Label. A request that is not the same purchase is refused with 409. See Buy a Label.

See Rate Errors and Label Errors for the documented error responses.

Production guidance​

  • Store the chosen returned Rate identifier only for the current purchase workflow.
  • Retain postageLabel.id from a successful response.
  • Log request context without exposing credentials.
  • Do not depend on response ordering; re-evaluate your application criteria when returned Rates differ.
  • Keep schema handling tolerant of optional fields and use the API Reference for complete schemas.

Next steps​