# API reference

Every operation, generated from the platform's own operation registry.

> **Info:** This page is generated from the same registry the gateway authorizes against. The scope, entitlement, idempotency and sandbox facts below are not a description of the implementation — they are the implementation's own metadata.

### `GET /v1/me/membership`

Whether this customer holds an active Ryde One membership. Call it before offering to transact, so the agent can explain the requirement rather than hit a 403 mid-sentence.

- operation: `get_membership_status`
- scope: `profile.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_membership_status`
- status: beta

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

### `GET /v1/food/merchants`

Find open restaurants, grocery stores and shops near a point.

- operation: `search_restaurants`
- scope: `food.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `search_restaurants`
- status: beta

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

### `GET /v1/food/merchants/{merchant_id}/menu`

The public catalogue for one merchant. Cost, stock, barcodes and supplier ids are the merchant's own business and are never returned here.

- operation: `get_restaurant_menu`
- scope: `food.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_restaurant_menu`
- status: beta

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

### `POST /v1/food/orders/quote`

Price a basket exactly as checkout would: items, fees, taxes, any member discount, and the total. Returns the quote_id place_food_order requires.

- operation: `quote_food_order`
- scope: `food.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `quote_food_order`
- status: beta

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

### `POST /v1/food/orders`

Place the order the customer confirmed, from a quote_id they were shown.

- operation: `place_food_order`
- scope: `food.order`
- entitlement: ryde_one
- creates a transaction: yes
- idempotency key: required
- MCP tool: `place_food_order`
- status: beta

```bash
curl -sX POST 'https://sandbox-api.ryde.us.com/v1/food/orders' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{ … }'
```

### `GET /v1/food/orders/{order_id}`

Live state of one order, including courier progress. Deliberately NOT membership-gated: an order that exists stays trackable whatever happens to the membership.

- operation: `get_food_order`
- scope: `food.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_food_order`
- status: beta

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

### `GET /v1/food/orders`

The customer's own order history, newest first.

- operation: `list_food_orders`
- scope: `food.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `list_food_orders`
- status: beta

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

### `POST /v1/food/orders/{order_id}/cancel`

Cancel an order, where its current state still allows it. Never membership-gated — getting OUT of a transaction must not require an entitlement.

- operation: `cancel_food_order`
- scope: `food.read`
- entitlement: none
- creates a transaction: no
- idempotency key: supported
- MCP tool: `cancel_food_order`
- status: beta

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

### `GET /v1/rides/products`

The vehicle tiers that can be requested, with each tier's base fare.

- operation: `search_ride_options`
- scope: `rides.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `search_ride_options`
- status: beta

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

### `POST /v1/rides/quote`

Road distance, driving time and the final fare per vehicle tier, tax included. Returns the quote_id request_ride requires.

- operation: `quote_ride`
- scope: `rides.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `quote_ride`
- status: beta

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

### `POST /v1/rides`

Request the ride the customer confirmed, from a quote_id they were shown.

- operation: `request_ride`
- scope: `rides.request`
- entitlement: ryde_one
- creates a transaction: yes
- idempotency key: required
- MCP tool: `request_ride`
- status: beta

```bash
curl -sX POST 'https://sandbox-api.ryde.us.com/v1/rides' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{ … }'
```

### `GET /v1/rides/{ride_id}`

Live state of one ride: dispatch progress, the assigned driver and vehicle, and the pickup ETA. Never membership-gated — a ride in progress stays trackable.

- operation: `get_ride`
- scope: `rides.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_ride`
- status: beta

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

### `GET /v1/rides`

The customer's own ride history, newest first.

- operation: `list_rides`
- scope: `rides.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `list_rides`
- status: beta

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

### `POST /v1/rides/{ride_id}/cancel`

Cancel a ride that has not started. Never membership-gated, for the same reason as cancelling an order.

- operation: `cancel_ride`
- scope: `rides.read`
- entitlement: none
- creates a transaction: no
- idempotency key: supported
- MCP tool: `cancel_ride`
- status: beta

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

### `POST /v1/deliveries/quote`

Price a courier run between two points. Runs the same pricing path the request does, so the quote is the charge.

