### GET /customers

Source: https://komashi.com/api-docs/spec

API endpoint for GET /customers

```markdown
### Parameters

- **page** (integer, query, optional): Pagination page number. Minimum: 1.
- **per_page** (integer, query, optional): Items per page. Minimum: 1, maximum: 100, default: 25.

### Responses

#### 200 - Customers

- Array of Customer

#### 401 - Unauthenticated

Unauthenticated

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/customers?page=1&per_page=25"
```

```

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

### GET /services/{service_id}/addons

Source: https://komashi.com/api-docs/spec

API endpoint for GET /services/{service_id}/addons

```markdown
### Parameters

- **service_id** (string (uuid), path, required): UUID of the service
- **page** (integer, query, optional): Pagination page number. Minimum: 1.
- **per_page** (integer, query, optional): Items per page. Minimum: 1, maximum: 100, default: 25.

### Responses

#### 200 - List of addons

- Array of ServiceAddon

#### 401 - Unauthenticated

Unauthenticated

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/services/{service_id}/addons?page=1&per_page=25"
```

```

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

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

Source: https://komashi.com/api-docs/spec

API endpoint for GET /services/{service_id}/addons/{addon_id}/options

```markdown
### Parameters

- **service_id** (string (uuid), path, required): UUID of the service
- **addon_id** (string (uuid), path, required): UUID of the service addon
- **page** (integer, query, optional): Pagination page number. Minimum: 1.
- **per_page** (integer, query, optional): Items per page. Minimum: 1, maximum: 100, default: 25.

### Responses

#### 200 - List of addon options

- Array of ServiceAddonOption

#### 401 - Unauthenticated

Unauthenticated

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/services/{service_id}/addons/{addon_id}/options?page=1&per_page=25"
```

```

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

### GET /services/{service_id}/addons/{addon_id}/options/{option_id}

Source: https://komashi.com/api-docs/spec

API endpoint for GET /services/{service_id}/addons/{addon_id}/options/{option_id}

```markdown
### Parameters

- **service_id** (string (uuid), path, required): UUID of the service
- **addon_id** (string (uuid), path, required): UUID of the service addon
- **option_id** (string (uuid), path, required): Service Addon Option UUID

### Responses

#### 200 - Addon option

**ServiceAddonOption**
- **option_id** (string (uuid))
- **addon_id** (string (uuid))
- **provider_id** (string (uuid))
- **service_id** (string (uuid))
- **limit_value** (number (float)): Positive measurable usage quota; null means no quota.
- **limit_label** (string): Human-readable usage unit for limit_value.
- **full_limit_label** (string)
- **description** (string)
- **reset_usage_on_renewal** (boolean): When enabled, usage resets to 0 at the start of each billing period.
- **cap_per_customer** (integer): Max total quantity per customer across all subscriptions. 0 = unlimited
- **activation_date** (string (date))
- **expiration_date** (string (date))

#### 401 - Unauthenticated

Unauthenticated

#### 404 - Not found

Not found

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/services/{service_id}/addons/{addon_id}/options/{option_id}"
```

```

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

### GET /services/{service_id}/plans

Source: https://komashi.com/api-docs/spec

API endpoint for GET /services/{service_id}/plans

```markdown
### Parameters

- **service_id** (string (uuid), path, required): UUID of the service
- **page** (integer, query, optional): Pagination page number. Minimum: 1.
- **per_page** (integer, query, optional): Items per page. Minimum: 1, maximum: 100, default: 25.

### Responses

#### 200 - List of plans

- Array of ServicePlan

#### 401 - Unauthenticated

Unauthenticated

#### 404 - Service not found

Service not found

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/services/{service_id}/plans?page=1&per_page=25"
```

```

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

### GET /services

Source: https://komashi.com/api-docs/spec

API endpoint for GET /services

```markdown
### Parameters

- **page** (integer, query, optional): Pagination page number. Minimum: 1.
- **per_page** (integer, query, optional): Items per page. Minimum: 1, maximum: 100, default: 25.

### Responses

#### 200 - List of services

- Array of Service

#### 401 - Unauthenticated

Unauthenticated

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/services?page=1&per_page=25"
```

```

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

### GET /services/{service_id}/addons/{addon_id}

Source: https://komashi.com/api-docs/spec

API endpoint for GET /services/{service_id}/addons/{addon_id}

```markdown
### Parameters

- **service_id** (string (uuid), path, required): UUID of the service
- **addon_id** (string (uuid), path, required): UUID of the service addon

### Responses

#### 200 - Addon data

**ServiceAddon**
- **addon_id** (string (uuid))
- **provider_id** (string (uuid))
- **service_id** (string (uuid))
- **name** (string)
- **description** (string)
- **is_one_time** (boolean)
- **is_required** (boolean)
- **cap_per_customer** (integer): Max total quantity per customer across all subscriptions. 0 = unlimited
- **activation_date** (string (date))
- **expiration_date** (string (date))
- **created_at** (string (date-time))
- **updated_at** (string (date-time))

#### 401 - Unauthenticated

Unauthenticated

#### 404 - Addon not found

Addon not found

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/services/{service_id}/addons/{addon_id}"
```

