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

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`

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

- operation: `check_coverage`
- scope: `coverage.read`
- entitlement: carrier_agreement
- creates a transaction: no
- idempotency key: not required
- MCP tool: `check_coverage`
- status: beta

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

### `GET /v1/rates`

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
- creates a transaction: no
- idempotency key: not required
- MCP tool: `quote_rates`
- status: beta

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

### `POST /v1/shipments`

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

- operation: `create_shipment`
- scope: `shipments.create`
- entitlement: carrier_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `create_shipment`
- status: beta

```bash
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`

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
- creates a transaction: no
- idempotency key: supported
- MCP tool: `create_shipments_batch`
- status: beta

```bash
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}`

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
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_shipment`
- status: beta

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

### `GET /v1/shipments`

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

- operation: `list_shipments`
- scope: `shipments.read`
- entitlement: carrier_agreement
- creates a transaction: no
- idempotency key: not required
- MCP tool: `list_shipments`
- status: beta

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

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

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
- creates a transaction: no
- idempotency key: supported
- MCP tool: `cancel_shipment`
- status: beta

```bash
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`

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
- creates a transaction: no
- idempotency key: not required
- MCP tool: `list_shipment_events`
- status: beta

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

### `GET /v1/hubs`

The depots your parcels are collected from.

- operation: `list_hubs`
- scope: `coverage.read`
- entitlement: carrier_agreement
- creates a transaction: no
- idempotency key: not required
- MCP tool: `list_hubs`
- status: beta

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