Hyperline

https://docs.hyperline.co/
Admin
Hyperline is an all-in-one platform to manage CPQ, billing, usage-based pricing, and revenue...
Tokens:1,061,040
Snippets:7,004
Trust Score:7.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Get Product

Source: https://docs.hyperline.co/llms.txt

Retrieve the details of an existing product. Only the first 50 price configurations are returned, to retrieve all of them use `GET /v1/price-configurations`.

```APIDOC
## Get Product

### Description
Retrieve the details of an existing product. Only the first 50 price configurations are returned, to retrieve all of them use `GET /v1/price-configurations`.

### Method
GET

### Endpoint
/v1/products/{product_id}

### Parameters
#### Path Parameters
- **product_id** (string) - Required - The ID of the product to retrieve.
```

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

### Retrieve Subscription Details

Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions/get-subscription

This example demonstrates how to get the details of a subscription by its ID.

```APIDOC
## GET /subscriptions/{subscriptionId}

### Description
Retrieves the details of a specific subscription.

### Method
GET

### Endpoint
/subscriptions/{subscriptionId}

### Parameters
#### Path Parameters
- **subscriptionId** (string) - Required - The unique identifier of the subscription.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the subscription.
- **status** (string) - The current status of the subscription (e.g., 'active', 'canceled', 'past_due').
- **planId** (string) - The identifier of the subscription plan.
- **startDate** (string) - The date the subscription started (ISO 8601 format).
- **endDate** (string) - The date the subscription ends or will end (ISO 8601 format).

#### Response Example
```json
{
  "id": "sub_123abc",
  "status": "active",
  "planId": "plan_xyz789",
  "startDate": "2023-10-27T10:00:00Z",
  "endDate": "2024-10-27T10:00:00Z"
}
```
```

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

### Create Subscription from Products

Source: https://docs.hyperline.co/docs/subscriptions/create

This example shows how to create a subscription by specifying a list of products, their quantities, and activation details.

```APIDOC
## Create Subscription from Products

### Description
Creates a new subscription for a customer by defining a list of products, their quantities, payment intervals, and activation strategies.

### Method
POST

### Endpoint
/v2/subscriptions

### Request Body
- **customer_id** (string) - Required - The ID of the customer for whom the subscription is created.
- **starts_at** (string) - Optional - The date and time when the subscription should start (ISO 8601 format).
- **activation_strategy** (string) - Optional - Strategy for activating the subscription (e.g., "start_date").
- **payment_method_strategy** (string) - Optional - Strategy for selecting the payment method (e.g., "current").
- **products** (array) - Required - A list of products to include in the subscription.
  - **id** (string) - Required - The ID of the product.
  - **payment_interval** (object) - Required - Defines the payment frequency.
    - **period** (string) - Required - The period for the payment interval (e.g., "months").
  - **count** (integer) - Optional - The number of items for this product.

### Request Example
```json
{
  "customer_id": "cus_3PYD5R2q5NFK5E",
  "starts_at": "2025-12-20T00:00:00Z",
  "activation_strategy": "start_date",
  "payment_method_strategy": "current",
  "products": [
    {
      "id": "itm_4vea8Gj0a5HZr9",
      "payment_interval": { "period": "months" }
    },
    {
      "id": "itm_vBBCZSTR6NzzuL",
      "payment_interval": { "period": "months" },
      "count": 2
    }
  ]
}
```

### Response
#### Success Response (200)
- **subscription** (object) - Details of the created subscription.

#### Response Example
```json
{
  "subscription": {
    "id": "sub_example_id_2",
    "customer_id": "cus_3PYD5R2q5NFK5E",
    "starts_at": "2025-12-20T00:00:00Z",
    "activation_strategy": "start_date",
    "status": "pending",
    "created_at": "2023-10-27T10:05:00Z"
  }
}
```
```

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

### Convert Local Time to UTC for Subscriptions

Source: https://docs.hyperline.co/api-reference/docs/dates-and-timezones

When creating subscriptions, convert the desired local start time to UTC. The examples show conversions for Paris time, accounting for daylight saving.

```javascript
// Example 1: January 1st, 2024 at 00:00 Paris time
// Paris is UTC+1 in winter, so we need to convert to UTC (23:00 previous day)
"2023-12-31T23:00:00Z"
```

