> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.resemble.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.resemble.ai/_mcp/server.

# Subscriptions and Product Quantities

Use subscription metadata to discover every product your team can adjust. Voice Clone Slots are used below as one example; the same workflow applies to any product marked adjustable by the API.

Set the credentials and base URL used in the examples:

```bash
export RESEMBLE_API_KEY="your_api_key"
export BILLING_API_BASE="https://app.resemble.ai/billing/api/v1"
```

## Discover plans

Plan discovery is public. List active self-serve plans before changing a subscription:

```bash
curl "$BILLING_API_BASE/plans"
```

Retrieve one plan using its returned `slug`:

```bash
curl "$BILLING_API_BASE/plans/flex"
```

A plan's `products` array describes included quantities, prices, and plan-specific limits. Do not maintain a hard-coded catalog of adjustable product slugs; products and rules can vary by plan.

## Find the current subscription

```bash
curl "$BILLING_API_BASE/subscription" \
  -H "Authorization: Bearer $RESEMBLE_API_KEY"
```

The response contains `subscription: null` when the team has no customer-visible active subscription. Otherwise, `subscription.subscription_items` contains the current product quantities and consumption.

## Find every adjustable product

An item is adjustable when both of these conditions are true:

* `product.category` is `subscription`.
* `plan_product.allow_additional_usage` is `true`.

List the team's adjustable products and their effective constraints with `jq`:

```bash
curl --silent "$BILLING_API_BASE/subscription" \
  -H "Authorization: Bearer $RESEMBLE_API_KEY" \
  | jq '
      .subscription.subscription_items[]
      | select(
          .product.category == "subscription"
          and .plan_product.allow_additional_usage == true
        )
      | {
          name: .product.name,
          slug: .product.slug,
          quantity,
          consumed_quantity,
          included_quantity: .plan_product.included_quantity,
          minimum: .plan_product.min_usage_per_period,
          maximum: .plan_product.max_usage_per_period,
          locked_rate_per_unit_cents: .rate_per_unit_cents,
          current_rate_per_unit_cents
        }
    '
```

Use the returned values as the source of truth:

* `quantity` is the current absolute quantity.
* `consumed_quantity` is currently in use and is the lowest quantity you can select.
* `included_quantity` is supplied by the plan.
* `min_usage_per_period` and `max_usage_per_period` are the plan's allowed bounds. A null maximum means there is no plan-specific maximum.
* `rate_per_unit_cents` is the subscription item's locked-in rate; `current_rate_per_unit_cents` is the current catalog rate.

## Update product quantities

`PATCH /subscription/products` accepts one or more changes in a single request. Every `new_quantity` is the desired absolute total, not an amount to add or subtract.

```bash
curl --request PATCH "$BILLING_API_BASE/subscription/products" \
  -H "Authorization: Bearer $RESEMBLE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "changes": [
      {
        "product_slug": "voice_clone",
        "new_quantity": 5
      },
      {
        "product_slug": "another_adjustable_product",
        "new_quantity": 10
      }
    ]
  }'
```

The API validates every change before applying the batch:

* The product must exist on the current plan.
* Only `subscription` products with `allow_additional_usage: true` can change.
* The new quantity cannot be negative or fall outside the returned plan bounds.
* The new quantity cannot be less than `consumed_quantity`. Remove the resources using those slots first.

Replace `another_adjustable_product` with a product slug returned by the adjustable-product query. The Voice Clone example uses the same batch operation as every other adjustable product.

### Example: increase Voice Clone Slots

First, find the existing Voice Clone quantity rather than assuming it:

```bash
curl --silent "$BILLING_API_BASE/subscription" \
  -H "Authorization: Bearer $RESEMBLE_API_KEY" \
  | jq '.subscription.subscription_items[] | select(.product.slug == "voice_clone") | {quantity, consumed_quantity, plan_product}'
```

If the current quantity is `3` and the desired total is `5`, send `new_quantity: 5`:

```bash
curl --request PATCH "$BILLING_API_BASE/subscription/products" \
  -H "Authorization: Bearer $RESEMBLE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "changes": [
      {
        "product_slug": "voice_clone",
        "new_quantity": 5
      }
    ]
  }'
```

This sets the total to five Voice Clone Slots. It does not add five slots. Use the same process for every product returned by the adjustable-product filter.

## Complete additional payment authentication

A prorated quantity or plan change can require additional payment authentication. In that case the mutation returns `402 Payment Required`:

```json
{
  "requires_action": true,
  "client_secret": "pi_..._secret_..."
}
```

Send the `client_secret` to a secure browser payment flow so the customer can complete authentication. After authentication succeeds, send the completed payment intent ID from your server:

```bash
curl --request POST "$BILLING_API_BASE/subscription/confirm_payment" \
  -H "Authorization: Bearer $RESEMBLE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "payment_intent_id": "pi_123456789"
  }'
```

The response contains the synchronized subscription. Keep the API key on your server while the customer completes payment authentication.

## Change plans

Change to another active plan. The change is prorated and can return the same `402` flow described above:

```bash
curl --request PATCH "$BILLING_API_BASE/subscription/change_plan" \
  -H "Authorization: Bearer $RESEMBLE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "plan_slug": "PLAN_SLUG_FROM_GET_PLANS",
    "product_quantities": {
      "voice_clone": 5
    }
  }'
```

Custom enterprise plans cannot be changed through self-service endpoints. Contact Resemble support to manage them.

## API reference

* [List billing plans](/api-reference/billing-plans/list-billing-plans)
* [Get the current subscription](/api-reference/billing-subscriptions/get-billing-subscription)
* [Update subscription product quantities](/api-reference/billing-subscriptions/update-billing-subscription-products)