Skip to content

Ryde Developers

Español Dashboard ryde.us.com

Carrier

Hand Ryde parcels to deliver. This is the surface a logistics operator or marketplace integrates once and then stops thinking about: ask whether a postcode is covered, send a manifest of up to 500 parcels in a single request, and follow each one by its Ryde tracking number until it is delivered, refused or returned. Every parcel answers with the same seven-word status vocabulary a tracking aggregator expects, so the feed you build here is the feed your customers already know how to read. Access needs an approved shipper organization with a signed Ryde Carrier Agreement; prices come from the rate card in that agreement, not from a per-request quote.

API version v1 · View as Markdown

Hand Ryde parcels to deliver. This is the surface a logistics operator or marketplace integrates once and then stops thinking about: ask whether a postcode is covered, send a manifest of up to 500 parcels in a single request, and follow each one by its Ryde tracking number until it is delivered, refused or returned. Every parcel answers with the same seven-word status vocabulary a tracking aggregator expects, so the feed you build here is the feed your customers already know how to read. Access needs an approved shipper organization with a signed Ryde Carrier Agreement; prices come from the rate card in that agreement, not from a per-request quote.

Lifecycle

  CREATED               (we have the parcel's details, not the parcel)
     |
  AT HUB / SORTED       (it is at the depot it will be collected from)
     |
  COLLECTED             (a courier has it in hand, scanned at the depot)
     |
  OUT FOR DELIVERY      (the run has started; the recipient is told)
     |
  DELIVERED  <----+     (photo and recipient name are the proof)
     |            |
  ATTEMPTED ------+     (nobody home, refused, cannot reach the door;
     |                   it goes back on a later run)
  RETURNED TO HUB
     |
  RETURNED TO SHIPPER   (attempts exhausted, or you asked for it back)

  You may CANCEL at any point before a parcel is delivered or returned
  — including while it is already on a van.

Operations

`GET` `/v1/coverage`

Beta Carrier agreement required Sandbox supported

Ask whether Ryde delivers to a postcode or a point, and at which service levels.

Operation	`check_coverage`
Scope	`coverage.read`
Entitlement	Carrier agreement required
Idempotency	Not required
MCP tool	`check_coverage`

Example request

curl -s 'https://sandbox-api.ryde.us.com/v1/coverage' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN"

`GET` `/v1/rates`

Beta Carrier agreement required Sandbox supported

Price one parcel to one address from your contracted rate card, per service level. Creates nothing.

Operation	`quote_rates`
Scope	`coverage.read`
Entitlement	Carrier agreement required
Idempotency	Not required
MCP tool	`quote_rates`

Example request

curl -s 'https://sandbox-api.ryde.us.com/v1/rates' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN"

`POST` `/v1/shipments`

Beta Carrier agreement required Sandbox supported

Hand Ryde one parcel to deliver. Returns its Ryde tracking number.

Operation	`create_shipment`
Scope	`shipments.create`
Entitlement	Carrier agreement required
Idempotency	Supported
MCP tool	`create_shipment`

Example request

curl -sX POST 'https://sandbox-api.ryde.us.com/v1/shipments' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ … }'

`POST` `/v1/shipments/batch`

Beta Carrier agreement required Sandbox supported

Hand Ryde a manifest of up to 500 parcels in one request. Every row reports created, duplicate or rejected with a reason.

Operation	`create_shipments_batch`
Scope	`shipments.create`
Entitlement	Carrier agreement required
Idempotency	Supported
MCP tool	`create_shipments_batch`

Example request

curl -sX POST 'https://sandbox-api.ryde.us.com/v1/shipments/batch' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ … }'

`GET` `/v1/shipments/{tracking_number}`

Beta Carrier agreement required Sandbox supported

The current state of one parcel, with its scan history and proof of delivery once delivered.

Operation	`get_shipment`
Scope	`shipments.read`
Entitlement	Carrier agreement required
Idempotency	Not required
MCP tool	`get_shipment`

Example request

curl -s 'https://sandbox-api.ryde.us.com/v1/shipments/$tracking_number' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN"

`GET` `/v1/shipments`

Beta Carrier agreement required Sandbox supported

Your parcels, newest first, filterable by status and date.

Operation	`list_shipments`
Scope	`shipments.read`
Entitlement	Carrier agreement required
Idempotency	Not required
MCP tool	`list_shipments`

Example request

curl -s 'https://sandbox-api.ryde.us.com/v1/shipments' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN"

`POST` `/v1/shipments/{tracking_number}/cancel`

Beta Carrier agreement required Sandbox supported

Cancel a parcel you have given Ryde, at any point before it is delivered or returned.

Operation	`cancel_shipment`
Scope	`shipments.manage`
Entitlement	Carrier agreement required
Idempotency	Supported
MCP tool	`cancel_shipment`

Example request

curl -sX POST 'https://sandbox-api.ryde.us.com/v1/shipments/$tracking_number/cancel' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ … }'

`GET` `/v1/shipments/{tracking_number}/events`

Beta Carrier agreement required Sandbox supported

Every recorded event for one parcel, oldest first: where it was scanned, when, and why an attempt failed.

Operation	`list_shipment_events`
Scope	`shipments.read`
Entitlement	Carrier agreement required
Idempotency	Not required
MCP tool	`list_shipment_events`

Example request

curl -s 'https://sandbox-api.ryde.us.com/v1/shipments/$tracking_number/events' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN"

`GET` `/v1/hubs`

Beta Carrier agreement required Sandbox supported

The depots your parcels are collected from.

Operation	`list_hubs`
Scope	`coverage.read`
Entitlement	Carrier agreement required
Idempotency	Not required
MCP tool	`list_hubs`

Example request

curl -s 'https://sandbox-api.ryde.us.com/v1/hubs' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN"