### Start subscriptions on a plan

Source: https://usagebox.com/docs

Initiate a new subscription for a customer on a specific plan. This connects customers to pricing models and tracks their lifecycle.

```APIDOC
## POST /api/v1/subscriptions

### Description
Creates a new subscription, connecting a customer to a plan and setting its start date and other relevant metadata.

### Method
POST

### Endpoint
/api/v1/subscriptions

### Request Body
- **customer_id** (string) - Required - The ID of the customer subscribing.
- **plan_id** (string) - Required - The ID of the plan the customer is subscribing to.
- **starts_at** (string) - Required - The date the subscription becomes active (YYYY-MM-DD).
- **external_reference** (string) - Optional - An external reference identifier for the subscription (e.g., from your CRM).

### Request Example
{
  "customer_id": "cust_456",
  "plan_id": "plan_usage_plus",
  "starts_at": "2024-05-01",
  "external_reference": "crm-789"
}
```

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

### Subscriptions API

Source: https://usagebox.com/docs

Start, update, or view subscription lifecycle state.

```APIDOC
## GET /api/v1/subscriptions

### Description
View subscription lifecycle state.

### Method
GET

### Endpoint
/api/v1/subscriptions

## POST /api/v1/subscriptions

### Description
Start subscription lifecycle state.

### Method
POST

### Endpoint
/api/v1/subscriptions

## PATCH /api/v1/subscriptions

### Description
Update subscription lifecycle state.

### Method
PATCH

### Endpoint
/api/v1/subscriptions
```

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

### Create a product

Source: https://usagebox.com/docs

Use this endpoint to create a new product. Products act as the parent container for plans and are used to group related services.

```APIDOC
## POST /api/v1/products

### Description
Creates a new product with a given name and reference code.

### Method
POST

### Endpoint
/api/v1/products

### Request Body
- **name** (string) - Required - The name of the product.
- **code** (string) - Required - A unique reference code for the product.

### Request Example
{
  "name": "Pro API",
  "code": "pro-api"
}
```

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

### Products API

Source: https://usagebox.com/docs

List and create products in the active project.

```APIDOC
## GET /api/v1/products

### Description
List products in the active project.

### Method
GET

### Endpoint
/api/v1/products

## POST /api/v1/products

### Description
Create products in the active project.

### Method
POST

### Endpoint
/api/v1/products
```

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

### Create a Product with UsageBox API

Source: https://usagebox.com/docs

Use this endpoint to create a new product in your UsageBox catalog. Products serve as parent containers for plans.

```curl
curl -X POST https://api.usagebox.com/v1/products \
  -H 'Authorization: Bearer <api_key>' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Pro API", "code": "pro-api" }'
```

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

### Create or import customers

Source: https://usagebox.com/docs

Use this endpoint to create new customers or import existing ones into UsageBox. Customers store account details for billing.

```APIDOC
## POST /api/v1/customers

### Description
Creates a new customer or imports an existing one into the UsageBox platform.

### Method
POST

### Endpoint
/api/v1/customers

### Request Body
- **external_id** (string) - Required - The unique identifier for the customer in your system (e.g., corporate ID, UUID).
- **email** (string) - Optional - The customer's email address.
- **name** (string) - Optional - The customer's name.
```

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

### Customers API

Source: https://usagebox.com/docs

Create customers and fetch their billing profile.

```APIDOC
## GET /api/v1/customers

### Description
Fetch customer billing profiles.

### Method
GET

### Endpoint
/api/v1/customers

## POST /api/v1/customers

### Description
Create customers.

### Method
POST

### Endpoint
/api/v1/customers
```

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

### Attach one or more plans

Source: https://usagebox.com/docs

Use this endpoint to attach plans to a product. Plans define billing cadence, base price, and usage tiers.

```APIDOC
## POST /api/v1/plans

### Description
Attaches one or more plans to a product, configuring billing details and pricing models.

### Method
POST

### Endpoint
/api/v1/plans

### Request Body
- **plan_details** (object) - Required - Details of the plan to be created or attached.
  - **billing_cadence** (string) - Required - The billing frequency (e.g., "monthly", "annually").
  - **base_price** (number) - Required - The base price for the plan.
  - **usage_tiers** (array) - Optional - Defines usage-based pricing tiers.
  - **entitlements** (object) - Optional - Maps features to capabilities and limits.
```

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

### Create a Subscription with UsageBox API

Source: https://usagebox.com/docs

Connect a customer to a specific plan to activate a subscription. You can also include trial or contract metadata.

```curl
curl -X POST https://api.usagebox.com/v1/subscriptions \
  -H 'Authorization: Bearer <api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "cust_456",
    "plan_id": "plan_usage_plus",
    "starts_at": "2024-05-01",
    "external_reference": "crm-789"
  }'
```

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

### Meters API

Source: https://usagebox.com/docs

Create meters and inspect meter configuration.