```

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

### GET /invoices

Source: https://komashi.com/api-docs/spec

API endpoint for GET /invoices

```markdown
### Parameters

- **page** (integer, query, optional): Pagination page number. Minimum: 1.
- **per_page** (integer, query, optional): Items per page. Minimum: 1, maximum: 100, default: 25.
- **customer_id** (string (uuid), query, optional)
- **invoice_number** (string, query, optional)
- **created_from** (string (date), query, optional)
- **created_to** (string (date), query, optional)

### Responses

#### 200 - Invoice list

- Array of Invoice

#### 401 - Unauthenticated

Unauthenticated

#### 422 - Validation error

Validation error

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/invoices?page=1&per_page=25&customer_id=string&invoice_number=string&created_from=2023-01-01&created_to=2023-01-01"
```

```

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

### GET /services/{service_id}/plans/{plan_id}

Source: https://komashi.com/api-docs/spec

API endpoint for GET /services/{service_id}/plans/{plan_id}

```markdown
### Parameters

- **service_id** (string (uuid), path, required): UUID of the service
- **plan_id** (string (uuid), path, required): UUID of the plan (service type)

### Responses

#### 200 - Plan details

**ServicePlan**
- **plan_id** (string (uuid))
- **service_id** (string (uuid))
- **name** (string)
- **description** (string)
- **current_service_period_id** (string (uuid)): UUID of the current active period. For one-time services, this is the current expiration term period.
- **activation_date** (string (date))
- **expiration_date** (string (date))
- **created_at** (string (date-time))
- **updated_at** (string (date-time))

#### 401 - Unauthenticated

Unauthenticated

#### 404 - Service or Plan not found

Service or Plan not found

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/services/{service_id}/plans/{plan_id}"
```

```

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

### GET /customers/{customer_id}

Source: https://komashi.com/api-docs/spec

API endpoint for GET /customers/{customer_id}

```markdown
### Parameters

- **customer_id** (string (uuid), path, required): UUID of the customer

### Responses

#### 200 - Customer

**Customer**
- **customer_id** (string (uuid))
- **provider_id** (string (uuid))
- **note** (string)
- **vat_number** (string)
- **vat_type** (string (NO_TAX_NUMBER|HAS_TAX_NUMBER|FOREIGN)) ("NO_TAX_NUMBER"|"HAS_TAX_NUMBER"|"FOREIGN")
- **billing_name** (string)
- **billing_country** (string)
- **billing_state** (string): Required only for countries configured in billing.state_required_countries.
- **billing_city** (string)
- **billing_zip** (string)
- **billing_address** (string)
- **billing_address_2** (string)
- **customer_external_data** (object) (example: {"ext_pref_plan":"Premium","ext_seats":5})
- **created_at** (string (date-time))
- **updated_at** (string (date-time))

#### 401 - Unauthenticated

Unauthenticated

#### 404 - Customer not found

Customer not found

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/customers/{customer_id}"
```

```

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

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

Source: https://komashi.com/api-docs/spec

Returns coupon discount templates configured for the authenticated provider. Providers can compose discounts in the admin interface, then use the returned discount_id values when creating subscriptions through the API.

```markdown
### Parameters

- **service_id** (string (uuid), path, required): UUID of the service
- **page** (integer, query, optional): Pagination page number. Minimum: 1.
- **per_page** (integer, query, optional): Items per page. Minimum: 1, maximum: 100, default: 25.

### Responses

#### 200 - List of provider coupon discounts

- Array of Discount

#### 401 - Unauthorized

Unauthorized

#### 403 - Forbidden

Forbidden

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/services/{service_id}/service-prices/discounts?page=1&per_page=25"
```

```

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

### GET /subscriptions/{subscription_id}

Source: https://komashi.com/api-docs/spec

Returns one subscription record. A plan change creates a new target draft record, while the source subscription is the current integration anchor and receives the new plan content after successful payment.

```markdown
### Parameters

- **subscription_id** (string (uuid), path, required): UUID of the subscription

### Responses

#### 200 - Subscription