```javascript
// Example 2: July 1st, 2024 at 00:00 Paris time
// Paris is UTC+2 in summer (due to daylight saving), so we need to convert to UTC (22:00 previous day)
"2024-06-30T22:00:00Z"
```

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

### Create Subscription Transition with Full Configuration

Source: https://docs.hyperline.co/guides/bulk-update-subscriptions

Initiate a subscription transition by providing the full target subscription configuration. This method offers granular control over billing and application schedules, suitable for complex updates. The example shows an immediate transition that keeps the current billing cycle and does not charge.

```sh
curl -X POST "https://api.hyperline.co/v2/subscriptions/transitions" \
  -H "Authorization: Bearer <API key>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_subscription_id": "sub_xxx",
    "application_schedule": "immediately",
    "billing_cycle_transition_method": "keep_current_billing_cycle",
    "calculation_method": "do_not_charge",
    "target_subscription": {
      "phases": [
        {
          "products": [
            ...
          ],
          ...
        }
      ],
      ... // Existing subscription payload
    }
  }'
```

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

### Install Hyperline CLI

Source: https://docs.hyperline.co/api-reference/docs/ai/cli

Install the Hyperline CLI globally using npm. Verify the installation by checking the version.

```bash
npm install -g @hyperline/cli
```

```bash
hyperline --version
```

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

### Create Subscription with Coupon

Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions/create-subscription

This snippet shows how to create a subscription and apply a coupon. It includes examples of different coupon types (amount, percent) and frequency settings (once, forever, custom, duration).

```APIDOC
## POST /subscriptions

### Description
Creates a new subscription for a customer, with options to apply coupons for discounts.

### Method
POST

### Endpoint
/subscriptions

### Parameters
#### Request Body
- **customer_id** (string) - Required - The ID of the customer subscribing.
- **plan_id** (string) - Required - The ID of the subscription plan.
- **coupon** (object) - Optional - Details of the coupon to apply.
  - **type** (string) - Required - The type of coupon ('amount' or 'percent').
  - **amount** (object) - Required if type is 'amount'. Details for an amount-based coupon.
    - **discount_amount** (number) - Required - The amount to discount, in the currency's smallest unit.
    - **name** (string) - Optional - The name of the coupon.
  - **percent** (object) - Required if type is 'percent'. Details for a percentage-based coupon.
    - **discount_percent** (number) - Required - The discount percentage (0-100).
    - **name** (string) - Optional - The name of the coupon.
  - **repeat** (string) - Optional - The frequency of the coupon application ('once', 'forever', 'custom', 'duration').
  - **duration_period** (string) - Optional - The period for 'duration' frequency ('days', 'weeks', 'months', 'years').
  - **duration_count** (number) - Optional - The number of periods for 'duration' frequency.
  - **expires_at** (string) - Optional - The expiration date for 'custom' frequency (ISO 8601 format).
  - **apply_at** (string) - Optional - The date for the first coupon application (ISO 8601 format).

### Request Example
```json
{
  "customer_id": "cus_12345",
  "plan_id": "plan_abcde",
  "coupon": {
    "type": "percent",
    "percent": {
      "discount_percent": 10,
      "name": "SUMMER10"
    },
    "repeat": "forever"
  }
}
```

### Response
#### Success Response (200)
- **subscription_id** (string) - The ID of the created subscription.
- **status** (string) - The status of the subscription.
- **coupon_applied** (object) - Details of the coupon applied, if any.
  - **type** (string) - Type of the applied coupon.
  - **discount_amount** (number) - Discount amount if applicable.
  - **discount_percent** (number) - Discount percentage if applicable.
  - **repeat** (string) - Frequency of the coupon.

#### Response Example
```json
{
  "subscription_id": "sub_xyz789",
  "status": "active",
  "coupon_applied": {
    "type": "percent",
    "discount_percent": 10,
    "repeat": "forever"
  }
}
```
```

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

### Get Product Details

Source: https://docs.hyperline.co/api-reference/endpoints/products/get-product

Retrieves the details of a specific product. By default, it returns the first 50 price configurations. To get all price configurations, use the `GET /v1/price-configurations` endpoint.