- operation: `quote_delivery`
- scope: `delivery.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `quote_delivery`
- status: beta

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

### `POST /v1/deliveries`

Dispatch a courier to move a package, from a quote_id the customer was shown.

- operation: `request_delivery`
- scope: `delivery.request`
- entitlement: ryde_one
- creates a transaction: yes
- idempotency key: required
- MCP tool: `request_delivery`
- status: beta

```bash
curl -sX POST 'https://sandbox-api.ryde.us.com/v1/deliveries' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{ … }'
```

### `GET /v1/deliveries/{delivery_id}`

Live state of one delivery, including courier progress and proof of delivery once collected.

- operation: `get_delivery`
- scope: `delivery.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_delivery`
- status: beta

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

### `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"
```

### `GET /v1/services/providers`

Find providers who travel to the customer, with their live availability. Availability is derived per request and is never cached by the client.

- operation: `search_service_providers`
- scope: `services.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `search_service_providers`
- status: beta

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

### `GET /v1/services/providers/{provider_id}/slots`

Open appointment slots on a date, for a job of a given duration. A long job is only offered a start whose consecutive slots are all free.

- operation: `get_provider_availability`
- scope: `services.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_provider_availability`
- status: beta

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

### `POST /v1/services/bookings/quote`

Price a service booking before committing to a slot.

- operation: `quote_service`
- scope: `services.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `quote_service`
- status: beta

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

### `POST /v1/services/bookings`

Book a provider, optionally into a specific slot. Slot contention is settled by the platform: a losing booking is refused, never double-booked.

- operation: `book_service`
- scope: `services.book`
- entitlement: ryde_one
- creates a transaction: yes
- idempotency key: required
- MCP tool: `book_service`
- status: beta

```bash
curl -sX POST 'https://sandbox-api.ryde.us.com/v1/services/bookings' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{ … }'
```

### `GET /v1/services/bookings/{booking_id}`

Live state of one booking, through arrival, start and completion.

- operation: `get_service_booking`
- scope: `services.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_service_booking`
- status: beta

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

### `GET /v1/tasks/types`

The task types this market can actually execute, with the evidence each one collects. Only types Ryde can staff are listed.

- operation: `list_task_types`
- scope: `tasks.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `list_task_types`
- status: beta

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

### `POST /v1/tasks/quote`

Price a task and confirm a qualified provider could be found for it before committing.

- operation: `quote_task`
- scope: `tasks.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `quote_task`
- status: beta

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

### `POST /v1/tasks`

Dispatch real-world work with structured requirements and evidence rules.

- operation: `create_task`
- scope: `tasks.create`
- entitlement: ryde_one
- creates a transaction: yes
- idempotency key: required
- MCP tool: `create_task`
- status: beta

```bash
curl -sX POST 'https://sandbox-api.ryde.us.com/v1/tasks' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{ … }'
```

### `GET /v1/tasks/{task_id}`

Task state, the assigned provider, and the evidence collected so far.

- operation: `get_task`
- scope: `tasks.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_task`
- status: beta

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

### `GET /v1/tasks/{task_id}/evidence`

The evidence collected against a task: photos with their content hashes, capture GPS and device timestamps, and any checklist answers.

- operation: `get_task_evidence`
- scope: `tasks.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_task_evidence`
- status: beta

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

### `POST /v1/tasks/{task_id}/cancel`

Cancel a task that has not started.

- operation: `cancel_task`
- scope: `tasks.read`
- entitlement: none
- creates a transaction: no
- idempotency key: supported
- MCP tool: `cancel_task`
- status: beta

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

### `GET /v1/business/orders`

List the store's orders, newest first. Filter by status or fulfillment, or ask only for active work.

- operation: `list_business_orders`
- scope: `orders.read`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: not required
- MCP tool: `list_business_orders`
- status: beta

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

### `GET /v1/business/orders/{order_id}`

Read one of the store's orders in full, including its line items and status history.

- operation: `get_business_order`
- scope: `orders.read`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_business_order`
- status: beta

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

### `POST /v1/business/orders/{order_id}/accept`

Accept an incoming order. Refused with 402 if a card or wallet order has not been paid yet.

- operation: `accept_business_order`
- scope: `orders.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `accept_business_order`
- status: beta

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

### `POST /v1/business/orders/{order_id}/reject`

Reject an order. A paid order is refunded to the customer's Ryde wallet — or, when the store collected it on its own Stripe account, to the customer's card by the store — and any booked slot is released.

- operation: `reject_business_order`
- scope: `orders.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `reject_business_order`
- status: beta

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

### `POST /v1/business/orders/{order_id}/preparing`

Mark an accepted order as being prepared, so the customer's tracking reflects the kitchen.