**Subscription**
- **subscription_id** (string (uuid)): Stable subscription identifier. During a paid plan change the source subscription remains the integration anchor and receives the target plan content.
- **group_id** (string (uuid)): UUID of the subscription group this subscription belongs to
- **parent_id** (string (uuid))
- **provider_id** (string (uuid))
- **customer_id** (string (uuid))
- **service_id** (string (uuid))
- **plan_id** (string (uuid))
- **period_id** (string (uuid))
- **addon_id** (string (uuid))
- **option_id** (string (uuid))
- **price_id** (string (uuid))
- **discount_id** (string (uuid)): Discount applied to this subscription record. Plan-change targets may contain the transition discount.
- **quantity** (integer)
- **current_usage** (number (float))
- **usage_percentage** (number (float))
- **is_limit_reached** (boolean)
- **remaining_quota** (number (float))
- **is_draft** (boolean): Draft or archived lifecycle record. Plan-change targets are normally drafts; do not use a draft as the current active subscription.
- **is_renewable** (boolean): Whether the subscription renews. Cancellation sets this to false while access may remain available until end_date.
- **status** (string (PENDING|ACTIVE|EXPIRED|ENDED)) ("PENDING"|"ACTIVE"|"EXPIRED"|"ENDED")
- **start_date** (string (date))
- **renewal_date** (string (date))
- **end_date** (string (date))
- **public_note** (string)
- **admin_note** (string)
- **external_reference** (string)
- **upgrade_id** (string (uuid)): On a source subscription, ID of the pending upgrade target. Cleared after the change is completed or cancelled.
- **downgrade_id** (string (uuid)): On a source subscription, ID of the pending downgrade target. Cleared after the change is completed or cancelled.
- **upgrade_info** (array (object))
  Array items:
    - **id** (string (uuid)) (required)
    - **new** (string)
    - **old** (string)
    - **attribute** (string)
- **created_at** (string (date-time))
- **updated_at** (string (date-time))

#### 401 - Unauthenticated

Unauthenticated

#### 404 - Not found

Not found

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/subscriptions/{subscription_id}"
```

```

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

### GET /services/{service_id}

Source: https://komashi.com/api-docs/spec

API endpoint for GET /services/{service_id}

```markdown
### Parameters

- **service_id** (string (uuid), path, required): UUID of the service

### Responses

#### 200 - Service details

**Service**
- **service_id** (string (uuid))
- **name** (string)
- **short_name** (string)
- **description** (string)
- **language** (string)
- **enable_multiple_subscribe** (boolean)
- **enable_customer_edit** (boolean)
- **is_self_service** (boolean)
- **currency** (string)
- **billing_type** (string (recurring|one_time)) ("recurring"|"one_time")
- **is_required** (boolean)
- **activation_date** (string (date))
- **expiration_date** (string (date))
- **external_data_top** (array (ExternalField))
  Array items:
    - **id** (string (uuid)) (required)
    - **type** (string (text|number|select)) (required) ("text"|"number"|"select")
    - **label** (string) (required)
    - **required** (boolean) (required)
    - **visibility** (string (user_can|user_can_not)) (required) ("user_can"|"user_can_not")
    - **access_control** (string (editable_once|editable_always)) (required) ("editable_once"|"editable_always")
    - **rules** (object)
      - **min** (number)
      - **max** (number)
    - **options** (array (string))
- **external_data_bottom** (array (ExternalField))
  Array items:
- **created_at** (string (date-time))
- **updated_at** (string (date-time))

#### 401 - Unauthenticated

Unauthenticated

#### 404 - Service not found

Service not found

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/services/{service_id}"
```

```

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

### GET /customers/{customer_id}/contacts/{contact_id}

Source: https://komashi.com/api-docs/spec

API endpoint for GET /customers/{customer_id}/contacts/{contact_id}

```markdown
### Parameters

- **customer_id** (string (uuid), path, required): UUID of the customer
- **contact_id** (string (uuid), path, required): Customer Contact ID

### Responses

#### 200 - Contact

**CustomerContact**
- **contact_id** (string (uuid))
- **customer_id** (string (uuid))
- **provider_id** (string (uuid))
- **name** (string)
- **email** (string)
- **phone** (string)
- **whatsapp** (string)
- **viber** (string)
- **note** (string)
- **contact_settings** (object)
  - **email** (object) (required)
    - **is_visible** (boolean) (required)
    - **is_enabled** (boolean) (required)
  - **phone** (object) (required)
  - **whatsapp** (object) (required)
  - **viber** (object) (required)
- **created_at** (string (date-time))
- **updated_at** (string (date-time))

#### 401 - Unauthenticated

Unauthenticated

#### 404 - Not found

Not found

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/customers/{customer_id}/contacts/{contact_id}"
```

```

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

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

Source: https://komashi.com/api-docs/spec

API endpoint for GET /subscriptions/groups/{group_id}

