Skip to main content

Public Object Model

What the public model represents​

The public API helps an application create and manage Orders and the Shipments inside them. Credentials establish an Account scope; an optional Sub-account scope can narrow a supported request. Address and Parcel values travel with an Order and Shipment rather than being separately managed resources.

Canonical relationships​

The client retains the identifiers returned by the API. A client-selected Rate identifier is supplied when purchasing a Label; it is not a separate operation in this public model.

The model, in full:

  • An API key is exchanged for an access token and a refresh token.
  • An Account owns everything. A Sub-account is an optional scope inside that Account; supplied at creation, it tags the new Order and its Shipments, which remain Account-owned.
  • An Order (orderId) carries origin and destination Address data as embedded values and contains one or more Shipments (shipmentId), each carrying Parcel data as an embedded value.
  • shipmentId requests Rate results. A Rate is a decision result, and your application selects one rate.id from the set returned.
  • That client-selected Rate identifier buys a Label (labelId). A Shipment has at most one active Label.
  • A Label renders as one binary Label asset per printable format (PDF or ZPL). The Label record can exist before its file does, so the asset moves from processing to completed.
  • There are two ways to reach the file: the authenticated download operation GET /api/v1/labels/{labelId}/download, which uses labelId; or the time-limited links the Order carries, which need no API token and therefore must be treated as credentials. When a link expires, re-read the Order for a fresh one.

How to classify the model​

CategoryPublic concept
CredentialsAPI key, access token, refresh token
Request scopesAccount and optional Sub-account
ResourcesOrder and Shipment
Embedded valuesOrigin Address data, destination Address data, and Parcel data
Decision resultsRate results
Binary representationLabel asset
Cross-cutting resultErrors returned by an operation

What is not a current public resource​

The current public model does not expose Merchant, Postage Account, Tracker/Tracking Event, Webhook subscription, public Carrier Account management, or standalone Address or Parcel CRUD. See the current integration scope for the reviewed 12-operation boundary.

Identifier flow​

  1. Create an Order and retain its orderId and each shipmentId.
  2. Use orderId with Get an Order or update Order status.
  3. Use shipmentId with get Rate results.
  4. Select a returned Rate identifier, then use it with create a Label.
  5. Retain postageLabel.id and use it as labelId for the Label workflows.

Short previews of Rates and Labels​

Rates explain the returned Rate result and its bounded client-selected identifier handoff. Carrier Availability explains the public-safe readiness boundaries. Labels and Order Lifecycle provide the bounded operation and Order-status guidance.

Continue learning​