### MCP server configuration example

Source: https://komashi.com/docs/provider/Developers/mcp-integration/index

Example configuration for a client that supports HTTP transport and OAuth. The configuration shape varies by client; this supplies the endpoint, and authorization still takes place through the client's OAuth flow. A client that only accepts a static Bearer key is not sufficient.

```json
{
  "mcpServers": {
    "komashi": {
      "type": "http",
      "url": "https://mcp.komashi.com/"
    }
  }
}
```

--------------------------------

### GET /services

Source: https://komashi.com/docs/llms-full.txt

Lists all available services in the catalog. Use this endpoint to discover the services that can be configured.

```APIDOC
## GET /services

### Description
Lists all available services in the catalog.

### Method
GET

### Endpoint
/services

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number for pagination.
- **per_page** (integer) - Optional - Number of items per page (default 25, max 100).

### Request Example
```bash
curl "$KOMASHI_API_BASE/services?page=1&per_page=25" \
  -H "Authorization: Bearer $KOMASHI_API_KEY" \
  -H 'Accept: application/json'
```

### Response
#### Success Response (200)
- **succeeded** (boolean) - Indicates if the request succeeded.
- **status_code** (integer) - HTTP status code.
- **data** (array) - List of services.
- **links** (object) - Pagination links (if present).
- **meta** (object) - Pagination metadata (if present).

#### Response Example
```json
{
  "succeeded": true,
  "status_code": 200,
  "data": []
}
```
```

--------------------------------

### GET /services/{service}/addons

Source: https://komashi.com/docs/llms-full.txt

Lists the add-ons available for a specific service. Use the service identifier to retrieve its add-ons.

```APIDOC
## GET /services/{service}/addons

### Description
Lists the add-ons available for a specific service.

### Method
GET

### Endpoint
/services/{service}/addons

### Parameters
#### Path Parameters
- **service** (string) - Required - The service identifier.

#### Query Parameters
- **page** (integer) - Optional - Page number for pagination.
- **per_page** (integer) - Optional - Number of items per page (default 25, max 100).

### Request Example
```bash
curl "$KOMASHI_API_BASE/services/{service}/addons?page=1&per_page=25" \
  -H "Authorization: Bearer $KOMASHI_API_KEY" \
  -H 'Accept: application/json'
```

### Response
#### Success Response (200)
- **succeeded** (boolean) - Indicates if the request succeeded.
- **status_code** (integer) - HTTP status code.
- **data** (array) - List of add-ons.
- **links** (object) - Pagination links (if present).
- **meta** (object) - Pagination metadata (if present).

#### Response Example
```json
{
  "succeeded": true,
  "status_code": 200,
  "data": []
}
```
```

--------------------------------

### GET /services/{service}/addons/{addon_id}/options

Source: https://komashi.com/docs/llms-full.txt

Lists the options for a specific add-on. Use the service and add-on identifiers to retrieve the options.

```APIDOC
## GET /services/{service}/addons/{addon_id}/options

### Description
Lists the options for a specific add-on.

### Method
GET

### Endpoint
/services/{service}/addons/{addon_id}/options

### Parameters
#### Path Parameters
- **service** (string) - Required - The service identifier.
- **addon_id** (string) - Required - The add-on identifier.

#### Query Parameters
- **page** (integer) - Optional - Page number for pagination.
- **per_page** (integer) - Optional - Number of items per page (default 25, max 100).

### Request Example
```bash
curl "$KOMASHI_API_BASE/services/{service}/addons/{addon_id}/options?page=1&per_page=25" \
  -H "Authorization: Bearer $KOMASHI_API_KEY" \
  -H 'Accept: application/json'
```

### Response
#### Success Response (200)
- **succeeded** (boolean) - Indicates if the request succeeded.
- **status_code** (integer) - HTTP status code.
- **data** (array) - List of add-on options.
- **links** (object) - Pagination links (if present).
- **meta** (object) - Pagination metadata (if present).

#### Response Example
```json
{
  "succeeded": true,
  "status_code": 200,
  "data": []
}
```
```

--------------------------------

### GET /services/{service}

Source: https://komashi.com/docs/llms-full.txt

