Packages
Reusable contract templates, aliases and versions.
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 · Get a package · List all packages · Archive a package · 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.
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_offsetandproration, 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_keywith apackage: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 isFIRST_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. Metronome docs: Create a package.