Shipping API

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

Forward vs reverse

Set entity_type to either:

• FORWARD: a normal outbound shipment from the merchant to the customer.
• REVERSE: a return shipment, where the customer sends items back to the merchant.

Draft, confirmed, prebooked

Three creation modes, each with different behaviour 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 created in error status with the validation errors in the response.

• 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 does a substring match across carrier tracking number, order reference, shipment reference, customer name, email, and similar fields; combine it with the other filters, sort, and pagination parameters as needed.

Quota: this endpoint is subject to your account's monthly shipment quota. Once the monthly limit is exceeded, further requests are blocked until the quota resets.

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

The path parameter accepts either the Carriyo shipment_id or the merchant's partner_shipment_reference. The reference variant is useful when your own system only retained the value it originally supplied.

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.)

Merge rules

• Top-level fields you include are replaced wholesale. For example, to change only the pickup postcode, you still pass the entire pickup object; any field you omit there is reset to its default. Plan your payload accordingly.
• Custom attributes are the exception and merge key-by-key. You can add or change a single attribute without supplying the others. To remove an attribute, set its value to null.

The path parameter accepts either the Carriyo shipment_id or the merchant's partner_shipment_reference.

Fully replace a draft shipment. The request body overwrites the existing shipment in its entirety: any field you omit is reset to the schema default, including nested objects like pickup, dropoff, parcels, and items. If you want to change only a few fields and leave the rest intact, use Update shipment (PATCH) instead.

Only draft shipments can be replaced. Confirmed shipments return 400.

The path parameter accepts either the Carriyo shipment_id or the merchant's partner_shipment_reference.

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):

• Top-level fields you include are replaced wholesale; omitted fields reset to defaults.
• Custom attributes are the exception and merge key-by-key. 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.

The path parameter accepts either the Carriyo shipment_id or the merchant's partner_shipment_reference.

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):

• Top-level fields you include are replaced wholesale; omitted fields reset to defaults.
• Custom attributes are the exception and merge key-by-key. 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.

The path parameter accepts either the Carriyo shipment_id or the merchant's partner_shipment_reference.

Mark a shipment as ready to ship.

For carriers that support scheduled collection (typically on-demand couriers), this also notifies the carrier of the scheduled collection date and time so they can arrange pickup.

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.

The path parameter accepts either the Carriyo shipment_id or the merchant's partner_shipment_reference.