```markdown
### Parameters

- **group_id** (string (uuid), path, required): UUID of the subscription group

### Responses

#### 200 - Subscription group data

**SubscriptionGroup**
- **group_id** (string (uuid))
- **billing_type** (string (recurring|one_time)) ("recurring"|"one_time")
- **service** (object)
  - **id** (string (uuid))
  - **name** (string)
- **subscriptions** (array (object))
  Array items:
    - **type** (string (parent|addon|purchase)) ("parent"|"addon"|"purchase")
    - **subscription_id** (string (uuid))
    - **plan_id** (string (uuid))
    - **period_id** (string (uuid))
    - **addon_id** (string (uuid))
    - **quantity** (integer)
    - **status** (string)
    - **start_date** (string (date-time))
    - **end_date** (string (date-time))
    - **current_usage** (number (float))
    - **addon_option** (object)
      - **id** (string (uuid))
      - **name** (string)
      - **limit_value** (number (float))
      - **limit_label** (string)
- **aggregate** (object)
  - **total_limit** (number (float))
  - **total_usage** (number (float))
  - **remaining** (number (float))
  - **earliest_end_date** (string (date-time))
  - **latest_end_date** (string (date-time))
  - **overall_status** (string)

#### 401 - Unauthenticated

Unauthenticated

#### 404 - Group not found

Group not found

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/subscriptions/groups/{group_id}"
```

```

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

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

Source: https://komashi.com/api-docs/spec

API endpoint for GET /subscriptions/{subscription_id}/usage

```markdown
### Parameters

- **subscription_id** (string (uuid), path, required): UUID of the subscription

### Responses

#### 200 - Usage status

**SubscriptionUsage**
- **subscription_id** (string (uuid))
- **is_reached** (boolean)
- **remaining** (number (float))
- **limit** (number (float))
- **usage** (number (float))
- **label** (string)
- **message** (string)

#### 401 - Unauthenticated

Unauthenticated

#### 404 - Not found

Not found

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/subscriptions/{subscription_id}/usage"
```

```

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

### GET /invoices/{invoice_id}

Source: https://komashi.com/api-docs/spec

API endpoint for GET /invoices/{invoice_id}

```markdown
### Parameters

- **invoice_id** (string (uuid), path, required)

### Responses

#### 200 - Invoice

**Invoice**
- **invoice_id** (string (uuid))
- **external_invoice_id** (string)
- **invoice_number** (string)
- **customer_id** (string (uuid))
- **invoice_method_id** (string (uuid))
- **total** (number (float))
- **currency** (string)
- **payment_method** (string)
- **download_url** (string (uri))
- **subscription_ids** (array (string (uuid)))
- **created_at** (string (date-time))
- **updated_at** (string (date-time))

#### 401 - Unauthenticated

Unauthenticated

#### 404 - Not found

Not found

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/invoices/{invoice_id}"
```

```

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

### GET /services/{service_id}/subscriptions

Source: https://komashi.com/api-docs/spec

Returns the complete subscription history matching the filters, including non-draft subscriptions and plan-change draft records. Integrations should use customer_id to resync every record after a plan change, then select the current non-draft subscription.

```markdown
### Parameters

- **service_id** (string (uuid), path, required): UUID of the service
- **page** (integer, query, optional): Pagination page number. Minimum: 1.
- **per_page** (integer, query, optional): Items per page. Minimum: 1, maximum: 100, default: 25.
- **external_reference** (string, query, optional): Provider-defined subscription reference.
- **status** (string (PENDING|ACTIVE|EXPIRED|ENDED), query, optional)
- **customer_id** (string (uuid), query, optional)
- **plan_id** (string (uuid), query, optional)
- **period_id** (string (uuid), query, optional)
- **addon_id** (string (uuid), query, optional)
- **option_id** (string (uuid), query, optional)
- **start_date_from** (string (date), query, optional)
- **start_date_to** (string (date), query, optional)
- **end_date_from** (string (date), query, optional)
- **end_date_to** (string (date), query, optional)
- **renewal_date_from** (string (date), query, optional)
- **renewal_date_to** (string (date), query, optional)
- **expires_before** (string (date), query, optional)
- **expires_after** (string (date), query, optional)
- **created_from** (string (date), query, optional)
- **created_to** (string (date), query, optional)

### Responses

#### 200 - List

- Array of Subscription

#### 401 - Unauthenticated

Unauthenticated

#### 422 - Validation error

Validation error

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/services/{service_id}/subscriptions?page=1&per_page=25&external_reference=string&status=PENDING&customer_id=string&plan_id=string&period_id=string&addon_id=string&option_id=string&start_date_from=2023-01-01&start_date_to=2023-01-01&end_date_from=2023-01-01&end_date_to=2023-01-01&renewal_date_from=2023-01-01&renewal_date_to=2023-01-01&expires_before=2023-01-01&expires_after=2023-01-01&created_from=2023-01-01&created_to=2023-01-01"
```

```

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

### GET /services/{service_id}/plans/{plan_id}/periods/{period_id}