```APIDOC
## GET /api/v1/meters

### Description
Inspect meter configuration.

### Method
GET

### Endpoint
/api/v1/meters

## POST /api/v1/meters

### Description
Create meters.

### Method
POST

### Endpoint
/api/v1/meters
```

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

### Projects API

Source: https://usagebox.com/docs

Fetch your projects and select an active project.

```APIDOC
## GET /api/v1/projects

### Description
Fetch your projects and select an active project.

### Method
GET

### Endpoint
/api/v1/projects

## PATCH /api/v1/projects

### Description
Fetch your projects and select an active project.

### Method
PATCH

### Endpoint
/api/v1/projects
```

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

### Plans API

Source: https://usagebox.com/docs

Manage plans and pricing tiers linked to products.

```APIDOC
## GET /api/v1/plans

### Description
List plans and pricing tiers linked to products.

### Method
GET

### Endpoint
/api/v1/plans

## POST /api/v1/plans

### Description
Create plans and pricing tiers linked to products.

### Method
POST

### Endpoint
/api/v1/plans
```

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

### Send usage from your app servers

Source: https://usagebox.com/docs

Send batches of usage events from your application servers to UsageBox for real-time rating.

```APIDOC
## POST /api/v1/usage

### Description
Submits batches of usage events to UsageBox for rating against active subscriptions and plans.

### Method
POST

### Endpoint
/api/v1/usage

### Request Body
- **events** (array) - Required - A list of usage events.
  - **subscription_id** (string) - Required - The ID of the subscription the event belongs to.
  - **meter_id** (string) - Required - The ID of the meter associated with the event.
  - **quantity** (number) - Required - The amount of usage for this event.
  - **occurred_at** (string) - Required - The timestamp when the usage occurred (ISO 8601 format).

### Request Example
{
  "events": [
    {
      "subscription_id": "sub_123",
      "meter_id": "mtr_compute",
      "quantity": 150,
      "occurred_at": "2024-05-01T12:00:00Z"
    }
  ]
}
```

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

### Send Usage Events to UsageBox API

Source: https://usagebox.com/docs

Send batches of usage events to UsageBox for real-time rating against your pricing models. Each event must reference a meter, subscription, and quantity.

```curl
curl -X POST https://api.usagebox.com/v1/usage \
  -H 'Authorization: Bearer <api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "events": [
      {
        "subscription_id": "sub_123",
        "meter_id": "mtr_compute",
        "quantity": 150,
        "occurred_at": "2024-05-01T12:00:00Z"
      }
    ]
  }'
```

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

### Usage API

Source: https://usagebox.com/docs

Submit usage events for metered billing.

```APIDOC
## POST /api/v1/usage

### Description
Submit usage events for metered billing.

### Method
POST

### Endpoint
/api/v1/usage
```

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

### Define meters for each billable signal

Source: https://usagebox.com/docs

Create meters to capture billable usage signals. Meters define unit names, aggregation methods, and associated products.

```APIDOC
## POST /api/v1/meters

### Description
Defines a meter for a specific billable signal, specifying its unit, aggregation method, and associated products.

### Method
POST

### Endpoint
/api/v1/meters

### Request Body
- **name** (string) - Required - The name of the meter (e.g., "API Calls", "Bandwidth").
- **unit** (string) - Required - The unit of measurement for the meter.
- **aggregation** (string) - Required - The aggregation method (e.g., "sum", "unique").
- **product_id** (string) - Required - The ID of the product this meter belongs to.
```

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

### API Keys API

Source: https://usagebox.com/docs

Rotate API credentials and manage access.

```APIDOC
## GET /api/v1/api-keys

### Description
View API credentials and manage access.

### Method
GET

### Endpoint
/api/v1/api-keys

## POST /api/v1/api-keys

### Description
Create API credentials and manage access.

### Method
POST

### Endpoint
/api/v1/api-keys

## DELETE /api/v1/api-keys

### Description
Rotate API credentials and manage access.

### Method
DELETE

### Endpoint
/api/v1/api-keys
```

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

### Activity API

Source: https://usagebox.com/docs

Inspect rating outcomes, charges, and events.

```APIDOC
## GET /api/v1/activity

### Description
Inspect rating outcomes, charges, and events.

### Method
GET

### Endpoint
/api/v1/activity
```

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

### Automate renewals and pauses

Source: https://usagebox.com/docs

Update the status or terms of an existing subscription, allowing for automation of renewals, pauses, and other lifecycle events.

```APIDOC
## PATCH /api/v1/subscriptions/{id}

### Description
Updates an existing subscription to pause, resume, or modify its terms without losing historical usage data.

### Method
PATCH

### Endpoint
/api/v1/subscriptions/{id}

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

### Request Body
- **status** (string) - Optional - The new status of the subscription (e.g., "paused", "active").
- **contract_end_at** (string) - Optional - The new end date for the subscription contract.
```

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