```APIDOC
## GET /v1/products/{productId}

### Description
Retrieve the details of an existing product. Only the first 50 price configurations are returned, to retrieve all of them use `GET /v1/price-configurations`.

### Method
GET

### Endpoint
/v1/products/{productId}

### Parameters
#### Path Parameters
- **productId** (string) - Required - The unique identifier of the product.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the product.
- **name** (string) - The name of the product.
- **description** (string) - A description of the product.
- **price_configurations** (array) - A list of price configurations for the product (limited to the first 50).
  - **id** (string) - The unique identifier of the price configuration.
  - **price** (number) - The price of the product configuration.
  - **currency** (string) - The currency of the price.
  - **created_at** (string) - The timestamp when the price configuration was created.
  - **updated_at** (string) - The timestamp when the price configuration was last updated.

#### Response Example
```json
{
  "id": "prod_123",
  "name": "Example Product",
  "description": "This is an example product.",
  "price_configurations": [
    {
      "id": "price_abc",
      "price": 99.99,
      "currency": "USD",
      "created_at": "2023-01-01T12:00:00Z",
      "updated_at": "2023-01-01T12:00:00Z"
    }
  ]
}
```
```

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

### Create Subscription from Template

Source: https://docs.hyperline.co/docs/subscriptions/create

This example demonstrates how to create a new subscription using a pre-defined template for a specific customer.

```APIDOC
## Create Subscription from Template

### Description
Creates a new subscription based on a provided template ID for a given customer.

### Method
POST

### Endpoint
/v2/subscriptions

### Request Body
- **customer_id** (string) - Required - The ID of the customer for whom the subscription is created.
- **template_id** (string) - Required - The ID of the subscription template to use.

### Request Example
```json
{
  "customer_id": "cus_3PYD5R2q5NFK5E",
  "template_id": "subt_7gdusOkqr5L0B8"
}
```

### Response
#### Success Response (200)
- **subscription** (object) - Details of the created subscription.

#### Response Example
```json
{
  "subscription": {
    "id": "sub_example_id",
    "customer_id": "cus_3PYD5R2q5NFK5E",
    "template_id": "subt_7gdusOkqr5L0B8",
    "status": "active",
    "created_at": "2023-10-27T10:00:00Z"
  }
}
```
```

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

### Create Subscription with Price Override

Source: https://docs.hyperline.co/docs/subscriptions/create

This example demonstrates how to create a subscription and override the price for a specific flat-fee product.