Source: https://komashi.com/api-docs/spec

API endpoint for GET /services/{service_id}/plans/{plan_id}/periods/{period_id}

```markdown
### Parameters

- **service_id** (string (uuid), path, required): UUID of the service
- **plan_id** (string (uuid), path, required): UUID of the plan (service type)
- **period_id** (string (uuid), path, required): UUID of the period

### Responses

#### 200 - Period

**ServicePeriod**
- **period_id** (string (uuid))
- **interval** (integer)
- **interval_type** (string (year|month|week|day)) ("year"|"month"|"week"|"day")
- **trial_interval** (integer)
- **trial_interval_type** (string (year|month|week|day)) ("year"|"month"|"week"|"day")
- **description** (string)
- **activation_date** (string (date))
- **expiration_date** (string (date))
- **created_at** (string (date-time))
- **updated_at** (string (date-time))

#### 401 - Unauthenticated

Unauthenticated

#### 404 - Not found

Not found

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/services/{service_id}/plans/{plan_id}/periods/{period_id}"
```

```

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

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

Source: https://komashi.com/api-docs/spec

API endpoint for GET /services/{service_id}/plans/{plan_id}/periods

```markdown
### Parameters

- **service_id** (string (uuid), path, required): UUID of the service
- **plan_id** (string (uuid), path, required): UUID of the plan (service type)
- **page** (integer, query, optional): Pagination page number. Minimum: 1.
- **per_page** (integer, query, optional): Items per page. Minimum: 1, maximum: 100, default: 25.

### Responses

#### 200 - List of periods

- Array of ServicePeriod

#### 401 - Unauthenticated

Unauthenticated

#### 404 - Plan not found

Plan not found

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/services/{service_id}/plans/{plan_id}/periods?page=1&per_page=25"
```

```

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

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

Source: https://komashi.com/api-docs/spec

Creates a new target subscription record for the requested change. The source subscription receives i_upgrade or i_downgrade pointing to that target. The target contains the requested plan, addon and discount and is normally a PENDING draft until checkout succeeds. After successful payment, the source subscription remains the stable integration ID and is updated with the new plan content; the target becomes historical/draft. Always resync the source and target records after payment or webhook delivery.

```markdown
### Parameters

- **subscription_id** (string (uuid), path, required): UUID of the subscription

### Request Body

**Content-Type:** application/json

- **service_id** (string (uuid)) (required)
- **plan_id** (string (uuid)) (required)
- **period_id** (string (uuid)) (required)
- **discount_id** (string (uuid))
- **quantity** (integer) (required)
- **public_note** (string)
- **admin_note** (string)
- **external_reference** (string)
- **return_url** (string (uri)) (required)
- **cancel_url** (string (uri)) (required)
- **addons** (array (object))
  Array items:
    - **addon_id** (string (uuid)) (required)
    - **option_id** (string (uuid))
    - **discount_id** (string (uuid))
    - **quantity** (integer)
    - **public_note** (string)
    - **admin_note** (string)

### Responses

#### 200 - Plan change created

**SubscriptionChangePlanResponse**
- **detected_change_type** (string (upgrade|downgrade|modify)): Change detected by comparing the source and requested target values. ("upgrade"|"downgrade"|"modify")
- **requires_checkout** (boolean): Whether the target must be paid before it becomes effective.
- **source_subscription** (object)
  - **subscription_id** (string (uuid)): Stable subscription identifier. During a paid plan change the source subscription remains the integration anchor and receives the target plan content.
  - **group_id** (string (uuid)): UUID of the subscription group this subscription belongs to
  - **parent_id** (string (uuid))
  - **provider_id** (string (uuid))
  - **customer_id** (string (uuid))
  - **service_id** (string (uuid))
  - **plan_id** (string (uuid))
  - **period_id** (string (uuid))
  - **addon_id** (string (uuid))
  - **option_id** (string (uuid))
  - **price_id** (string (uuid))
  - **discount_id** (string (uuid)): Discount applied to this subscription record. Plan-change targets may contain the transition discount.
  - **quantity** (integer)
  - **current_usage** (number (float))
  - **usage_percentage** (number (float))
  - **is_limit_reached** (boolean)
  - **remaining_quota** (number (float))
  - **is_draft** (boolean): Draft or archived lifecycle record. Plan-change targets are normally drafts; do not use a draft as the current active subscription.
  - **is_renewable** (boolean): Whether the subscription renews. Cancellation sets this to false while access may remain available until end_date.
  - **status** (string (PENDING|ACTIVE|EXPIRED|ENDED)) ("PENDING"|"ACTIVE"|"EXPIRED"|"ENDED")
  - **start_date** (string (date))
  - **renewal_date** (string (date))
  - **end_date** (string (date))
  - **public_note** (string)
  - **admin_note** (string)
  - **external_reference** (string)
  - **upgrade_id** (string (uuid)): On a source subscription, ID of the pending upgrade target. Cleared after the change is completed or cancelled.
  - **downgrade_id** (string (uuid)): On a source subscription, ID of the pending downgrade target. Cleared after the change is completed or cancelled.
  - **upgrade_info** (array (object))
    Array items:
      - **id** (string (uuid)) (required)
      - **new** (string)
      - **old** (string)
      - **attribute** (string)
  - **created_at** (string (date-time))
  - **updated_at** (string (date-time))
- **target_subscriptions** (array (Subscription)): New target subscription records created for the requested plan change. These are normally PENDING drafts and may contain a transition discount.
  Array items:
- **checkout_url** (string)
- **magic_url** (string)

#### 401 - Unauthenticated

Unauthenticated

#### 403 - Forbidden

Forbidden

#### 404 - Not found

Not found

#### 409 - Plan change already in progress

Plan change already in progress

#### 422 - Validation error

Validation error

### Example Usage

```bash
curl -X POST "https://api.komashi.com/v1/subscriptions/{subscription_id}/change-plan" \
  -H "Content-Type: application/json" \
  -d '{
  "service_id": "string",
  "plan_id": "string",
  "period_id": "string",
  "discount_id": "string",
  "quantity": "0",
  "public_note": "string",
  "admin_note": "string",
  "external_reference": "string",
  "return_url": "string",
  "cancel_url": "string",
  "addons": [
    {
      "addon_id": "string",
      "option_id": "string",
      "discount_id": "string",
      "quantity": "0",
      "public_note": "string",
      "admin_note": "string"
    }
  ]
}'
```

```

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

