Customers API Reference

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

{
  "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"
    }
  }
}

{
  "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

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

Request example

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

Responses

201 — Created

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

{
  "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

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>"}'

Loading OpenAPI contract...