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 relationship diagram​

API key -> access token + refresh token

Account scope -> optional Sub-account scope -> Order
    -> origin/destination Address data -> Shipment -> Parcel data
    -> Rate results -> client-selected Rate identifier -> Label
    -> binary Label asset

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.

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​