```APIDOC
## POST /v2/subscriptions

### Description
Creates a new subscription for a customer. Allows overriding prices for `flat_fee` products.

### Method
POST

### Endpoint
https://api.hyperline.co/v2/subscriptions

### Request Body
- **customer_id** (string) - Required - The ID of the customer.
- **starts_at** (string) - Required - The start date and time for the subscription.
- **activation_strategy** (string) - Required - The strategy for activating the subscription (e.g., `start_date`).
- **payment_method_strategy** (string) - Required - The strategy for handling payment methods (e.g., `current`).
- **products** (array) - Required - A list of products to include in the subscription.
  - **id** (string) - Required - The ID of the product.
  - **payment_interval** (object) - Required - The interval for payments.
    - **period** (string) - Required - The payment period (e.g., `months`).
  - **price** (object) - Optional - Overrides the default price for the product.
    - **type** (string) - Required - The type of price (e.g., `fee`).
    - **amount** (integer) - Required - The custom price amount.
  - **count** (integer) - Optional - The number of times the product should be billed.

### Request Example
```json
{
  "customer_id": "cus_3PYD5R2q5NFK5E",
  "starts_at": "2023-12-20T00:00:00Z",
  "activation_strategy": "start_date",
  "payment_method_strategy": "current",
  "products": [
    {
      "id": "itm_4vea8Gj0a5HZr9",
      "payment_interval": { "period": "months" },
      "price": { "type": "fee", "amount": 1234 }
    },
    {
      "id": "itm_vBBCZSTR6NzzuL",
      "payment_interval": { "period": "months" },
      "count": 2
    }
  ]
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the created subscription.
- **customer_id** (string) - The ID of the customer.
- **starts_at** (string) - The start date and time of the subscription.
- **status** (string) - The current status of the subscription.
- **products** (array) - The list of products included in the subscription.
  - **id** (string) - The ID of the product.
  - **price** (object) - The price details of the product.
    - **type** (string) - The type of price.
    - **amount** (integer) - The amount of the price.

#### Response Example
```json
{
  "id": "sub_abc123xyz",
  "customer_id": "cus_3PYD5R2q5NFK5E",
  "starts_at": "2023-12-20T00:00:00Z",
  "status": "active",
  "products": [
    {
      "id": "itm_4vea8Gj0a5HZr9",
      "price": {
        "type": "fee",
        "amount": 1234
      }
    },
    {
      "id": "itm_vBBCZSTR6NzzuL",
      "price": {
        "type": "fee",
        "amount": 500
      }
    }
  ]
}
```
```

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

### Install React Components Package

Source: https://docs.hyperline.co/api-reference/docs/react-components

Install the `@hyperline/react-components` NPM package using npm.

```sh
npm install @hyperline/react-components
```

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

### Get Invoice (v1)

Source: https://docs.hyperline.co/llms.txt

Retrieves the details of an existing invoice. Note: The `GET /v2/invoices/{id}` endpoint is recommended.

```APIDOC
## Get Invoice (v1)

### Description
We recommend using the `GET /v2/invoices/{id}` endpoint instead.

### Method
GET

### Endpoint
/v1/invoices/{id}
```

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

### Create Subscription Transition

Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions-%3E-transitions/create-subscription-transition

Transition a subscription to another subscription, configured from a subscription, a plan or a template. If the application_schedule is `immediately`, the transition is applied right away.

```APIDOC
## POST /v2/subscriptions/transitions

### Description
Transition a subscription to another subscription, configured from a subscription, a plan or a template. If the application_schedule is `immediately`, the transition is applied right away.

### Method
POST

### Endpoint
/v2/subscriptions/transitions

### Parameters
#### Request Body
- **source_subscription_id** (string) - Required - The ID of the subscription to transition from
- **name** (string) - Optional - An optional name for the transition
- **calculation_method** (string) - Optional - The calculation method to use for the transition. 'do_not_charge' will not generate any transition invoice. 'pro_rata' will generate a prorated invoice for the remaining period. Enum: `do_not_charge`, `pro_rata`
- **billing_cycle_transition_method** (string) - Optional - The billing cycle transition method to use. 'keep_current_billing_cycle' will keep the current billing cycle dates if possible. 'align_to_new_billing_cycle' will align the billing cycle to the transition date. Enum: `keep_current_billing_cycle`, `align_to_new_billing_cycle`
- **application_schedule** (string) - Optional - Whether the transition should be applied 'immediately' or 'scheduled' for a specific date. Past dates within the current billing period are supported and will be applied immediately. Enum: `scheduled`, `immediately`
- **transition_date** (string) - Optional - The date at which the transition should occur. Only applicable if the application schedule is 'scheduled'. Can be a past date within the current billing period. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
- **target_subscription** (object) - Optional - Details of the target subscription.
  - **name** (string) - Optional - Subscription custom name.
  - **purchase_order** (string) - Optional - Reference to the purchase order.
  - **invoicing_entity_id** (string) - Optional - ID of the invoicing entity attached to the subscription. If not defined, fallback to customer's invoicing entity.
  - **crm_opportunity_id** (string) - Optional - ID of the related opportunity/deal in the connected CRM.
  - **commitment_interval** (object) - Optional - Deprecated field, please use `contract_terms`.
    - **period** (string) - Required - Enum: `days`, `weeks`, `months`, `years`
    - **count** (number) - Required - Minimum: 1
  - **renew_for** (object) - Optional

### Request Example
{
  "example": "{\"source_subscription_id\": \"sub_123\", \"name\": \"Upgrade to Pro\", \"calculation_method\": \"pro_rata\", \"billing_cycle_transition_method\": \"align_to_new_billing_cycle\", \"application_schedule\": \"immediately\", \"transition_date\": \"2024-12-20T16:04:11Z\", \"target_subscription\": { \"name\": \"Pro Plan\", \"invoicing_entity_id\": \"ive_jerrb484RHn\", \"crm_opportunity_id\": \"opp_abcde\" }}" 
}

### Response
#### Success Response (200)
- **field1** (type) - Description

#### Response Example
{
  "example": "response body"
}
```

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

### Create Product

Source: https://docs.hyperline.co/api-reference/endpoints/products/create-product

This section outlines the parameters for creating a product. It includes fields for internal and public descriptions, availability flags, custom properties, accounting details, and bundle configurations.

```APIDOC
## POST /products

### Description
Creates a new product with specified details, pricing, and bundle configurations.

### Method
POST

### Endpoint
/products

### Request Body
- **description** (string) - Optional - Product internal description.
- **description_display_interval_dates** (boolean) - Optional - Indicates if the dates of the interval should be automatically added in the product description on the invoices.
- **public_description** (string | null) - Optional - Public description of the product.
- **translations** (object | null) - Optional - Product name and description translations. Accepts an object where keys are language codes and values contain `name` and `public_description`.
- **is_available_on_demand** (boolean) - Optional - Defaults to true. Indicates if the product is available on demand.
- **is_available_on_subscription** (boolean) - Optional - Defaults to true. Indicates if the product is available via subscription.
- **custom_properties** (object) - Optional - A list of key value pairs for custom properties.
- **accounting** (object) - Optional - Accounting details for the product. See `ProductAccounting` schema.
- **type** (string) - Optional - Product type, e.g., 'bundle'.
- **display_mode** (string) - Optional - How bundle items are displayed on invoices. Enum: `single_line`, `ventilated`.
- **exclusive_items_enabled** (boolean) - Optional - Defaults to false. When true, only one item in the bundle can be active at a time.
- **bundle_items** (array) - Optional - Products included in this bundle. Percentages must sum to 100. See `CreateBundleProductItem` schema.
- **price_configurations** (array) - Optional - Pricing configurations for the product. See schema for details on currency and price.

### Request Example
```json
{
  "description": "Product internal description",
  "public_description": "Product public description",
  "is_available_on_demand": true,
  "is_available_on_subscription": false,
  "custom_properties": {
    "internal_code": "PROD-123"
  },
  "type": "bundle",
  "bundle_items": [
    {
      "product_id": "prod_abc",
      "percentage": 50
    },
    {
      "product_id": "prod_def",
      "percentage": 50
    }
  ],
  "price_configurations": [
    {
      "currency": "EUR",
      "price": 10000
    }
  ]
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created product.
- **name** (string) - The name of the product.
- **description** (string) - The internal description of the product.
- **public_description** (string | null) - The public description of the product.
- **is_available_on_demand** (boolean) - Indicates if the product is available on demand.
- **is_available_on_subscription** (boolean) - Indicates if the product is available via subscription.

#### Response Example
```json
{
  "id": "prod_xyz",
  "name": "Example Product",
  "description": "Product internal description",
  "public_description": "Product public description",
  "is_available_on_demand": true,
  "is_available_on_subscription": false
}
```
```

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

### April 2, 2026 - Customer Segment Field Added

Source: https://docs.hyperline.co/api-reference/docs/upgrades

The `Customer.segment_ids` field has been added to the `/v1/customers` GET and GET /{id} endpoints.

```APIDOC
## API Changes - April 2, 2026

### Field Additions

*   Added `Customer.segment_ids` on `/v1/customers` GET and `/v1/customers/{id}` GET endpoints.
```

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

### Create Product

Source: https://docs.hyperline.co/api-reference/endpoints/products/create-product

Use this endpoint to create a new product with specified pricing and billing configurations.

```APIDOC
## POST /products

### Description
Creates a new product with associated pricing and billing configurations.

### Method
POST

### Endpoint
/products

### Request Body
- **currency** (string) - Required - The currency for the product pricing.
- **billing_interval** (object) - Required - The billing interval configuration.
  - **period** (string) - Required - The period of the billing interval (e.g., weeks, months, years).
  - **count** (number) - Required - The number of periods in the billing interval.
- **type** (string) - Required - The type of the product (e.g., volume).
- **prices** (array) - Required - An array of price tiers for the product.
  - **type** (string) - Required - The type of price tier (e.g., volume).
  - **amount** (number) - Required - The price amount.
  - **from** (number) - Required - The starting quantity for this price tier.
  - **to** (number) - Optional - The ending quantity for this price tier.
  - **on_bucket_incomplete** (string) - Optional - How to handle incomplete buckets (e.g., pro_rata, pay_in_full, do_not_charge). Defaults to 'pro_rata'.
  - **unit_count** (number) - Optional - The unit count for this price tier. Defaults to 1.
- **metering_filter** (object) - Optional - A filter to scope eligible billable events.
  - **name** (string) - Required - Name of the metering filter.
  - **configuration** (object) - Required - The configuration for the metering filter.

### Request Example
```json
{
  "currency": "USD",
  "billing_interval": {
    "period": "months",
    "count": 1
  },
  "type": "volume",
  "prices": [
    {
      "type": "volume",
      "amount": 0.1,
      "from": 0,
      "to": 1000,
      "on_bucket_incomplete": "pro_rata",
      "unit_count": 1
    }
  ],
  "metering_filter": {
    "name": "API Calls",
    "configuration": {
      "type": "event",
      "event_name": "api_call"
    }
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created product.
- **currency** (string) - The currency of the product.
- **billing_interval** (object) - The billing interval configuration.
- **type** (string) - The type of the product.
- **prices** (array) - The price tiers of the product.
- **metering_filter** (object) - The metering filter configuration.

#### Response Example
```json
{
  "id": "prod_12345",
  "currency": "USD",
  "billing_interval": {
    "period": "months",
    "count": 1
  },
  "type": "volume",
  "prices": [
    {
      "type": "volume",
      "amount": 0.1,
      "from": 0,
      "to": 1000,
      "on_bucket_incomplete": "pro_rata",
      "unit_count": 1
    }
  ],
  "metering_filter": {
    "name": "API Calls",
    "configuration": {
      "type": "event",
      "event_name": "api_call"
    }
  }
}
```
```

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

### Get Product by ID

Source: https://docs.hyperline.co/api-reference/endpoints/products/get-product

Retrieve the details of an existing product. Only the first 50 price configurations are returned, to retrieve all of them use `GET /v1/price-configurations`.

```APIDOC
## GET /v1/products/{id}

### Description
Retrieve the details of an existing product. Only the first 50 price configurations are returned, to retrieve all of them use `GET /v1/price-configurations`.

### Method
GET

### Endpoint
/v1/products/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the product to retrieve.

#### Query Parameters
- **price_book_id** (string) - Optional - The ID of the price book to use for pricing information.

### Response
#### Success Response (200)
- **Product** (object) - The product details.

#### Response Example
{
  "example": "{\"id\": \"itm_3kXODDF42QXtnL\", \"name\": \"Product name\", \"status\": \"active\", \"description\": \"Product internal description\", \"description_display_interval_dates\": false, \"public_description\": \"Product public description\", \"translations\": null, \"properties\": null, \"custom_properties\": {}, \"accounting\": { \"revenue_recognition_type\": \"none\", \"revenue_recognition_ এজency\": \"none\", \"revenue_recognition_schedule\": \"none\", \"invoice_timing\": \"immediate\", \"credit_card_transaction_type\": \"none\", \"credit_card_transaction_ এজency\": \"none\", \"credit_card_transaction_schedule\": \"none\" }, \"type\": \"flat_fee\", \"is_available_on_demand\": false}"
}
```

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

### February 10, 2026 - Wallet Endpoint Update and Deprecation

Source: https://docs.hyperline.co/api-reference/docs/upgrades

Introduces a new `/v2/wallets` GET endpoint and deprecates the `/v1/wallets` GET endpoint.

```APIDOC
## API Changes - February 10, 2026

### New Endpoint

*   `GET /v2/wallets`

### Deprecation Warning

*   Deprecating `/v1/wallets` GET endpoint.
```

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

### List All Price Configurations

Source: https://docs.hyperline.co/api-reference/endpoints/price-configurations/list-price-configurations

Fetches a list of all price configurations available in the system.

```APIDOC
## GET /price-configurations

### Description
Retrieves a list of all price configurations.

### Method
GET

### Endpoint
/price-configurations

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of price configurations to return.
- **offset** (integer) - Optional - The number of price configurations to skip before starting to collect the result set.

### Response
#### Success Response (200)
- **data** (array) - An array of price configuration objects.
  - **id** (string) - Required - Unique identifier for the price configuration.
  - **product_id** (string) - Required - Identifier of the product associated with the price configuration.
  - **price_book_id** (string) - Required - Identifier of the price book this configuration belongs to.
  - **status** (string) - Required - The current status of the price configuration (e.g., 'active', 'inactive').
  - **currency** (string) - Required - The currency code (e.g., 'USD', 'EUR').
  - **country** (string) - Required - Two-letter country code in ISO format.
  - **plan_id** (string) - Optional - ID of the plan on which this price configuration is eligible.
  - **billing_interval** (object or null) - Optional - Billing interval on which the price configuration is eligible.
    - **period** (string) - Required - The billing period ('once', 'days', 'weeks', 'months', 'years').
    - **count** (number) - Optional - The number of periods for the billing interval.
  - **commitment_interval** (object or null) - Optional - Commitment interval on which the price configuration is eligible.
    - **period** (string) - Required - The commitment period ('all', 'weeks', 'months', 'years').
    - **count** (number) - Optional - The number of periods for the commitment interval.
  - **updated_at** (string) - Required - Last edition date of the price configuration.
  - **archived_at** (string) - Optional - Date of the price configuration archival.
  - **type** (string) - Required - The type of price configuration ('bundle').
  - **allow_on_portal** (boolean) - Required - Indicates if the configuration is allowed on the portal.
  - **prices** (array) - Required - Price tiers of the price configuration.

#### Response Example
```json
{
  "data": [
    {
      "id": "price_config_123",
      "product_id": "prod_abc",
      "price_book_id": "pb_xyz",
      "status": "active",
      "currency": "USD",
      "country": "US",
      "plan_id": null,
      "billing_interval": {
        "period": "months",
        "count": 1
      },
      "commitment_interval": {
        "period": "years",
        "count": 1
      },
      "updated_at": "2023-10-27T10:00:00Z",
      "archived_at": null,
      "type": "bundle",
      "allow_on_portal": true,
      "prices": [
        {
          "type": "volume",
          "id": "price_vol_001",
          "amount": 1000,
          "unit_count": 100,
          "from": 1
        }
      ]
    }
  ]
}
```
```

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

### Example Event Payload

Source: https://docs.hyperline.co/docs/usage/send-usage-data

This is a basic example of an event payload that can be sent to the POST /events endpoint. The record object can contain various data types but not arrays of objects.

```json
{
  "customer_id": "cus_fh4585Jjrekkk",
  "timestamp": "2022-01-05 21:56:52",
  "event_type": "new_transaction",
  "record": {
    "id": 485,
    "amount": 2500
  }
}
```

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

### Create Product

Source: https://docs.hyperline.co/api-reference/endpoints/products/create-product

Use this endpoint to create a new product with specified details.

```APIDOC
## POST /products

### Description
Creates a new product in the system.

### Method
POST

### Endpoint
/products

### Request Body
- **name** (string) - Required - The name of the product.
- **description** (string) - Optional - A detailed description of the product.
- **price** (number) - Required - The price of the product.
- **currency** (string) - Required - The currency code for the product price (e.g., EUR, USD). See [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes).
- **country** (string) - Optional - The country code where the product is relevant (e.g., US, DE). See [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

### Request Example
{
  "name": "Example Product",
  "description": "A sample product for demonstration purposes.",
  "price": 19.99,
  "currency": "USD",
  "country": "US"
}

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier of the created product.
- **name** (string) - The name of the product.
- **description** (string) - The description of the product.
- **price** (number) - The price of the product.
- **currency** (string) - The currency code.
- **country** (string) - The country code.
- **createdAt** (string) - The timestamp when the product was created.

#### Response Example
{
  "id": "prod_12345abc",
  "name": "Example Product",
  "description": "A sample product for demonstration purposes.",
  "price": 19.99,
  "currency": "USD",
  "country": "US",
  "createdAt": "2023-10-27T10:00:00Z"
}
```

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

### Create Product

Source: https://docs.hyperline.co/api-reference/endpoints/products/create-product

This section details the structure for creating a new product, including its pricing configurations.

```APIDOC
## POST /products

### Description
Creates a new product with specified pricing tiers and configurations.

### Method
POST

### Endpoint
/products

### Request Body
- **id** (string) - Required - Unique identifier for the product.
- **product_id** (string) - Required - Identifier for the product.
- **price_book_id** (string | null) - Optional - ID of the price book. If null, uses the default price book.
- **status** (string) - Required - Status of the price configuration (e.g., active, archived).
- **currency** (string) - Required - Currency code for the price configuration.
- **country** (string) - Required - Country code for the price configuration.
- **plan_id** (string) - Required - ID of the associated plan.
- **billing_interval** (string) - Required - Interval for billing.
- **commitment_interval** (string) - Required - Interval for commitment.
- **updated_at** (string) - Required - Timestamp of the last update.
- **archived_at** (string) - Required - Timestamp when the price configuration was archived.
- **type** (string) - Required - Type of the price configuration.
- **metering_filter** (object) - Required - Filter for metering.
- **prices** (array) - Required - Price tiers for the product.
  - **items** (object) - Represents a single price tier.
    - **id** (string) - Required - Price configuration ID.
    - **product_id** (string) - Required - ID of the product.
    - **price_book_id** (string | null) - Optional - ID of the price book.
    - **status** (string) - Required - Price configuration status (e.g., active, archived).
    - **currency** (string) - Required - Currency code.
    - **country** (string) - Required - Country code.
    - **plan_id** (string) - Required - ID of the associated plan.
    - **billing_interval** (string) - Required - Interval for billing.
    - **commitment_interval** (string) - Required - Interval for commitment.
    - **updated_at** (string) - Required - Timestamp of the last update.
    - **archived_at** (string) - Required - Timestamp when archived.
    - **type** (string) - Required - Type of the price configuration.
    - **metering_filter** (object) - Required - Filter for metering.
    - **prices** (array) - Required - Price tiers.

### Request Example
{
  "example": "{\"id\": \"prod_123\", \"name\": \"Example Product\", \"description\": \"A sample product\", \"prices\": [{\"id\": \"price_abc\", \"product_id\": \"prod_123\", \"status\": \"active\", \"currency\": \"USD\", \"country\": \"US\", \"plan_id\": \"plan_xyz\", \"billing_interval\": \"monthly\", \"commitment_interval\": \"1y\", \"updated_at\": \"2023-10-27T10:00:00Z\", \"archived_at\": null, \"type\": \"fixed\", \"metering_filter\": {\"type\": \"none\"}, \"prices\": [{\"unit_amount\": 1000, \"unit\": \"month\"}]}]}"
}

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the created product.
- **name** (string) - Name of the product.
- **description** (string) - Description of the product.
- **prices** (array) - Pricing configurations for the product.

#### Response Example
{
  "example": "{\"id\": \"prod_123\", \"name\": \"Example Product\", \"description\": \"A sample product\", \"prices\": [{\"id\": \"price_abc\", \"product_id\": \"prod_123\", \"status\": \"active\", \"currency\": \"USD\", \"country\": \"US\", \"plan_id\": \"plan_xyz\", \"billing_interval\": \"monthly\", \"commitment_interval\": \"1y\", \"updated_at\": \"2023-10-27T10:00:00Z\", \"archived_at\": null, \"type\": \"fixed\", \"metering_filter\": {\"type\": \"none\"}, \"prices\": [{\"unit_amount\": 1000, \"unit\": \"month\"}]}]}"
}
```

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

### Example CSV File Structure

Source: https://docs.hyperline.co/docs/usage/import-events-csv

This example demonstrates the required fields and custom fields for a CSV file import. Ensure string fields are quoted and boolean fields are not.

```csv
timestamp,event_type,record/id,record/type,record/is_live,customer_id
"2023-11-07T13:59:40.536Z",api_call,1245,"paid",true,"cus_foXtwuyW7NsCH-"
"2023-11-07T13:59:40.536Z",api_call,1152,"to_pay",true,"cus_foXtwuyW7NsCH-"
"2023-11-07T13:59:40.536Z",api_call,8625,"pending",false,"cus_foXtwuyW7NsCH-"
"2023-10-18T15:53:24.772Z",api_call,9752,"closed",true,"cus_foXtwuyW7NsCH-"
"2023-10-18T15:53:24.772Z",api_call,7052,"open",true,"cus_foXtwuyW7NsCH-
```

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

### Example Custom Domain URLs

Source: https://docs.hyperline.co/docs/customers/portal

These are example URLs for your hosted portal and checkout pages when a custom domain is configured. Ensure your DNS provider has a CNAME record pointing to cname.hyperline.co.

```text
https://billing.alpeak.com/portal/:customerId
https://billing.alpeak.com/checkout/:sessionId
```

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

### Create Subscription from Products

Source: https://docs.hyperline.co/docs/subscriptions/create

Create a subscription for a customer by specifying a list of products, their payment intervals, and optional quantities. This method allows for automatic price determination based on product catalog configurations.

```sh
curl --request POST \
  --url https://api.hyperline.co/v2/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ \
    "customer_id": "cus_3PYD5R2q5NFK5E", \
    "starts_at": "2025-12-20T00:00:00Z", \
    "activation_strategy": "start_date", \
    "payment_method_strategy": "current", \
    "products": [ \
      { \
        "id": "itm_4vea8Gj0a5HZr9", \
        "payment_interval": { "period": "months" }, \
      }, \
      { \
        "id": "itm_vBBCZSTR6NzzuL", \
        "payment_interval": { "period": "months" }, \
        "count": 2, \
      }, \
    ] \
  }'
```
Tokens:
Raw