# Packages

> Reusable contract templates, aliases and versions.

Source: https://metrocli.com/docs/concepts/packages/ · Docs index: https://metrocli.com/llms.txt

A package is a reusable, customer-agnostic contract template. It bundles a rate card, a duration, billing settings, and optionally recurring commits, credits and subscriptions. A contract created from a package copies the template at creation time.

> **Metronome's reference:** [Create a package](https://docs.metronome.com/api-reference/contracts/create-a-package) · [Get a package](https://docs.metronome.com/api-reference/packages/get-a-package) · [List all packages](https://docs.metronome.com/api-reference/list-all-packages) · [Archive a package](https://docs.metronome.com/api-reference/packages/archive-a-package) · [List contracts associated with a package](https://docs.metronome.com/api-reference/contracts/list-contracts-associated-with-a-package). These pages are the source of truth for every field; metro's page covers how metro handles it. What metro wraps, endpoint by endpoint: [Metronome API coverage](/docs/reference/api-coverage).

## Aliases and versions

Packages can't be edited. To change one, you publish a new package with the same alias and a future `starting_at` on that alias. From that hour the alias resolves to the new version. Existing contracts keep the version they were created from.

An alias resolves to the version live at the **contract's** `starting_at`, not at the time of the call. Use aliases, not hardcoded package IDs.

## How it connects

A package references a rate card. Contracts reference it through `package_alias` or `package_id`. Listing the contracts on a package shows who uses it.

## Gotchas

- Aliases must be objects, `[{ "name": "growth" }]`. A plain string alias is silently ignored.
- Recurring commits on a package need `starting_at_offset` and `proration`, which direct contracts don't. A missing one gives an unhelpful schema error.
- Don't archive an old version until the new alias is live. In that gap, contract creation fails with `400`.
- Package list returns archived packages too, and returns `uniqueness_key` with a `package:` prefix.
- A tenant holds at most 75 active packages, plus archived ones that still have contracts.
- A package with a seat subscription needs a matching subscription rate on its rate card.
- Annual packages should set `usage_statement_schedule.day: CONTRACT_START`. The default is `FIRST_OF_MONTH`.

## How metro handles it

| Command | Does |
|---|---|
| `metro package list --sandbox --json` | All packages, with `--search=`, `--only-active`, `--only-archived` |
| `metro package customers --alias=growth --sandbox` | Contracts created from a package |
| `metro package create preflight --file=package.yaml --sandbox` | Create a package. Derives a `uniqueness_key` if you don't pass one, and refuses an alias another package holds. |
| `metro package clone-version preflight --aliases=growth --handoff-at=<hour> --sandbox` | Publish a new version behind the same alias. Nothing is archived. |
| `metro package archive preview --file handoff.json --sandbox` | Offline check that refuses archive until the new alias is live |

See [Clone a package version](/docs/guides/clone-a-package-version). Metronome docs: [Create a package](https://docs.metronome.com/api-reference/contracts/create-a-package).