Retrieves details for a specific service. Use the service identifier obtained from the list of services.

```APIDOC
## GET /services/{service}

### Description
Retrieves details for a specific service.

### Method
GET

### Endpoint
/services/{service}

### Parameters
#### Path Parameters
- **service** (string) - Required - The service identifier.

### Request Example
```bash
curl "$KOMASHI_API_BASE/services/{service}" \
  -H "Authorization: Bearer $KOMASHI_API_KEY" \
  -H 'Accept: application/json'
```

### Response
#### Success Response (200)
- **succeeded** (boolean) - Indicates if the request succeeded.
- **status_code** (integer) - HTTP status code.
- **data** (object) - The service details.

#### Response Example
```json
{
  "succeeded": true,
  "status_code": 200,
  "data": {}
}
```
```

--------------------------------

### GET /services/{service}/plans

Source: https://komashi.com/docs/llms-full.txt

Lists the plans available for a specific service. Use the service identifier to retrieve its plans.

```APIDOC
## GET /services/{service}/plans

### Description
Lists the plans available for a specific service.

### Method
GET

### Endpoint
/services/{service}/plans

### Parameters
#### Path Parameters
- **service** (string) - Required - The service identifier.

#### Query Parameters
- **page** (integer) - Optional - Page number for pagination.
- **per_page** (integer) - Optional - Number of items per page (default 25, max 100).

### Request Example
```bash
curl "$KOMASHI_API_BASE/services/{service}/plans?page=1&per_page=25" \
  -H "Authorization: Bearer $KOMASHI_API_KEY" \
  -H 'Accept: application/json'
```

### Response
#### Success Response (200)
- **succeeded** (boolean) - Indicates if the request succeeded.
- **status_code** (integer) - HTTP status code.
- **data** (array) - List of plans.
- **links** (object) - Pagination links (if present).
- **meta** (object) - Pagination metadata (if present).

#### Response Example
```json
{
  "succeeded": true,
  "status_code": 200,
  "data": []
}
```
```

--------------------------------

### GET /services/{service}/addons

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Lists all add-ons available for a specific service. Use the service identifier from the catalog.

```APIDOC
## [GET] /services/{service}/addons

### Description
List add-ons for a service.

### Method
GET

### Endpoint
/services/{service}/addons

### Parameters
#### Path Parameters
- **service** (string) - Required - The service identifier.

#### Query Parameters
- **page** (integer) - Optional - Page number for pagination.
- **per_page** (integer) - Optional - Number of items per page (default 25, max 100).

### Request Example
```bash
curl "$KOMASHI_API_BASE/services/{service}/addons?page=1&per_page=25" \
  -H "Authorization: Bearer $KOMASHI_API_KEY" \
  -H 'Accept: application/json'
```

### Response
#### Success Response (200)
- **succeeded** (boolean) - Indicates if the request succeeded.
- **status_code** (integer) - HTTP status code.
- **data** (array) - List of add-ons.
- **links** (object) - Pagination links (if present).
- **meta** (object) - Pagination metadata (if present).

#### Response Example
```json
{
  "succeeded": true,
  "status_code": 200,
  "data": []
}
```
```

--------------------------------

### GET /services/{service}/subscriptions

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Lists subscriptions for a service.

```APIDOC
## [GET] /services/{service}/subscriptions

### Description
Lists subscriptions for a service.

### Method
GET

### Endpoint
/services/{service}/subscriptions

### Parameters
#### Path Parameters
- **service** (string) - Required - The service identifier.
```

--------------------------------

### GET /services/{service}/service-prices/discounts

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Reads the available discounts for a service's prices. Use the service identifier from the catalog.

```APIDOC
## [GET] /services/{service}/service-prices/discounts

### Description
Read available discounts for a service.

### Method
GET

### Endpoint
/services/{service}/service-prices/discounts

### Parameters
#### Path Parameters
- **service** (string) - Required - The service identifier.

#### Query Parameters
- **page** (integer) - Optional - Page number for pagination.
- **per_page** (integer) - Optional - Number of items per page (default 25, max 100).

### Request Example
```bash
curl "$KOMASHI_API_BASE/services/{service}/service-prices/discounts?page=1&per_page=25" \
  -H "Authorization: Bearer $KOMASHI_API_KEY" \
  -H 'Accept: application/json'
