> ## Documentation Index
> Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Bundles
> Group several priced products into one reusable unit that subscriptions, plans and quotes reference by a single ID — and how a bundle differs from a plan.
A **bundle** groups several priced [products](/docs/pricing/configure-products) so they can be added and managed as one thing. "Platform + onboarding + support", always sold together, is a bundle: define it once and reference it by ID wherever items are chosen — a [subscription](/docs/subscriptions/overview-subscriptions), a [plan](/docs/pricing/plans), or a [quote](/docs/quotes/create-quotes) — instead of adding the same three products by hand each time. See [How Alguna Works](/docs/concepts/how-alguna-works) for where bundles sit in the object graph.
***
## Bundle or plan?
The two are often confused because both collect products. They answer different questions.
| | Bundle | Plan |
| ----------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Answers** | Which products travel together as one item | What we sell, on what terms |
| **Contains** | Priced products | Priced products *and* bundles, plus contract length, renewal, trial, discounts, spend thresholds, entitlements, invoice behaviour |
| **Sellable on its own** | No — it is an item inside an offer | Yes — a buyer picks it at [checkout](/docs/hosted/checkout), a rep starts a [quote](/docs/quotes/create-quotes) from it, the API takes it as `plan_id` |
| **Reach for it when** | The same few products always go together and should be added as one | The same complete offer will be sold more than once |
A plan can contain bundle items, so the two compose: a plan is the offer, a bundle is a unit of packaging inside it. If you only ever sell the group as a fixed offer with fixed terms, a plan alone is enough — reach for a bundle when the same grouping needs to appear inside several different offers, or on a quote a rep assembles item by item.
***
## Creating a bundle
A bundle needs a `name` and its `prices` — the same [price definitions](/docs/pricing/pricing-models) you would give a product on a subscription. Each price names its `product_id`, its pricing `type` and model, whether it is `fixed` or `metered`, and when it bills.
```bash cURL theme={null}
curl -X POST https://api.alguna.io/bundles \
-H "Authorization: Bearer $ALGUNA_API_KEY" \
-H "Alguna-Version: 2026-04-01" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ik_bundle_platform_starter" \
-d '{
"name": "Platform Starter",
"description": "Platform access with onboarding and metered API calls",
"prices": [
{
"product_id": "prod_platform",
"type": "fixed",
"fee_type": "fixed",
"billing_direction": "advance",
"billing_frequency": "recurring",
"billing_interval_unit": "month",
"billing_interval_count": 1,
"charge_on_contract_start": true,
"fixed_pricing_model": { "price_per_unit": "500.00", "units": 1 }
},
{
"product_id": "prod_api_calls",
"type": "unit",
"fee_type": "metered",
"billing_direction": "arrears",
"billing_frequency": "recurring",
"billing_interval_unit": "month",
"billing_interval_count": 1,
"charge_on_contract_start": false,
"unit_pricing_model": { "price_per_unit": "0.05" }
}
]
}'
```
```python Python theme={null}
import os
import requests
response = requests.post(
"https://api.alguna.io/bundles",
headers={
"Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
"Alguna-Version": "2026-04-01",
"Content-Type": "application/json",
"Idempotency-Key": "ik_bundle_platform_starter",
},
json={
"name": "Platform Starter",
"description": "Platform access with onboarding and metered API calls",
"prices": [
{
"product_id": "prod_platform",
"type": "fixed",
"fee_type": "fixed",
"billing_direction": "advance",
"billing_frequency": "recurring",
"billing_interval_unit": "month",
"billing_interval_count": 1,
"charge_on_contract_start": True,
"fixed_pricing_model": {"price_per_unit": "500.00", "units": 1},
},
{
"product_id": "prod_api_calls",
"type": "unit",
"fee_type": "metered",
"billing_direction": "arrears",
"billing_frequency": "recurring",
"billing_interval_unit": "month",
"billing_interval_count": 1,
"charge_on_contract_start": False,
"unit_pricing_model": {"price_per_unit": "0.05"},
},
],
},
timeout=10,
)
response.raise_for_status()
bundle = response.json()
```
```typescript TypeScript SDK theme={null}
const bundle = await alguna.bundles.create(
{
name: "Platform Starter",
description: "Platform access with onboarding and metered API calls",
prices: [
{
product_id: "prod_platform",
type: "fixed",
fee_type: "fixed",
billing_direction: "advance",
billing_frequency: "recurring",
billing_interval_unit: "month",
billing_interval_count: 1,
charge_on_contract_start: true,
fixed_pricing_model: { price_per_unit: "500.00", units: 1 },
},
{
product_id: "prod_api_calls",
type: "unit",
fee_type: "metered",
billing_direction: "arrears",
billing_frequency: "recurring",
billing_interval_unit: "month",
billing_interval_count: 1,
charge_on_contract_start: false,
unit_pricing_model: { price_per_unit: "0.05" },
},
],
},
{ idempotencyKey: "ik_bundle_platform_starter" },
);
```
A bundle can mix fixed and metered prices and different billing directions freely — the platform fee above bills in advance, the API calls in arrears — because each price keeps its own cadence. Amounts are strings, never floats.
**In the dashboard:** **Bundles → New Bundle**, then add products and set each one's price. Existing bundles are listed and edited from the same place.
***
## Reading and updating
| Operation | Endpoint | SDK |
| --------- | --------------------------------------------------------------------------------------------- | ------------------------------ |
| List | [`GET /bundles`](/docs/api-reference/v2/2026-04-01/product-bundles/list-product-bundles) | `alguna.bundles.list()` |
| Fetch one | [`GET /bundles/{id}`](/docs/api-reference/v2/2026-04-01/product-bundles/get-a-product-bundle) | `alguna.bundles.get(id)` |
| Update | [`PATCH /bundles/{id}`](/docs/api-reference/v2/2026-04-01/product-bundles/update-a-product-bundle) | `alguna.bundles.update(id, …)` |
List takes `limit` and `offset` — see [Pagination](/docs/api-reference/v2/overview#pagination).
Editing a bundle changes the template, not the subscriptions already sold from it. A subscription holds its own copy of the priced items from the moment it was created, so existing customers keep the prices they agreed to. To change what an active customer pays, amend the subscription — see [Amendments](/docs/subscriptions/amendments) and [Versioning](/docs/subscriptions/versioning).
***
## Using a bundle
Wherever an item list accepts products, an entry is **either** a standalone item (`product_id` with its `price`) **or** a bundle item (`bundle_id` with its child `items`). You do not flatten a bundle into loose products — passing the `bundle_id` is what keeps it grouped downstream.
* **On a subscription** — pass `bundle_id` and the bundle's `items` in the subscription's item list when [creating a subscription](/docs/guides/first-subscription).
* **On a plan** — a plan item takes `bundle_id` plus a `name` and `bundle_description` for how the bundle is labelled in that offer, so the same bundle can read differently in two plans.
* **On a subscription version** — bundle items appear in [version items](/docs/subscriptions/versioning) exactly as they do on creation, so a bundle can be added, changed or removed as part of an amendment like any other item.
* **On a quote** — build the quote in the dashboard and add the bundle as a line; quoting is a dashboard flow, not an API one. See [Create quotes](/docs/quotes/create-quotes).
The grouping survives the sale: a subscription version item created from a bundle carries its `bundle_id`, so the subscription still shows the bundle rather than a flat list of unrelated products, and a later amendment can address the bundle as a unit. Billing itself is unchanged — each price inside the bundle bills on its own cadence and produces its own charge.
***
## Next steps
The products a bundle groups.
Every price type and its model fields.
Turn packaging into a sellable offer with terms.
Change what a customer is billed for mid-term.