Shipping

Carriyo books shipments with carriers, generates labels and manifests, and tracks parcels through to delivery. Shipping is the capability most Carriyo customers use first, often before they adopt any other module. You don't need Orders in Carriyo to create a shipment; the shipping endpoints stand on their own.

What Carriyo's shipping does

• Booking and re-booking. Submit a shipment and Carriyo books it with the right carrier: the one you specify, or the one your configured rules pick when you leave it open.
• Label and document generation. Standard PDF / ZPL plus carrier-specific templates and QR codes. Commercial invoices for cross-border. Re-generate when needed.
• Pickup and delivery scheduling. Set or revise the pickup collection window and the delivery slot, per shipment or as a daily standing schedule.
• Manifest handoff. End-of-day manifest creation for carriers that need a single batched handover.
• Consistent status tracking. Carriers report status differently. Carriyo normalizes those into one consistent set of statuses you can build against.
• Reprocessing and reassignment. When a booking errors, reprocess with edits or reassign to a different carrier without starting from scratch.

The model

A Shipment is the central object. It holds the pickup and dropoff parties, the parcels, the items, payment details (currency, COD), and a reference to the order. It moves through a lifecycle of statuses: draft, booked, ready_to_ship, shipped, in_transit, out_for_delivery, delivered. Branching paths handle errors, cancellations, returns, and reverse flows.

The shipment is bound to one carrier account at booking time. Three things decide which:

• The shipment data itself: origin, destination, weight, items, custom attributes.
• The carrier account configuration: its costing profile, capacity profile, network profile, and merchant access.
• Shipping rules: the engine that picks among eligible accounts. See Automation.

A shipment can include multiple parcels (the physical packages) and multiple items (the line content). Customs treats items as the unit of declaration for cross-border; carriers compute rates per parcel.

Forward and reverse

Every shipment is either FORWARD (merchant → customer) or REVERSE (customer → merchant, typically a return). The same Shipment object handles both. You can configure a carrier account for one direction or both, and shipping rules can target either direction on its own.

The Shipping API only handles the carrier booking part of a return. For the full reverse-logistics workflow (return requests, approvals, refunds), see Returns.

Integration shapes

Shipments enter Carriyo in one of three shapes, picked by how much of the booking flow you want Carriyo to own.

Draft → confirm

Carriyo creates: Draft Shipment → Confirmed Shipment (booked + label).

Create a draft Shipment in Carriyo as soon as the order is placed upstream. Confirm it later when the parcel is ready; Carriyo books with the carrier, generates the label, and starts tracking. The draft makes the shipment visible in Carriyo immediately, before any booking happens.

The advantage is early visibility. The customer-facing tracking page is live the moment the draft is created, so shoppers can land on it right after checkout. Internally, you can monitor order-processing SLAs from the moment the draft exists, and flag any orders that haven't been processed in time.

Best for: clients who want live customer-facing tracking from checkout and order-processing SLA monitoring in Carriyo, without pushing Orders into the system.

Confirmed (just-in-time)

Carriyo creates: Confirmed Shipment (booked + label) directly.

Skip the draft step. Create the confirmed Shipment when you're ready to generate a label. Carriyo books with the carrier, returns the label, tracks the parcel, and runs post-purchase.

Best for: the simplest integration that uses Carriyo's full shipping and tracking functionality.

Pre-booked

Carriyo creates: a pre-booked shipment record. No carrier booking.

You've already booked the shipment elsewhere and you have the carrier name and tracking number. Push the Shipment into Carriyo for tracking and the post-purchase experience only. Carriyo doesn't re-book.

Best for: clients with an existing fulfillment and shipping operation who want only the customer-facing tracking and post-purchase layer.

Returns

Returns layer on top of any shape. A return request always references the originating order via partner_order_reference. Carriyo uses that reference to locate the associated shipments, whether or not an Order entity exists in Carriyo.

Idempotency

Idempotency on POST /shipments is keyed on (merchant, partner_shipment_reference), your external reference for the shipment. Send the same reference twice and you get the existing shipment record back, not a duplicate. Retries are safe.

How it fits with other modules

• Orders. Orders ingest the customer's request; shipments execute it. One order can produce one shipment (most common), several shipments (multi-warehouse splits), or no shipment (cancelled before fulfillment).
• Checkout. Checkout-time rates and delivery options use the same carrier configuration as booking, so what the shopper sees is what they get.
• Automation. The rules engine that picks the carrier account at booking time.
• Carrier configuration. The accounts and profiles that describe which carriers can do what.
• Post-purchase CX. The tracking pages, notifications, and feedback the customer sees after checkout. All of it reacts to events on the shipment.
• Webhooks. The real-time feed of shipment events your systems listen to.
• Data redaction. Per-shipment PII anonymization for GDPR right-to-erasure requests.