```

### Response
#### Success Response (200)
- **succeeded** (boolean) - Indicates if the request succeeded.
- **status_code** (integer) - HTTP status code.
- **data** (array) - List of discounts.
- **links** (object) - Pagination links (if present).
- **meta** (object) - Pagination metadata (if present).

#### Response Example
```json
{
  "succeeded": true,
  "status_code": 200,
  "data": []
}
```
```

--------------------------------

### GET /services

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Lists all available services in the catalog. Use this endpoint to discover the services that can be configured and used in the API.

```APIDOC
## [GET] /services

### Description
Lists all available services in the catalog.

### Method
GET

### Endpoint
/services

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number for pagination.
- **per_page** (integer) - Optional - Number of items per page (default 25, max 100).

### Request Example
```bash
curl "$KOMASHI_API_BASE/services?page=1&per_page=25" \
  -H "Authorization: Bearer $KOMASHI_API_KEY" \
  -H 'Accept: application/json'
```

### Response
#### Success Response (200)
- **succeeded** (boolean) - Indicates if the request succeeded.
- **status_code** (integer) - HTTP status code.
- **data** (array) - List of services.
- **links** (object) - Pagination links (if present).
- **meta** (object) - Pagination metadata (if present).

#### Response Example
```json
{
  "succeeded": true,
  "status_code": 200,
  "data": []
}
```
```

--------------------------------

### GET /services/{service}/subscriptions

Source: https://komashi.com/docs/llms-full.txt

Lists subscriptions for a service. This endpoint returns a list of subscriptions associated with the specified service.

```APIDOC
## [GET] /services/{service}/subscriptions

### Description
Lists subscriptions for a service. This endpoint returns a list of subscriptions associated with the specified service.

### Method
GET

### Endpoint
/services/{service}/subscriptions

### Parameters
#### Path Parameters
- **service** (string) - Required - The service identifier.

### Response
#### Success Response (200)
- **data** (array) - List of subscriptions.
```

--------------------------------

### GET /invoices

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Reads invoice records.

```APIDOC
## [GET] /invoices

### Description
Reads invoice records.

### Method
GET

### Endpoint
/invoices
```

--------------------------------

### GET /services/{service}/addons/{addon_id}/options

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Lists the options for a specific add-on. Use the add-on identifier from the add-ons list.

```APIDOC
## [GET] /services/{service}/addons/{addon_id}/options

### Description
List add-on options.

### Method
GET

### Endpoint
/services/{service}/addons/{addon_id}/options

### Parameters
#### Path Parameters
- **service** (string) - Required - The service identifier.
- **addon_id** (string) - Required - The add-on identifier.

#### Query Parameters
- **page** (integer) - Optional - Page number for pagination.
- **per_page** (integer) - Optional - Number of items per page (default 25, max 100).

### Request Example
```bash
curl "$KOMASHI_API_BASE/services/{service}/addons/{addon_id}/options?page=1&per_page=25" \
  -H "Authorization: Bearer $KOMASHI_API_KEY" \
  -H 'Accept: application/json'
```

### Response
#### Success Response (200)
- **succeeded** (boolean) - Indicates if the request succeeded.
- **status_code** (integer) - HTTP status code.
- **data** (array) - List of add-on options.
- **links** (object) - Pagination links (if present).
- **meta** (object) - Pagination metadata (if present).

#### Response Example
```json
{
  "succeeded": true,
  "status_code": 200,
  "data": []
}
```
```

--------------------------------

### GET /subscriptions/groups/{group_id}

Source: https://komashi.com/docs/llms-full.txt

Reads a subscription group by its group ID. Returns the details of the specified subscription group.

```APIDOC
## [GET] /subscriptions/groups/{group_id}

### Description
Reads a subscription group by its group ID. Returns the details of the specified subscription group.

### Method
GET

### Endpoint
/subscriptions/groups/{group_id}

### Parameters
#### Path Parameters
- **group_id** (string) - Required - The subscription group identifier.

### Response
#### Success Response (200)
- **data** (object) - The subscription group details.
```