### Schema: CustomerCreate

Source: https://komashi.com/api-docs/spec

Schema definition for CustomerCreate

```markdown
## Schema: CustomerCreate

Schema definition for CustomerCreate

**Type:** object

- **billing_name** (string) (required)
- **billing_address** (string) (required)
- **billing_address_2** (string)
- **billing_zip** (string) (required)
- **billing_city** (string) (required)
- **billing_country** (string) (required)
- **billing_state** (string): Required only for countries configured in billing.state_required_countries.
- **vat_number** (string)
- **note** (string)
- **contact_email** (string (email))
- **contact_phone** (string)
- **customer_external_data** (object) (example: {"ext_pref_plan":"Premium","ext_seats":5})

```

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

### Schema: SubscriptionCreate

Source: https://komashi.com/api-docs/spec

Schema definition for SubscriptionCreate

```markdown
## Schema: SubscriptionCreate

Schema definition for SubscriptionCreate

**Type:** object

- **customer_id** (string (uuid)) (required)
- **plan_id** (string (uuid)) (required)
- **period_id** (string (uuid)) (required)
- **discount_id** (string (uuid))
- **quantity** (integer) (required)
- **public_note** (string)
- **admin_note** (string)
- **external_reference** (string)
- **return_url** (string (uri)) (required)
- **cancel_url** (string (uri)) (required)
- **addons** (array (object))
  Array items:
    - **addon_id** (string (uuid)) (required)
    - **option_id** (string (uuid))
    - **discount_id** (string (uuid))
    - **quantity** (integer)
    - **public_note** (string)
    - **admin_note** (string)

```

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

### Schema: CustomerContactCreate

Source: https://komashi.com/api-docs/spec

Schema definition for CustomerContactCreate

```markdown
## Schema: CustomerContactCreate

Schema definition for CustomerContactCreate

**Type:** object

- **name** (string) (required)
- **email** (string)
- **phone** (string)
- **whatsapp** (string)
- **viber** (string)
- **note** (string)
- **contact_settings** (object) (required)
  - **email** (object) (required)
    - **is_visible** (boolean) (required)
    - **is_enabled** (boolean) (required)
  - **phone** (object) (required)
  - **whatsapp** (object) (required)
  - **viber** (object) (required)

```

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

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

Source: https://komashi.com/api-docs/spec

API endpoint for GET /subscriptions/groups/{group_id}/usage

```markdown
### Parameters

- **group_id** (string (uuid), path, required): UUID of the subscription group

### Responses

#### 200 - Group usage data

**SubscriptionGroupUsage**
- **subscriptions** (array (SubscriptionUsage))
  Array items:
    - **subscription_id** (string (uuid))
    - **is_reached** (boolean)
    - **remaining** (number (float))
    - **limit** (number (float))
    - **usage** (number (float))
    - **label** (string)
    - **message** (string)
- **total_usage** (number (float))
- **total_limit** (number (float))
- **total_remaining** (number (float))
- **group_id** (string (uuid))

#### 401 - Unauthenticated

Unauthenticated

#### 404 - Group not found

Group not found

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/subscriptions/groups/{group_id}/usage"
```

