# Business

Operate a store you are authorized for: read and work its order queue, and manage its catalogue. These are the same routes the Ryde merchant portal and its point of sale call, so a change made here appears on the store's own terminal immediately — there is no separate "API catalogue" to keep in step. Access needs the merchant's own authorization plus their signed Ryde business agreement; a developer cannot accept that agreement on a store's behalf.

Operate a store you are authorized for: read and work its order queue, and manage its catalogue. These are the same routes the Ryde merchant portal and its point of sale call, so a change made here appears on the store's own terminal immediately — there is no separate "API catalogue" to keep in step. Access needs the merchant's own authorization plus their signed Ryde business agreement; a developer cannot accept that agreement on a store's behalf.

## Lifecycle

```
  PLACED                (the customer has paid, or is paying cash)
     |
  MERCHANT ACCEPTED  ---> REJECTED   (a paid order is refunded to the
     |                                customer's Ryde wallet)
  PREPARING
     |
  READY FOR PICKUP      (for a delivery order, THIS is what dispatches
     |                   a Ryde courier — couriers accept first-come,
     |                   so there is nothing to assign)
  PICKED UP
     |
  DELIVERED             (or COMPLETED, for pickup and dine-in)
```

## Operations

### `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 '{ … }'
```