Shipping API

Create a shipment. Returns a unique shipment_id. Either name a carrier_account explicitly or let Carriyo's shipping rules pick one.

Forward vs reverse. Set entity_type to either:

• FORWARD: a normal outbound shipment from the merchant to the customer. Omit entity_type and this is what you get.
• REVERSE: a return shipment, where the customer sends items back to the merchant.

Draft, confirmed, prebooked. Three creation modes, each with different behavior against the carrier:

• Draft (?draft=true): the shipment is saved in Carriyo for visibility but is not sent to the carrier. Use this when parcel details aren't final yet. The shipment stays in draft until you call Confirm shipment.

• Confirmed (default, no ?draft query parameter): Carriyo validates the payload, assigns a carrier, and immediately submits the booking request to that carrier. The API responds with status pending straight away, without waiting for the carrier's response. The carrier's outcome (acceptance, rejection, label) arrives via webhook. If Carriyo's own validations fail, the shipment is still created, in error status with the validation errors in the response body, and the call returns 200 rather than a client error.

• Prebooked (pre_booked: true): register a shipment that was booked outside Carriyo so Carriyo can track it. Once registered, the shipment shows up alongside the rest of your shipments in operational monitoring, reporting, and the branded customer tracking experience. Carriyo does not call the carrier's booking endpoint in this mode, but it does take ownership of tracking the shipment with the carrier from this point on. Supply the existing carrier and tracking number in pre_booking_info:

  {
    "pre_booked": true,
    "pre_booking_info": {
      "input_carrier": "DHL",
      "carrier_tracking_no": "1234567890"
    }
  }
  

After booking. Once the carrier accepts the booking, the shipment status moves to booked and the carrier's tracking number is attached. A label is generated. From that point, all subsequent status changes and label updates are pushed to your webhooks; the response from this endpoint represents only the moment of submission, not the carrier's final decision.

Return a paginated list of shipments matching the search and filter parameters. The search_string parameter matches from the start of a word across carrier tracking number, order reference, shipment reference, customer name, email, and similar fields, so acme finds Acme Trading while cme finds nothing. An all-digit search_string is the exception: it also matches the end of the pickup or dropoff contact phone number, so the last few digits are enough to find a shipment. Combine it with the other filters, sort, and pagination parameters as needed.

Each request through the API counts one against the account's monthly shipment-list quota, a separate allowance from the shipment quota. The counter resets each calendar month. A request is refunded only when the search itself fails with a server error; a timeout still counts. An exhausted quota returns 429 with the limit in the message.

Return the latest shipment object, including the most up-to-date status and tracking information.

Partially update an existing shipment. Allowed when the shipment is in draft, error, or cancelled; any other status returns 400. (Cancelled shipments are editable so you can correct them before reprocessing.)

The body merges into the stored shipment as follows:

• Top-level fields you include are replaced wholesale. A top-level field you leave out keeps its current value, but one you send overwrites the stored value entirely — the merge does not reach inside it. To change a single pickup postcode you must still send the whole pickup object; any field you omit inside it is reset.
• An explicit null clears a field. carrier_account: null unassigns the carrier.
• custom_attributes and carriyo_metadata are the exceptions and merge entry by entry: add or change one without supplying the others, and set a value to null to remove it. carriyo_metadata entries are matched on name.

Every PATCH resets post_shipping_info to its draft state, keeping documents you uploaded. Changing references.partner_shipment_reference is allowed here, and is rejected when the new value already belongs to another shipment.

Fully replace a shipment. The request body overwrites the stored shipment: any field you omit is reset, including nested objects like pickup, dropoff, parcels and items. To change a few fields and leave the rest intact, use Update shipment (PATCH) instead.

Some fields survive the replacement whatever you send: tenant, merchant, entity_type, creation_date, manifest_id, version, return_request_id, fulfillment_order_id, original_promised_delivery_date, source, creation_source, update_source and the retry metadata.

Allowed in draft, error and cancelled, the same statuses as PATCH; any other status returns 400. Unlike PATCH, the body is required, and references.partner_shipment_reference cannot be changed.

Book a draft shipment for the first time, or retry booking a shipment that's currently in error status.

Eligible statuses: draft, error. For any other status that still allows re-booking (e.g. booked, cancelled, returned), use Reprocess shipment (POST /shipments/{shipment_id}/reprocess) instead.

Optional updates. The request body is optional. Supply it if you want to amend the shipment as part of confirming. Merge rules match Update shipment (PATCH):

• A top-level field you leave out keeps its value; one you send replaces the stored value wholesale, so send nested objects like pickup complete. An explicit null clears a field.
• custom_attributes and carriyo_metadata merge entry by entry. Pass null to remove one.

Booking flow. Carriyo moves the shipment to pending, assigns a carrier, and submits the booking request to that carrier. The API responds immediately with status pending, without waiting for the carrier's reply. If the carrier accepts, the status becomes booked and the tracking number is attached. If the carrier rejects, the status becomes error with the carrier's reason in post_shipping_info.error_details.

Booking outcomes and label generation are delivered via webhooks, not in the response to this call.

Re-book a shipment that's no longer in draft. Confirm shipment only handles draft and error; this endpoint covers the wider list of statuses below. For error, either endpoint works.

Eligible statuses: booked, ready_to_ship, error, cancelled, cancelled_by_carrier, out_for_collection, failed_collection_attempt, ready_for_return, return_in_transit, returned.

Typical uses:

• Retry after a transient carrier error.
• Switch carrier or routing after the original carrier cancelled or rejected the booking.
• Correct addresses, parcels, or other shipment data and re-submit.
• Re-book during a return or reverse-logistics flow.

Optional updates. The request body is optional. Supply it to amend shipment data as part of reprocessing. Merge rules match Update shipment (PATCH):

• A top-level field you leave out keeps its value; one you send replaces the stored value wholesale, so send nested objects like pickup complete. An explicit null clears a field.
• custom_attributes and carriyo_metadata merge entry by entry. Pass null to remove one.

Booking flow. Carriyo moves the shipment to pending, re-assigns a carrier (or keeps the one specified in the body), and submits the booking request. The API responds immediately as pending, without waiting for the carrier. If the carrier accepts, status becomes booked with the tracking number attached; if rejected, status becomes error with details in post_shipping_info.error_details. Subsequent booking outcomes and label updates flow through webhooks.

Mark a shipment as ready to ship. Allowed from booked, out_for_collection and failed_collection_attempt; any other status is rejected with 400.

The carrier is asked to arrange a pickup only when the body carries a full collection window (scheduled_from with scheduled_to) or sets schedule_pickup, and no pickup is already pending or arranged. Otherwise the status is set and the carrier is not contacted.

Where a pickup is requested, or the carrier has its own ready-to-ship API, the change is asynchronous: the response still carries the previous status, and ready_to_ship lands when the carrier confirms. Watch post_shipping_info.async_statuses.ready_to_ship.

Use with care. For carriers that operate pre-agreed line hauls or fixed daily pickup routes, sending an ad-hoc ready-to-ship notification can interfere with the carrier's own scheduling. Only call this endpoint for carriers and accounts configured to expect it.

The body is optional. Include it to update parcel information (weight, dimensions, count) at the same time, which is often when the final parcel details become known, or to set schedule_pickup and suppress_communication. ready_to_ship_date defaults to now.