```

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

### GET /customers/{customer_id}/contacts

Source: https://komashi.com/api-docs/spec

API endpoint for GET /customers/{customer_id}/contacts

```markdown
### Parameters

- **customer_id** (string (uuid), path, required): UUID of the customer
- **page** (integer, query, optional): Pagination page number. Minimum: 1.
- **per_page** (integer, query, optional): Items per page. Minimum: 1, maximum: 100, default: 25.

### Responses

#### 200 - List of contacts

- Array of CustomerContact

#### 401 - Unauthenticated

Unauthenticated

### Example Usage

```bash
curl -X GET "https://api.komashi.com/v1/customers/{customer_id}/contacts?page=1&per_page=25"
```

```

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

### Schema: Customer

Source: https://komashi.com/api-docs/spec

Schema definition for Customer

```markdown
## Schema: Customer

Schema definition for Customer

**Type:** object

- **customer_id** (string (uuid))
- **provider_id** (string (uuid))
- **note** (string)
- **vat_number** (string)
- **vat_type** (string (NO_TAX_NUMBER|HAS_TAX_NUMBER|FOREIGN)) ("NO_TAX_NUMBER"|"HAS_TAX_NUMBER"|"FOREIGN")
- **billing_name** (string)
- **billing_country** (string)
- **billing_state** (string): Required only for countries configured in billing.state_required_countries.
- **billing_city** (string)
- **billing_zip** (string)
- **billing_address** (string)
- **billing_address_2** (string)
- **customer_external_data** (object) (example: {"ext_pref_plan":"Premium","ext_seats":5})
- **created_at** (string (date-time))
- **updated_at** (string (date-time))

```

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

### Schema: ServiceAddon

Source: https://komashi.com/api-docs/spec

Schema definition for ServiceAddon

```markdown
## Schema: ServiceAddon

Schema definition for ServiceAddon

**Type:** object

- **addon_id** (string (uuid))
- **provider_id** (string (uuid))
- **service_id** (string (uuid))
- **name** (string)
- **description** (string)
- **is_one_time** (boolean)
- **is_required** (boolean)
- **cap_per_customer** (integer): Max total quantity per customer across all subscriptions. 0 = unlimited
- **activation_date** (string (date))
- **expiration_date** (string (date))
- **created_at** (string (date-time))
- **updated_at** (string (date-time))

```

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

### Schema: SubscriptionChangePlanResponse

Source: https://komashi.com/api-docs/spec

Schema definition for SubscriptionChangePlanResponse

```markdown
## Schema: SubscriptionChangePlanResponse

Schema definition for SubscriptionChangePlanResponse

**Type:** object

- **detected_change_type** (string (upgrade|downgrade|modify)): Change detected by comparing the source and requested target values. ("upgrade"|"downgrade"|"modify")
- **requires_checkout** (boolean): Whether the target must be paid before it becomes effective.
- **source_subscription** (object)
  - **subscription_id** (string (uuid)): Stable subscription identifier. During a paid plan change the source subscription remains the integration anchor and receives the target plan content.
  - **group_id** (string (uuid)): UUID of the subscription group this subscription belongs to
  - **parent_id** (string (uuid))
  - **provider_id** (string (uuid))
  - **customer_id** (string (uuid))
  - **service_id** (string (uuid))
  - **plan_id** (string (uuid))
  - **period_id** (string (uuid))
  - **addon_id** (string (uuid))
  - **option_id** (string (uuid))
  - **price_id** (string (uuid))
  - **discount_id** (string (uuid)): Discount applied to this subscription record. Plan-change targets may contain the transition discount.
  - **quantity** (integer)
  - **current_usage** (number (float))
  - **usage_percentage** (number (float))
  - **is_limit_reached** (boolean)
  - **remaining_quota** (number (float))
  - **is_draft** (boolean): Draft or archived lifecycle record. Plan-change targets are normally drafts; do not use a draft as the current active subscription.
  - **is_renewable** (boolean): Whether the subscription renews. Cancellation sets this to false while access may remain available until end_date.
  - **status** (string (PENDING|ACTIVE|EXPIRED|ENDED)) ("PENDING"|"ACTIVE"|"EXPIRED"|"ENDED")
  - **start_date** (string (date))
  - **renewal_date** (string (date))
  - **end_date** (string (date))
  - **public_note** (string)
  - **admin_note** (string)
  - **external_reference** (string)
  - **upgrade_id** (string (uuid)): On a source subscription, ID of the pending upgrade target. Cleared after the change is completed or cancelled.
  - **downgrade_id** (string (uuid)): On a source subscription, ID of the pending downgrade target. Cleared after the change is completed or cancelled.
  - **upgrade_info** (array (object))
    Array items:
      - **id** (string (uuid)) (required)
      - **new** (string)
      - **old** (string)
      - **attribute** (string)
  - **created_at** (string (date-time))
  - **updated_at** (string (date-time))
