# Customers API Reference

REST schemas and generated examples for customer and subscription lifecycle operations.

<!-- docs-source -->
Source: https://learning.monetizekit.app/docs/api-reference/customers
<!-- /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 |

## customers operations

### List customers

`GET /customers` — Lists customers in the active workspace.

Operation ID: customers.list.

Required scopes: customers:view.

#### 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" } | 25 |

#### Responses

`200` — Success

```json
{
  "type": "object",
  "required": [
    "data",
    "total",
    "page",
    "pageSize",
    "totalPages",
    "hasNext",
    "hasPrev"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "name",
          "email"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string"
          }
        }
      }
    },
    "total": {
      "type": "integer"
    },
    "page": {
      "type": "integer"
    },
    "pageSize": {
      "type": "integer"
    },
    "totalPages": {
      "type": "integer"
    },
    "hasNext": {
      "type": "boolean"
    },
    "hasPrev": {
      "type": "boolean"
    }
  }
}
```

```json
{
  "data": [
    {
      "id": "cust_001",
      "name": "Acme Corp",
      "email": "ops@acme.test"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 25,
  "totalPages": 1,
  "hasNext": false,
  "hasPrev": false
}
```

### Create customer

`POST /customers` — Creates a customer profile.

Operation ID: customers.create.

Required scopes: customers:create.

#### Request schema

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

#### Request example

```json
{
  "name": "Acme Project",
  "email": "ops@acme.test"
}
```

#### Responses

`201` — Created

```json
{
  "type": "object",
  "required": [
    "id",
    "name",
    "email"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "email": {
      "type": "string"
    }
  }
}
```

```json
{
  "id": "cust_445",
  "name": "Acme Project",
  "email": "ops@acme.test"
}
```

### subscriptions.create

`POST /api/v1/subscriptions`

| Contract | Value |
| --- | --- |
| Success statuses | 201 |
| Required scopes | subscriptions:write |
| Request fields | cancelAt, currentPeriodEnd, currentPeriodStart, customerId, planId, status, stripeSubscriptionId, trialEnd |
| Response fields | currentPeriodEnd, currentPeriodStart, customerId, id, planId, planName, status |

```bash
curl --request POST 'https://app.monetizekit.app/api/v1/subscriptions' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{"cancelAt":"<cancelAt>","currentPeriodEnd":"<currentPeriodEnd>","currentPeriodStart":"<currentPeriodStart>","customerId":"<customerId>","planId":"<planId>","status":"<status>","stripeSubscriptionId":"<stripeSubscriptionId>","trialEnd":"<trialEnd>"}'
```