--------------------------------

### GET /services/{service}/plans

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Lists all plans associated with a specific service. Use the service identifier from the catalog discovery.

```APIDOC
## [GET] /services/{service}/plans

### Description
List the plans for a given service.

### Method
GET

### Endpoint
/services/{service}/plans

### Parameters
#### Path Parameters
- **service** (string) - Required - The service identifier.

#### Query Parameters
- **page** (integer) - Optional - Page number for pagination.
- **per_page** (integer) - Optional - Number of items per page (default 25, max 100).

### Request Example
```bash
curl "$KOMASHI_API_BASE/services/{service}/plans?page=1&per_page=25" \
  -H "Authorization: Bearer $KOMASHI_API_KEY" \
  -H 'Accept: application/json'
```

### Response
#### Success Response (200)
- **succeeded** (boolean) - Indicates if the request succeeded.
- **status_code** (integer) - HTTP status code.
- **data** (array) - List of plans.
- **links** (object) - Pagination links (if present).
- **meta** (object) - Pagination metadata (if present).

#### Response Example
```json
{
  "succeeded": true,
  "status_code": 200,
  "data": []
}
```
```

--------------------------------

### GET /subscriptions/groups/{group_id}

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Reads a subscription group.

```APIDOC
## [GET] /subscriptions/groups/{group_id}

### Description
Reads a subscription group.

### Method
GET

### Endpoint
/subscriptions/groups/{group_id}

### Parameters
#### Path Parameters
- **group_id** (string) - Required - The group identifier.
```

--------------------------------

### GET /subscriptions/{subscription_id}

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Reads a single subscription.

```APIDOC
## [GET] /subscriptions/{subscription_id}

### Description
Reads a single subscription.

### Method
GET

### Endpoint
/subscriptions/{subscription_id}

### Parameters
#### Path Parameters
- **subscription_id** (string) - Required - The subscription identifier.
```

--------------------------------

### GET /invoices/{invoice_id}

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Reads a single invoice record.

```APIDOC
## [GET] /invoices/{invoice_id}

### Description
Reads a single invoice record.

### Method
GET

### Endpoint
/invoices/{invoice_id}

### Parameters
#### Path Parameters
- **invoice_id** (string) - Required - The invoice identifier.
```

--------------------------------

### Embed Service Picker widget

Source: https://komashi.com/docs/provider/Developers/widget-integration/index

Place this script in your HTML where the widget should appear. Replace YOUR_SERVICE_ID with an actual service ID from the REST API or another trusted Komashi resource; the generated example contains a placeholder and copying it without replacement does not connect your service. Use the script host generated by your own environment, not the local komashi-app.test address.

```html
<script
  src="https://komashi.com/widget/embed.js"
  data-komashi-widget
  data-service-id="YOUR_SERVICE_ID"
  data-view="service-picker"
></script>
```

--------------------------------

### GET /services/{service}

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Retrieves details for a specific service. Use the service identifier obtained from the list services endpoint.

```APIDOC
## [GET] /services/{service}

### Description
Get one service by its identifier.

### Method
GET

### Endpoint
/services/{service}

### Parameters
#### Path Parameters
- **service** (string) - Required - The service identifier.

### Request Example
```bash
curl "$KOMASHI_API_BASE/services/{service}" \
  -H "Authorization: Bearer $KOMASHI_API_KEY" \
  -H 'Accept: application/json'
```

### Response
#### Success Response (200)
- **succeeded** (boolean) - Indicates if the request succeeded.
- **status_code** (integer) - HTTP status code.
- **data** (object) - The service resource.

#### Response Example
```json
{
  "succeeded": true,
  "status_code": 200,
  "data": {}
}
```
```

--------------------------------

### GET /services/{service}/plans/{plan_id}/periods

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Lists the billing periods for a specific plan. Use the plan identifier from the plans list.

