> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.rookoo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Rates and pricing

> Manage the rate catalogue and preview event pricing.

Rates are priced catalogue items used when calculating an event total and generating quotes. Pricing plans and rules select which rates apply.

## Rates

Base path: `/api/v1/accounts/{account_id}/planning/rates`

### List / show

```bash theme={null}
curl https://app.rookoo.ai/api/v1/accounts/1/planning/rates \
  -H "api_access_token: YOUR_ACCESS_TOKEN"
```

### Create a rate

```bash theme={null}
curl -X POST https://app.rookoo.ai/api/v1/accounts/1/planning/rates \
  -H "api_access_token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rate": {
      "name": "Room hire – Grand Hall",
      "category": "space",
      "space_id": "SPACE_UUID",
      "position": 1,
      "prices_attributes": [
        {
          "name": "Half day",
          "unit": "half_day",
          "currency": "EUR",
          "price": 750,
          "tax_rate": 21,
          "is_default": true,
          "position": 0
        },
        {
          "name": "Full day",
          "unit": "day",
          "currency": "EUR",
          "price": 1200,
          "tax_rate": 21,
          "is_default": false,
          "position": 1
        }
      ]
    }
  }'
```

| Field | Notes |
| - | - |
| `name` | Display name |
| `category` | e.g. space, catering, av |
| `space_id` | Optional link to a space |
| `attribute_key` | Optional custom-attribute key |
| `position` | Sort order |
| `prices_attributes[]` | Nested prices (`unit`, `currency`, `price`, `tax_rate`, `is_default`) |

Creating a rate also ensures a default pricing-plan rule so it can appear in calculations.

### Update / delete

```bash theme={null}
curl -X PATCH https://app.rookoo.ai/api/v1/accounts/1/planning/rates/RATE_ID \
  -H "api_access_token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rate": {
      "prices_attributes": [
        { "id": 10, "price": 800 },
        { "id": 11, "_destroy": true }
      ]
    }
  }'

curl -X DELETE https://app.rookoo.ai/api/v1/accounts/1/planning/rates/RATE_ID \
  -H "api_access_token: YOUR_ACCESS_TOKEN"
```

## Pricing plans and rules

| Resource | Path |
| - | - |
| Plans | `/api/v1/accounts/{account_id}/planning/pricing-plans` |
| Rules | `/api/v1/accounts/{account_id}/planning/pricing-plans/{id}/rules` |
| Discount codes | `/api/v1/accounts/{account_id}/planning/discount-codes` |

A plan groups rules that point at rates. Assign a plan on the event with `pricing_plan_id`, then preview or lock pricing.

### Create a pricing plan

```bash theme={null}
curl -X POST https://app.rookoo.ai/api/v1/accounts/1/planning/pricing-plans \
  -H "api_access_token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pricing_plan": {
      "name": "2026 Standard",
      "active": true,
      "is_default": true,
      "valid_from": "2026-01-01",
      "valid_to": "2026-12-31",
      "repeat_yearly": true
    }
  }'
```

Creating a rate auto-adds a default rule on the default plan. To attach a rate explicitly:

```bash theme={null}
curl -X POST https://app.rookoo.ai/api/v1/accounts/1/planning/pricing-plans/PLAN_ID/rules \
  -H "api_access_token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pricing_rule": {
      "name": "Grand Hall hire",
      "rate_id": 12,
      "priority": 10,
      "active": true
    }
  }'
```

### Create a discount code

```bash theme={null}
curl -X POST https://app.rookoo.ai/api/v1/accounts/1/planning/discount-codes \
  -H "api_access_token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "discount_code": {
      "name": "Launch 10%",
      "code": "LAUNCH10",
      "discount_type": "percentage",
      "value": 10,
      "active": true,
      "valid_until": "2026-12-31"
    }
  }'
```

Pass `discount_code_ids` when [creating a quote](/events/quotes).

## Preview / lock pricing on an event

```bash theme={null}
curl -X POST https://app.rookoo.ai/api/v1/accounts/1/planning/pricing/preview \
  -H "api_access_token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "event_id": "EVENT_UUID", "pricing_plan_id": 3 }'

curl -X POST https://app.rookoo.ai/api/v1/accounts/1/planning/pricing/lock \
  -H "api_access_token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "event_id": "EVENT_UUID" }'

curl -X POST https://app.rookoo.ai/api/v1/accounts/1/planning/pricing/unlock \
  -H "api_access_token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "event_id": "EVENT_UUID" }'
```

`preview` returns a breakdown without persisting. `lock` stores the priced state on the event metadata. When the `planning_quotes` feature is enabled on the account, prefer creating a [quote](/events/quotes) instead of locking — `lock` returns an error in that case.

After pricing looks right, [create a quote](/events/quotes) from the event.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.