Manifests

Use a Manifest to hand off a batch of shipments to a carrier in a single pickup. A manifest is one record listing all the shipments going to the same carrier that day. In Carriyo, manifests are optional. Whether they're useful depends on your carrier and volume:

• When the carrier supports manifests, Carriyo sends the manifest details to the carrier on shipping (typically the driver scans one manifest barcode and takes everything on the list at once).
• When the carrier doesn't support manifests, the manifest stays local to Carriyo and acts as a cross-check document: a printed list the warehouse can use to confirm everything that should physically leave with the driver.

shipped vs in_transit

Marking a shipment as shipped is optional in Carriyo. The two adjacent statuses have different sources:

• shipped: the merchant's declaration that a shipment has left the warehouse. When the merchant marks a shipment as shipped (directly or by shipping the manifest it belongs to), the status moves to shipped immediately.
• in_transit: the carrier's declaration that the shipment is in its network. Triggered by the carrier's first scan event.

Marking a manifest as shipped flips every shipment in the manifest to shipped in one operation. From there each shipment moves on independently as carrier scans arrive.

When manifests matter

• High volume per carrier. A warehouse shipping 50+ parcels a day with one carrier saves time on a single handoff vs 50.
• Carriers that require it. Some carriers won't accept ad-hoc collection requests at scale. They expect a manifest at the end of each pickup window.
• Compliance and reconciliation. Manifests are auditable documents. Useful for tracing what was actually handed off, vs what's still in the warehouse.

For low-volume or ad-hoc shipping, manifests can usually be skipped entirely.

The model

A Manifest is an object that:

• Belongs to one carrier account.
• Lists multiple Shipments by id and tracking number.
• Has a status (draft, ready-to-ship, shipped, cancelled).
• Carries a Carriyo-generated manifest document (PDF) for the driver and warehouse to use. When the carrier also produces its own manifest artifact during the carrier dispatch step, that's stored alongside the Carriyo document.
• Has a creation timestamp and (after shipping) a shipped timestamp.

Shipments are added to a draft manifest after they're booked. The manifest is then marked ready to ship (locking the list, no more shipments can be added or removed) and shipped (sent to the carrier and flipping every contained shipment's status to shipped).

Manifest vs scheduled pickup

Two related but distinct concepts:

• Manifest. A batched handover list of multiple shipments. Generates a PDF for the driver.
• Scheduled pickup. A time window when the carrier picks up. Manifests can ride on a scheduled pickup, but the two aren't the same thing: a manifest is a document, a scheduled pickup is an event.

A daily scheduled pickup with a daily manifest is the typical high-volume pattern. The carrier arrives in the configured window, scans the day's manifest, takes the parcels.

Auto-create vs explicit

Some carriers / carrier account configurations auto-generate a daily manifest as shipments are booked. Others require explicit creation via API or Dashboard. Two patterns:

• Auto-create per day per carrier. Each shipment booked is added to the open manifest for its carrier account. The manifest is shipped at a configured time and produces the PDF.
• On-demand. You call POST /manifests with a list of shipment ids when you're ready to hand off. Useful for multi-pickup-per-day flows.

The carrier-account configuration determines which mode applies.

Things that go wrong

• Shipments missing from a manifest. A booked shipment that wasn't added to the day's manifest (different carrier, different account, missed window) won't get the shipped flip when the manifest ships. Spotting these is why aging reports exist.
• Manifest is shipped before all expected shipments are booked. If a draft shipment is "supposed" to be on today's manifest but never gets confirmed, the manifest ships without it. Either confirm earlier or run a tighter manifest cadence.
• Driver scans but doesn't take. A driver can scan a manifest and physically take fewer parcels than listed. Status updates from the carrier reflect what was actually scanned into the carrier's network. Reconcile against the manifest list to catch discrepancies.

How it fits with other modules

• Shipping. Manifests are part of the shipping execution flow.
• Carrier configuration. Manifest behavior (auto-create cadence, ship time) is per-carrier-account configuration.