- operation: `start_business_order_prep`
- scope: `orders.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `start_business_order_prep`
- status: beta

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

### `POST /v1/business/orders/{order_id}/ready`

Mark an order ready for collection. For a delivery order this is what dispatches a Ryde courier.

- operation: `mark_business_order_ready`
- scope: `orders.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `mark_business_order_ready`
- status: beta

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

### `POST /v1/business/orders/{order_id}/complete`

Complete a pickup or dine-in order. Refused with 409 while a table check is still open.

- operation: `complete_business_order`
- scope: `orders.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `complete_business_order`
- status: beta

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

### `GET /v1/business/catalog/items`

List the store's catalogue items with their prices, modifiers and availability.

- operation: `list_catalog_items`
- scope: `menu.read`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: not required
- MCP tool: `list_catalog_items`
- status: beta

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

### `GET /v1/business/catalog/items/{item_id}`

Read one catalogue item by its id: price, SKU, barcode, tax treatment, stock and availability.

- operation: `get_catalog_item`
- scope: `menu.read`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_catalog_item`
- status: beta

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

### `POST /v1/business/catalog/items`

Create a catalogue item. It appears immediately in the store's POS and on its Ryde storefront.

- operation: `create_catalog_item`
- scope: `menu.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `create_catalog_item`
- status: beta

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

### `PUT /v1/business/catalog/items/{item_id}`

Update a catalogue item's name, description, price, category or modifier groups.

- operation: `update_catalog_item`
- scope: `menu.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `update_catalog_item`
- status: beta

```bash
curl -sX PUT 'https://sandbox-api.ryde.us.com/v1/business/catalog/items/$item_id' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ … }'
```

### `PUT /v1/business/catalog/items/by-sku/{sku}`

Create or update the catalogue item with this SKU. The SKU is unique within the store, so the same call is safe to repeat.

- operation: `upsert_catalog_item_by_sku`
- scope: `menu.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `upsert_catalog_item_by_sku`
- status: beta

```bash
curl -sX PUT 'https://sandbox-api.ryde.us.com/v1/business/catalog/items/by-sku/$sku' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ … }'
```

### `PUT /v1/business/catalog/items/{item_id}/availability`

Take an item off sale or put it back on, without deleting it. The reversible way to 86 something.

- operation: `set_catalog_item_availability`
- scope: `menu.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `set_catalog_item_availability`
- status: beta

```bash
curl -sX PUT 'https://sandbox-api.ryde.us.com/v1/business/catalog/items/$item_id/availability' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ … }'
```

### `DELETE /v1/business/catalog/items/{item_id}`

Remove a catalogue item. There is no undo through the API — to take something off sale temporarily, set its availability instead.

- operation: `delete_catalog_item`
- scope: `menu.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `delete_catalog_item`
- status: beta

```bash
curl -sX DELETE 'https://sandbox-api.ryde.us.com/v1/business/catalog/items/$item_id' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ … }'
```

### `POST /v1/business/catalog/items/batch`

Add many catalogue items at once, with their categories. Duplicate-safe: an item matched by SKU or barcode is updated (price and description) instead of added twice, a name-only match is skipped unless decided, and mode "replace" retires items missing from the list once confirm_retire equals the count a 409 names.

- operation: `import_catalog_items`
- scope: `menu.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `import_catalog_items`
- status: beta

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

### `GET /v1/business/catalog/export`

Export the store's sellable catalogue as rows in the fixed template's columns (name, SKU, barcode, category, type, price, tax, cost, stock, warehouse, description). Cost, stock and barcode are filled only for a token with menu.manage.

- operation: `export_catalog`
- scope: `menu.read`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: not required
- MCP tool: `export_catalog`
- status: beta

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

### `GET /v1/business/catalog/template`

The template's columns, the values each accepts, an example row, the row limit and the import modes.

- operation: `get_catalog_template`
- scope: `menu.read`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_catalog_template`
- status: beta

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

### `POST /v1/business/catalog/import/preview`

Check rows in the template's columns against the catalogue WITHOUT writing: what is new, updated, unchanged, a possible duplicate or an error, per row. Answers a token for the commit.

- operation: `preview_catalog_import`
- scope: `menu.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `preview_catalog_import`
- status: beta

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

### `POST /v1/business/catalog/import/commit`

Apply a previewed import by its token, in mode merge, add_only or replace. Committing the same token again answers the first result and writes nothing.

- operation: `commit_catalog_import`
- scope: `menu.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `commit_catalog_import`
- status: beta

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