```APIDOC
## [GET] /services/{service}/plans/{plan_id}/periods

### Description
List a plan's periods.

### Method
GET

### Endpoint
/services/{service}/plans/{plan_id}/periods

### Parameters
#### Path Parameters
- **service** (string) - Required - The service identifier.
- **plan_id** (string) - Required - The plan identifier.

#### Query Parameters
- **page** (integer) - Optional - Page number for pagination.
- **per_page** (integer) - Optional - Number of items per page (default 25, max 100).

### Request Example
```bash
curl "$KOMASHI_API_BASE/services/{service}/plans/{plan_id}/periods?page=1&per_page=25" \
  -H "Authorization: Bearer $KOMASHI_API_KEY" \
  -H 'Accept: application/json'
```

### Response
#### Success Response (200)
- **succeeded** (boolean) - Indicates if the request succeeded.
- **status_code** (integer) - HTTP status code.
- **data** (array) - List of periods.
- **links** (object) - Pagination links (if present).
- **meta** (object) - Pagination metadata (if present).

#### Response Example
```json
{
  "succeeded": true,
  "status_code": 200,
  "data": []
}
```
```

--------------------------------

### GET /subscriptions/groups/{group_id}/usage

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Reads the current usage for a group of subscriptions. Use this endpoint to check group-level usage.

```APIDOC
## GET /subscriptions/groups/{group_id}/usage

### Description
Reads the current usage for a group of subscriptions. Use this endpoint to check group-level usage.

### Method
GET

### Endpoint
`/subscriptions/groups/{group_id}/usage`

### Parameters
#### Path Parameters
- **group_id** (string) - Required - The ID of the group.

### Response
#### Success Response (200)
- **usage** (number) - The current usage amount.

#### Response Example
```json
{
  "usage": 125
}
```
```

--------------------------------

### Webhook JSON envelope

Source: https://komashi.com/docs/provider/Settings/11webhooks/index

The JSON envelope contains the event name, timestamp, and a data object with the event-specific resource payload. The data fields vary by event; the example omits them intentionally.

```json
{
  "event": "customers.update",
  "timestamp": "2026-10-22T10:00:00+00:00",
  "data": {}
}
```

--------------------------------

### GET /subscriptions/{subscription_id}/usage

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Reads the current usage for a specific subscription. Use this endpoint before relying on an allowance to ensure you have the latest usage data.

```APIDOC
## GET /subscriptions/{subscription_id}/usage

### Description
Reads the current usage for a specific subscription. Use this endpoint before relying on an allowance to ensure you have the latest usage data.

### Method
GET

### Endpoint
`/subscriptions/{subscription_id}/usage`

### Parameters
#### Path Parameters
- **subscription_id** (string) - Required - The ID of the subscription.

### Response
#### Success Response (200)
- **usage** (number) - The current usage amount.

#### Response Example
```json
{
  "usage": 125
}
```
```

--------------------------------

### POST /subscriptions/{subscription_id}/change-plan

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Requests a plan change using the target configuration.

```APIDOC
## [POST] /subscriptions/{subscription_id}/change-plan

### Description
Requests a plan change using the target configuration.

### Method
POST

### Endpoint
/subscriptions/{subscription_id}/change-plan

### Parameters
#### Path Parameters
- **subscription_id** (string) - Required - The subscription identifier.
```

--------------------------------

### POST /services/{service}/subscriptions

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Creates a subscription checkout for a customer. Sends a JSON request body with customer and plan identifiers, and returns a checkout URL and subscription details.

```APIDOC
## [POST] /services/{service}/subscriptions

### Description
Creates a subscription checkout for a customer. Sends a JSON request body with customer and plan identifiers, and returns a checkout URL and subscription details.

### Method
POST

### Endpoint
/services/{service}/subscriptions

### Parameters
#### Path Parameters
- **service** (string) - Required - The service identifier.

#### Request Body
- **customer_id** (string) - Required - The customer UUID.
- **plan_id** (string) - Required - The plan UUID.
- **period_id** (string) - Required - The period UUID.
- **quantity** (integer) - Required - The quantity of the subscription.
- **external_reference** (string) - Optional - Your internal order reference.
- **return_url** (string) - Required - The URL to return the customer to after checkout.
- **cancel_url** (string) - Required - The URL to return the customer to if checkout is cancelled.

### Request Example
{
  "customer_id": "CUSTOMER_UUID",
  "plan_id": "PLAN_UUID",
  "period_id": "PERIOD_UUID",
  "quantity": 1,
  "external_reference": "your-internal-order-reference",
  "return_url": "https://your-app.example/subscription/return",
  "cancel_url": "https://your-app.example/subscription/cancel"
}

### Response
#### Success Response (200)
- **data** (object) - Contains checkout_url, subscription_id, group_id, and created subscription items.

#### Response Example
{
  "data": {
    "checkout_url": "https://checkout.example.com/...",
    "subscription_id": "SUBSCRIPTION_UUID",
    "group_id": "GROUP_UUID",
    "items": []
  }
}
```

