# Catalog API Reference

REST schemas and generated examples for products, plans, features, add-ons, and meters.

<!-- docs-source -->
Source: https://learning.monetizekit.app/docs/api-reference/catalog
<!-- /docs-source -->

Mock API reference used by the interactive docs explorer.

| OpenAPI version | Contract version | REST base path |
| --- | --- | --- |
| 3.1.0 | 2026-03-15 | /api/v1 |

## Servers

| URL | Environment |
| --- | --- |
| `https://app.monetizekit.app/api/v1` | Development environment |
| `https://app.monetizekit.app/api/v1` | Staging environment |
| `https://app.monetizekit.app/api/v1` | Production environment |

## catalog operations

### List plans

`GET /plans` — Returns plans visible to the current workspace.

Operation ID: plans.list.

Required scopes: plans:read.

#### Parameters

| Name | In | Required | Description | Schema | Example |
| --- | --- | --- | --- | --- | --- |
| `page` | query | no | One-based page number. | { "type": "integer" } | 1 |
| `pageSize` | query | no | Number of records per page. | { "type": "integer" } | 20 |

#### Responses

`200` — Success

```json
{
  "type": "object",
  "required": [
    "data",
    "total",
    "page",
    "pageSize",
    "totalPages",
    "hasNext",
    "hasPrev"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "key",
          "name",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "key": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "published",
              "archived"
            ]
          }
        }
      }
    },
    "total": {
      "type": "integer"
    },
    "page": {
      "type": "integer"
    },
    "pageSize": {
      "type": "integer"
    },
    "totalPages": {
      "type": "integer"
    },
    "hasNext": {
      "type": "boolean"
    },
    "hasPrev": {
      "type": "boolean"
    }
  }
}
```

```json
{
  "data": [
    {
      "id": "plan_001",
      "key": "starter_monthly",
      "name": "Starter",
      "status": "published"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20,
  "totalPages": 1,
  "hasNext": false,
  "hasPrev": false
}
```

### Create plan

`POST /plans` — Creates a draft plan with entitlements and pricing terms.

Operation ID: createPlan.

Required scopes: plans:write.

#### Request schema

```json
{
  "type": "object",
  "required": [
    "productId",
    "name"
  ],
  "properties": {
    "productId": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    }
  }
}
```

#### Request example

```json
{
  "productId": "prod_saas",
  "name": "Growth",
  "description": "Growth plan"
}
```

#### Responses

`201` — Created

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    }
  }
}
```

```json
{
  "id": "plan_002",
  "status": "draft"
}
```