- **target_subscriptions** (array (Subscription)): New target subscription records created for the requested plan change. These are normally PENDING drafts and may contain a transition discount.
  Array items:
- **checkout_url** (string)
- **magic_url** (string)

```

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

### Schema: Subscription

Source: https://komashi.com/api-docs/spec

Schema definition for Subscription

```markdown
## Schema: Subscription

Schema definition for Subscription

**Type:** object

- **subscription_id** (string (uuid)): Stable subscription identifier. During a paid plan change the source subscription remains the integration anchor and receives the target plan content.
- **group_id** (string (uuid)): UUID of the subscription group this subscription belongs to
- **parent_id** (string (uuid))
- **provider_id** (string (uuid))
- **customer_id** (string (uuid))
- **service_id** (string (uuid))
- **plan_id** (string (uuid))
- **period_id** (string (uuid))
- **addon_id** (string (uuid))
- **option_id** (string (uuid))
- **price_id** (string (uuid))
- **discount_id** (string (uuid)): Discount applied to this subscription record. Plan-change targets may contain the transition discount.
- **quantity** (integer)
- **current_usage** (number (float))
- **usage_percentage** (number (float))
- **is_limit_reached** (boolean)
- **remaining_quota** (number (float))
- **is_draft** (boolean): Draft or archived lifecycle record. Plan-change targets are normally drafts; do not use a draft as the current active subscription.
- **is_renewable** (boolean): Whether the subscription renews. Cancellation sets this to false while access may remain available until end_date.
- **status** (string (PENDING|ACTIVE|EXPIRED|ENDED)) ("PENDING"|"ACTIVE"|"EXPIRED"|"ENDED")
- **start_date** (string (date))
- **renewal_date** (string (date))
- **end_date** (string (date))
- **public_note** (string)
- **admin_note** (string)
- **external_reference** (string)
- **upgrade_id** (string (uuid)): On a source subscription, ID of the pending upgrade target. Cleared after the change is completed or cancelled.
- **downgrade_id** (string (uuid)): On a source subscription, ID of the pending downgrade target. Cleared after the change is completed or cancelled.
- **upgrade_info** (array (object))
  Array items:
    - **id** (string (uuid)) (required)
    - **new** (string)
    - **old** (string)
    - **attribute** (string)
- **created_at** (string (date-time))
- **updated_at** (string (date-time))

```

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

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

Source: https://komashi.com/api-docs/spec

API endpoint for POST /subscriptions/{subscription_id}/payment-link

```markdown
### Parameters

- **subscription_id** (string (uuid), path, required): UUID of the subscription

### Request Body

**Content-Type:** application/json

- **return_url** (string (uri)) (required)
- **cancel_url** (string (uri)) (required)

### Responses

#### 200 - Payment URL created

- **data** (object)
  - **checkout_url** (string (uri))

#### 401 - Unauthenticated

Unauthenticated

#### 404 - Subscription not found

Subscription not found

#### 422 - Subscription is not payable

Subscription is not payable

### Example Usage

```bash
curl -X POST "https://api.komashi.com/v1/subscriptions/{subscription_id}/payment-link" \
  -H "Content-Type: application/json" \
  -d '{
  "return_url": "string",
  "cancel_url": "string"
}'
```

```

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

### Security: sanctum

Source: https://komashi.com/api-docs/spec

Add meg a Bearer tokenedet az Authorization fejlécben. Példa: Bearer <token>

```markdown
## Security: sanctum

**Description:** Add meg a Bearer tokenedet az Authorization fejlécben. Példa: Bearer <token>

**Type:** http

**Scheme:** bearer

**Bearer Format:** JWT


```

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

### Schema: ContactChannelSettings

Source: https://komashi.com/api-docs/spec

Schema definition for ContactChannelSettings

```markdown
## Schema: ContactChannelSettings

Schema definition for ContactChannelSettings

**Type:** object

- **is_visible** (boolean) (required)
- **is_enabled** (boolean) (required)

```

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

### Schema: SubscriptionSyncUsage

Source: https://komashi.com/api-docs/spec

Schema definition for SubscriptionSyncUsage

```markdown
## Schema: SubscriptionSyncUsage

Schema definition for SubscriptionSyncUsage

**Type:** object

- **usage** (number (float)) (required)

```

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

### Schema: PaginationMeta

Source: https://komashi.com/api-docs/spec

Schema definition for PaginationMeta

```markdown
## Schema: PaginationMeta

Schema definition for PaginationMeta

**Type:** object

- **current_page** (integer)
- **per_page** (integer)
- **total** (integer)
- **last_page** (integer)

```