--------------------------------

### Webhook Delivery Format

Source: https://komashi.com/docs/provider/Settings/11webhooks/index

Describes the format of webhook delivery requests, including headers and JSON envelope structure.

```APIDOC
## Webhook Delivery Format

### Description
Webhook deliveries are HTTP POST requests sent to your configured endpoint. They include specific headers and a JSON envelope containing event information.

### Headers
- **Content-Type**: `application/json`
- **X-Webhook-Event**: The event type (e.g., `customers.update`)
- **X-Signature**: Hex-encoded HMAC-SHA256 signature of the raw request body

### Request Body
- **event** (string) - The event type (e.g., `customers.update`)
- **timestamp** (string) - ISO 8601 timestamp of the event
- **data** (object) - Event-specific resource payload. Fields vary by event; test payloads are examples and not a complete schema. Reconcile the current resource through the API for authoritative state.

### Request Example
```json
{
  "event": "customers.update",
  "timestamp": "2026-10-22T10:00:00+00:00",
  "data": {}
}
```
```

--------------------------------

### Paginated List Request with curl

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Paginated list operations accept page and per_page parameters. Default page size is 25, maximum is 100. Preserve pagination information such as links and meta when present.

```bash
curl "$KOMASHI_API_BASE/customers?page=1&per_page=25" \
  -H "Authorization: Bearer $KOMASHI_API_KEY" \
  -H 'Accept: application/json'
```

--------------------------------

### Authenticate a request with curl

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Send the provider key in the Authorization header and request JSON responses. The key must have the ability required by the operation; read access is sufficient for this first request.

```bash
export KOMASHI_API_BASE='https://api.komashi.com/v1'
export KOMASHI_API_KEY='YOUR_PROVIDER_API_KEY'

curl "$KOMASHI_API_BASE/services" \
  -H "Authorization: Bearer $KOMASHI_API_KEY" \
  -H 'Accept: application/json'
```

--------------------------------

### POST /subscriptions/{subscription_id}/payment-link

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Generates an available payment link for an existing subscription.

```APIDOC
## [POST] /subscriptions/{subscription_id}/payment-link

### Description
Generates an available payment link for an existing subscription.

### Method
POST

### Endpoint
/subscriptions/{subscription_id}/payment-link

### Parameters
#### Path Parameters
- **subscription_id** (string) - Required - The subscription identifier.
```

--------------------------------

### POST /subscriptions/{subscription_id}/sync-usage

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Sets the usage to a new absolute total. Send the new total in the request body.

```APIDOC
## POST /subscriptions/{subscription_id}/sync-usage

### Description
Sets the usage to a new absolute total. Send the new total in the request body.

### Method
POST

### Endpoint
`/subscriptions/{subscription_id}/sync-usage`

### Parameters
#### Path Parameters
- **subscription_id** (string) - Required - The ID of the subscription.

#### Request Body
- **usage** (number) - Required - The new absolute total usage.

### Request Example
```json
{
  "usage": 125
}
```

### Response
#### Success Response (200)
No response body is specified.
```

--------------------------------

### Service Picker with Return Destination

Source: https://komashi.com/docs/provider/Developers/widget-integration/index

Adds a return destination to the Service Picker embed. The return destination does not prove that payment succeeded. Read the subscription state when your application needs to grant access.

```html
<script
  src="https://komashi.com/widget/embed.js"
  data-komashi-widget
  data-service-id="YOUR_SERVICE_ID"
  data-view="service-picker"
  data-redirect-url="https://your-website.example/thanks"
></script>
```

