Shiptheory: shipment data and service selection
Separate the shipment you describe, the service selected by rules, and the carrier result before treating a label request as fulfillment.
- Shipment description
- Service selection
- Booking and label result
Investigation question
What should a shipping integration consider complete: sending shipment data, selecting a service, receiving a label or handing a parcel to a carrier? Shiptheory’s public interface exposes several of these concerns, which should remain distinct in a client’s state model.
Observed
Shiptheory’s developer documentation covers shipment creation and lookup, labels, available delivery services and package sizes. Shipping rules provide a separate selection layer over the shipment description. Addresses, parcels and item information describe what is being shipped; a carrier service describes how it is intended to move. A label is an artifact associated with a booking outcome. It is not physical proof that the parcel was packed, collected or delivered. Those later events need their own evidence. The API surface is useful precisely because a client can inspect more than one stage instead of representing everything as a single “shipped” flag.
Inferred
Model the request and its outcome separately. An accepted shipment description can still encounter a service constraint, a carrier validation problem or a later operational failure. Changing a rule may change a future service decision without changing the order’s commercial identity. This suggests keeping stable shipment identity, selected service and returned carrier artifacts as separate fields. A retry should be reconciled against the existing shipment before creating a fresh booking, especially if the first response was lost. This is a recommended client discipline, not a claim of undocumented idempotency guarantees.
Unknown & limitations
This article does not establish carrier-specific eligibility, label charging, cancellation or refund semantics. It does not equate a label with carrier collection or delivery. Exact retry guarantees and asynchronous result timing must come from the relevant documented operation and direct testing. No customer address, commercial shipment, carrier credentials or private fulfillment data is included.
Domain & data models
Conceptual sequence: shipment description → rule/service selection → carrier booking result → label and tracking evidence. An order can require more than one parcel or shipment, so an order identifier alone need not identify a unique carrier artifact. A client should preserve the reference that distinguishes the individual shipment.
Workflows & state machines
Illustrative scenario: one order is split into two physical shipments. Each shipment needs its own reference and booking result even if both display the same customer order number. If the network times out after the first request, the safe diagnostic question is whether that shipment already exists—not whether the order has any tracking number. A controlled verification would inspect available services, submit a test shipment through an authorized test route, retrieve the resulting record and compare its selected service and label state. A second test would use an intentionally ineligible service condition and observe the returned failure. No such live booking was performed for this publication.