--------------------------------

### General MCP endpoint

Source: https://komashi.com/docs/provider/Developers/mcp-integration/index

Use this root endpoint for the Komashi MCP server. For private or local deployments, use the configured MCP host with the same root path. Do not derive the MCP URL from the REST API endpoint or add a versioned REST path.

```text
https://mcp.komashi.com/
```

--------------------------------

### Adjust usage - POST /subscriptions/{subscription_id}/adjust-usage

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Send an increment or decrement action. Supported actions are 'increase' and 'decrease'; omitting 'value' uses 1. Repeating an adjustment applies it again, so do not blindly retry after a network timeout.

```json
{ "action": "increase", "value": 1 }
```

--------------------------------

### Webhook delivery headers

Source: https://komashi.com/docs/provider/Settings/11webhooks/index

Headers included in each webhook delivery. Content-Type is application/json, X-Webhook-Event identifies the event, and X-Signature contains the hex-encoded HMAC-SHA256 signature.

```text
Content-Type: application/json
X-Webhook-Event: customers.update
X-Signature: <hex-encoded HMAC-SHA256>
```

--------------------------------

### PATCH /subscriptions/{subscription_id}/dates

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Updates supported lifecycle dates.

```APIDOC
## [PATCH] /subscriptions/{subscription_id}/dates

### Description
Updates supported lifecycle dates.

### Method
PATCH

### Endpoint
/subscriptions/{subscription_id}/dates

### Parameters
#### Path Parameters
- **subscription_id** (string) - Required - The subscription identifier.
```

--------------------------------

### Verify Komashi Webhook Signature (JavaScript)

Source: https://komashi.com/docs/llms-full.txt

Verifies the HMAC-SHA256 signature of a Komashi webhook using the raw request body and the webhook secret. Returns false if the secret is missing or the signature is not 64 lowercase hex characters. Uses timing-safe comparison to prevent timing attacks. Pass the raw request-body buffer and reject the event if verification fails.

```javascript
export function verifyKomashiWebhook(rawBody, signature, secret) {
  if (!secret || !/^[a-f0-9]{64}$/.test(signature ?? '')) return false;
  const expected = createHmac('sha256', secret).update(rawBody).digest();
  const received = Buffer.from(signature, 'hex');
  return received.length === expected.length && timingSafeEqual(received, expected);
}
```

--------------------------------

### Versioned API endpoint

Source: https://komashi.com/docs/provider/Developers/api-integration/index

The public Komashi REST API endpoint includes the version prefix. Use the value displayed in your environment instead of adding /api or /v1 by guesswork.

```text
https://api.komashi.com/v1
```

--------------------------------

### verifyKomashiWebhook(rawBody, signature, secret)

Source: https://komashi.com/docs/provider/Settings/11webhooks/index

Verifies the HMAC-SHA256 signature of a webhook request. Returns true if the signature is valid, false otherwise.

```APIDOC
## verifyKomashiWebhook(rawBody, signature, secret)

### Description
Verifies the HMAC-SHA256 signature of a webhook request. Returns true if the signature is valid, false otherwise.

### Parameters
- **rawBody** (Buffer) - Required - The raw request body buffer from your HTTP framework.
- **signature** (string) - Required - The `X-Signature` header value (hex-encoded HMAC-SHA256).
- **secret** (string) - Required - The webhook's secret (must be supplied securely; API key cannot replace it).

### Returns
- **boolean** - `true` if the signature is valid, `false` otherwise.

### Usage
Pass your HTTP framework's raw request-body buffer to this function. Reject a failed signature before processing the event.

### Example
```js
import { createHmac, timingSafeEqual } from 'crypto';

export function verifyKomashiWebhook(rawBody, signature, secret) {
  if (!secret || !/^[a-f0-9]{64}$/.test(signature ?? '')) return false;
  const expected = createHmac('sha256', secret).update(rawBody).digest();
  const received = Buffer.from(signature, 'hex');
  return received.length === expected.length && timingSafeEqual(received, expected);
}
```
```

--------------------------------

### Embed Subscription Details

Source: https://komashi.com/docs/provider/Developers/widget-integration/index

Renders the subscription ID for the customer who is entitled to see that subscription. Use an individual subscription ID, not its group ID. The widget derives the service and provider from that subscription. A customer ID is not a substitute for the required subscription ID.

```html
<script
  src="https://komashi.com/widget/embed.js"
  data-komashi-widget
  data-subscription-id="YOUR_SUBSCRIPTION_ID"
  data-view="subscription-details"
></script>
```

--------------------------------

### Create subscription checkout request body

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Illustrative JSON body for POST /services/{service}/subscriptions. Replace every identifier with a real value from your provider. Send with Content-Type: application/json.

```json
{
  "customer_id": "CUSTOMER_UUID",
  "plan_id": "PLAN_UUID",
  "period_id": "PERIOD_UUID",
  "quantity": 1,
  "external_reference": "your-internal-order-reference",
  "return_url": "https://your-app.example/subscription/return",
  "cancel_url": "https://your-app.example/subscription/cancel"
}
```

--------------------------------

### DELETE /subscriptions/{subscription_id}/cancel

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Cancels a subscription or a pending plan change.

```APIDOC
## [DELETE] /subscriptions/{subscription_id}/cancel

### Description
Cancels a subscription or a pending plan change.

### Method
DELETE

### Endpoint
/subscriptions/{subscription_id}/cancel

### Parameters
#### Path Parameters
- **subscription_id** (string) - Required - The subscription identifier.
```

--------------------------------

### POST /subscriptions/{subscription_id}/adjust-usage

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Adjusts the usage by an increment or decrement. Send an action and an optional value in the request body.

```APIDOC
## POST /subscriptions/{subscription_id}/adjust-usage

### Description
Adjusts the usage by an increment or decrement. Send an action and an optional value in the request body.

### Method
POST

### Endpoint
`/subscriptions/{subscription_id}/adjust-usage`

### Parameters
#### Path Parameters
- **subscription_id** (string) - Required - The ID of the subscription.

#### Request Body
- **action** (string) - Required - The action to perform. Supported values: `increase`, `decrease`.
- **value** (number) - Optional - The amount to adjust by. Defaults to 1 if omitted.

### Request Example
```json
{
  "action": "increase",
  "value": 1
}
```

### Response
#### Success Response (200)
No response body is specified.
```

--------------------------------

### Sync usage - POST /subscriptions/{subscription_id}/sync-usage

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Send the new absolute total usage value. The request body must contain the 'usage' field with the total.

```json
{ "usage": 125 }
```

--------------------------------

### PATCH /subscriptions/{subscription_id}/status

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Updates the status and optional renewal setting.

```APIDOC
## [PATCH] /subscriptions/{subscription_id}/status

### Description
Updates the status and optional renewal setting.

### Method
PATCH

### Endpoint
/subscriptions/{subscription_id}/status

### Parameters
#### Path Parameters
- **subscription_id** (string) - Required - The subscription identifier.
```

--------------------------------

### Verify webhook signature with HMAC-SHA256

Source: https://komashi.com/docs/provider/Settings/11webhooks/index

Verifies the webhook signature against the raw request body using the webhook's secret. Returns false if the secret is missing or the signature is not 64 lowercase hex characters. Uses timing-safe comparison to prevent timing attacks. Requires the secret to be supplied securely; an API key cannot replace it.

```js


export function verifyKomashiWebhook(rawBody, signature, secret) {
  if (!secret || !/^[a-f0-9]{64}$/.test(signature ?? '')) return false;
  const expected = createHmac('sha256', secret).update(rawBody).digest();
  const received = Buffer.from(signature, 'hex');
  return received.length === expected.length && timingSafeEqual(received, expected);
}

```

--------------------------------

### Read JSON Response Common Fields

Source: https://komashi.com/docs/provider/Developers/api-integration/index

Responses include common fields: succeeded, status_code, and data. data contains the result and can be a resource, array, checkout result, or null. Additional fields like message, errors, links, and meta may appear; endpoint-specific errors can include error or code fields.

```json
{
  "succeeded": true,
  "status_code": 200,
  "data": []
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.