curl --request POST \
--url https://api.metronome.com/v1/packages/create \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"name": "My package",
"rate_card_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
"billing_provider": "stripe",
"delivery_method": "direct_to_billing_provider"
}'{
"data": {
"id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"
}
}Create a package
Create a package that defines a set of reusable, time-relative contract terms that can be used across cohorts of customers. Packages provide an abstraction layer on top of rate cards to provide an easy way to provision customers with standard pricing.
Use this endpoint to
- Model standard pay-as-you-go pricing packages that can be easily reused across customers
- Define standardized contract terms and discounting for sales-led motions
- [Coming soon] Set aliases for the package to facilitate easy package transition. Aliases are human-readable names that you can use in the place of the id of the package when provisioning a customer’s contract. By using an alias, you can easily create a contract and provision a customer by choosing the “Starter Plan” package, without storing the package ID in your internal systems. This is helpful when launching terms for a package, as you can create a new package with the “Starter Plan” alias scheduled to be assigned without updating your provisioning code.
Key Input Fields
starting_at_offset: Starting date relative to contract start. Generates thestarting_atdate when a contract is provisioned using a package.duration: Duration starting fromstarting_at_offset. Generates theending_beforedate when a contract is provisioned using a package.date_offset: Date relative to contract start. Used for point-in-time dates without a duration.
Usage Guidelines
- Use packages for standard self-serve use cases where customers have consistent terms. For customers with negotiated custom contract terms, use the
createContractendpoint for maximum flexibility. - Billing provider configuration can be set when creating a package by using
billing_provideranddelivery_method. To provision a customer successfully with a package, the customer must have one and only one billing provider configuration that matches the billing provider configuration set on the package. - A package alias can only be used by one package at a time. If you create a new package with an alias that is already in use by another package, the original package’s alias schedule will be updated. The alias will reference the package to which it was most recently assigned.
- Terms can only be specified using times relative to the contract start date. Supported granularities are:
days,weeks,months,years - Packages cannot be edited once created. Use the rate card to easily add new rates across all of your customers or make direct edits to a contract after provisioning with a package. Edited contracts will still be associated with the package used during provisioning.
curl --request POST \
--url https://api.metronome.com/v1/packages/create \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"name": "My package",
"rate_card_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
"billing_provider": "stripe",
"delivery_method": "direct_to_billing_provider"
}'{
"data": {
"id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Create a new package
Prevents the creation of duplicates. If a request to create a record is made with a previously used uniqueness key, a new record will not be created and the request will fail with a 409 error.
1 - 128Selects the rate card linked to the specified alias as of the contract's start date.
contract_start_date, first_billing_period Show child attributes
Show child attributes
PREPAID, prepaid, POSTPAID, postpaid Required: Schedule for distributing the commit to the customer. For "POSTPAID" commits only one schedule item is allowed and amount must match invoice_schedule total.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Defaults to USD (cents) if not passed
COMMIT_RATE, commit_rate, LIST_RATE, list_rate displayed on invoices
1Required for "POSTPAID" commits: the true up invoice will be generated at this time and only one schedule item is allowed; the total must match access_schedule amount. Optional for "PREPAID" commits: if not provided, this will be a "complimentary" commit with no invoice.
Show child attributes
Show child attributes
Either provide amount or provide both unit_price and quantity.
Show child attributes
Show child attributes
Unit price for the charge. Will be multiplied by quantity to determine the amount.
Quantity for the charge. Will be multiplied by unit_price to determine the amount.
Defaults to USD (cents) if not passed.
If true, this schedule will not generate an invoice.
Used only in UI/API. It is not exposed to end customers.
Fraction of unused segments that will be rolled over. Must be between 0 and 1.
If multiple commits are applicable, the one with the lower priority will apply first.
Which products the commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products.
The body is of type string<uuid>.
Which tags the commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products.
The body is of type string.
List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown. This field cannot be used together with applicable_product_ids or applicable_product_tags.
Show child attributes
Show child attributes
If provided, the specifier will only apply to the product with the specified ID.
If provided, the specifier will only apply to products with all the specified tags.
The body is of type string.
A temporary ID for the commit that can be used to reference the commit for commit specific overrides.
Show child attributes
Show child attributes
Schedule for distributing the credit to the customer.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Defaults to USD (cents) if not passed
displayed on invoices
1Used only in UI/API. It is not exposed to end customers.
Which products the credit applies to. If both applicable_product_ids and applicable_product_tags are not provided, the credit applies to all products.
The body is of type string<uuid>.
Which tags the credit applies to. If both applicable_product_ids and applicable_product_tags are not provided, the credit applies to all products.
The body is of type string.
List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown. This field cannot be used together with applicable_product_ids or applicable_product_tags.
Show child attributes
Show child attributes
If provided, the specifier will only apply to the product with the specified ID.
If provided, the specifier will only apply to products with all the specified tags.
The body is of type string.
If multiple credits are applicable, the one with the lower priority will apply first.
COMMIT_RATE, commit_rate, LIST_RATE, list_rate Show child attributes
Show child attributes
Will be passed down to the individual commits
Defines the length of the access schedule for each created commit/credit. The value represents the number of units. Unit defaults to "PERIODS", where the length of a period is determined by the recurrence_frequency.
displayed on invoices. will be passed through to the individual commits
1Will be passed down to the individual commits
Will be passed down to the individual commits. This controls how much of an individual unexpired commit will roll over upon contract transition. Must be between 0 and 1.
Will be passed down to the individual commits
The body is of type string<uuid>.
Will be passed down to the individual commits
The body is of type string.
List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown. This field cannot be used together with applicable_product_ids or applicable_product_tags.
Show child attributes
Show child attributes
If provided, the specifier will only apply to the product with the specified ID.
If provided, the specifier will only apply to products with all the specified tags.
The body is of type string.
A temporary ID that can be used to reference the recurring commit for commit specific overrides.
Whether the created commits will use the commit rate or list rate
COMMIT_RATE, commit_rate, LIST_RATE, list_rate The frequency at which the recurring commits will be created. If not provided: - The commits will be created on the usage invoice frequency. If provided: - The period defined in the duration will correspond to this frequency. - Commits will be created aligned with the recurring commit's starting_at rather than the usage invoice dates.
MONTHLY, monthly, QUARTERLY, quarterly, ANNUAL, annual, WEEKLY, weekly Determines whether the first and last commit will be prorated. If not provided, the default is FIRST_AND_LAST (i.e. prorate both the first and last commits).
NONE, none, FIRST, first, LAST, last, FIRST_AND_LAST, first_and_last Attach a subscription to the recurring commit/credit.
Show child attributes
Show child attributes
ID of the subscription to configure on the recurring commit/credit.
If set to POOLED, allocation added per seat is pooled across the account. If set to INDIVIDUAL, each seat in the subscription will have its own allocation.
INDIVIDUAL, POOLED Show child attributes
Show child attributes
Will be passed down to the individual commits
Defines the length of the access schedule for each created commit/credit. The value represents the number of units. Unit defaults to "PERIODS", where the length of a period is determined by the recurrence_frequency.
displayed on invoices. will be passed through to the individual commits
1Will be passed down to the individual commits
Will be passed down to the individual commits. This controls how much of an individual unexpired commit will roll over upon contract transition. Must be between 0 and 1.
Will be passed down to the individual commits
The body is of type string<uuid>.
Will be passed down to the individual commits
The body is of type string.
List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown. This field cannot be used together with applicable_product_ids or applicable_product_tags.
Show child attributes
Show child attributes
If provided, the specifier will only apply to the product with the specified ID.
If provided, the specifier will only apply to products with all the specified tags.
The body is of type string.
A temporary ID that can be used to reference the recurring commit for commit specific overrides.
Whether the created commits will use the commit rate or list rate
COMMIT_RATE, commit_rate, LIST_RATE, list_rate The frequency at which the recurring commits will be created. If not provided: - The commits will be created on the usage invoice frequency. If provided: - The period defined in the duration will correspond to this frequency. - Commits will be created aligned with the recurring commit's starting_at rather than the usage invoice dates.
MONTHLY, monthly, QUARTERLY, quarterly, ANNUAL, annual, WEEKLY, weekly Determines whether the first and last commit will be prorated. If not provided, the default is FIRST_AND_LAST (i.e. prorate both the first and last commits).
NONE, none, FIRST, first, LAST, last, FIRST_AND_LAST, first_and_last Attach a subscription to the recurring commit/credit.
Show child attributes
Show child attributes
ID of the subscription to configure on the recurring commit/credit.
If set to POOLED, allocation added per seat is pooled across the account. If set to INDIVIDUAL, each seat in the subscription will have its own allocation.
INDIVIDUAL, POOLED Defaults to LOWEST_MULTIPLIER, which applies the greatest discount to list prices automatically. EXPLICIT prioritization requires specifying priorities for each multiplier; the one with the lowest priority value will be prioritized first. If tiered overrides are used, prioritization must be explicit.
LOWEST_MULTIPLIER, lowest_multiplier, EXPLICIT, explicit Show child attributes
Show child attributes
Specifies which products the override will apply to.
Show child attributes
Show child attributes
Can only be used for commit specific overrides. Must be used in conjunction with one of product_id, product_tags, pricing_group_values, or presentation_group_values. If provided, the override will only apply to the specified commits. If not provided, the override will apply to all commits.
The body is of type string.
Can only be used for commit specific overrides. Must be used in conjunction with one of product_id, product_tags, pricing_group_values, or presentation_group_values. If provided, the override will only apply to commits created by the specified recurring commit ids.
The body is of type string.
Can only be used for commit specific overrides. Must be used in conjunction with one of product_id, product_tags, pricing_group_values, or presentation_group_values. If provided, the override will only apply to credits created by the specified recurring credit ids.
The body is of type string.
If provided, the override will only apply to the product with the specified ID.
If provided, the override will only apply to products with all the specified tags.
The body is of type string.
MONTHLY, QUARTERLY, ANNUAL, monthly, quarterly, annual, WEEKLY, weekly Overwrites are prioritized over multipliers and tiered overrides.
OVERWRITE, overwrite, MULTIPLIER, multiplier, TIERED, tiered Required for MULTIPLIER type. Must be >=0.
Required for EXPLICIT multiplier prioritization scheme and all TIERED overrides. Under EXPLICIT prioritization, overwrites are prioritized first, and then tiered and multiplier overrides are prioritized by their priority value (lowest first). Must be > 0.
Required for OVERWRITE type.
Show child attributes
Show child attributes
FLAT, flat, PERCENTAGE, percentage, TIERED, tiered Default price. For FLAT rate_type, this must be >=0. For PERCENTAGE rate_type, this is a decimal fraction, e.g. use 0.1 for 10%; this must be >=0 and <=1.
Indicates whether the override should only apply to commits. Defaults to false. If true, you can specify relevant commits in override_specifiers by passing commit_ids. if you do not specify commit_ids, then the override will apply when consuming any prepaid or postpaid commit.
Indicates whether the override applies to commit rates or list rates. Can only be used for overrides that have is_commit_specific set to true. Defaults to "LIST_RATE".
COMMIT_RATE, commit_rate, LIST_RATE, list_rate Show child attributes
Show child attributes
Must provide schedule_items.
Show child attributes
Show child attributes
Either provide amount or provide both unit_price and quantity.
Show child attributes
Show child attributes
Unit price for the charge. Will be multiplied by quantity to determine the amount.
Quantity for the charge. Will be multiplied by unit_price to determine the amount.
Defaults to USD (cents) if not passed.
displayed on invoices
1Determines which scheduled and commit charges to consolidate onto the Contract's usage invoice. The charge's timestamp must match the usage invoice's ending_before date for consolidation to occur. This field cannot be modified after a Contract has been created. If this field is omitted, charges will appear on a separate invoice from usage charges.
ALL Show child attributes
Show child attributes
MONTHLY, monthly, QUARTERLY, quarterly, ANNUAL, annual, WEEKLY, weekly If not provided, defaults to the first day of the month.
FIRST_OF_MONTH, first_of_month, CONTRACT_START, contract_start The offset at which Metronome should start generating usage invoices, relative to the contract start date. If unspecified, contract start date will be used. This is useful to set if you want to import historical invoices via our 'Create Historical Invoices' API rather than having Metronome automatically generate them.
aws_marketplace, azure_marketplace, gcp_marketplace, stripe, netsuite direct_to_billing_provider, aws_sqs, tackle, aws_sns Show child attributes
Show child attributes
When set to false, the contract will not be evaluated against the threshold_amount. Toggling to true will result an immediate evaluation, regardless of prior state.
Specify the threshold amount for the contract. Each time the contract's usage hits this amount, a threshold charge will be initiated.
Show child attributes
Show child attributes
The commit product that will be used to generate the line item for commit payment.
Specify the name of the line item for the threshold charge. If left blank, it will default to the commit product name.
Show child attributes
Show child attributes
Gate access to the commit balance based on successful collection of payment. Select STRIPE for Metronome to facilitate payment via Stripe. Select EXTERNAL to facilitate payment using your own payment integration. Select NONE if you do not wish to payment gate the commit balance.
NONE, STRIPE, EXTERNAL Stripe tax is only supported for Stripe payment gateway. Select NONE if you do not wish Metronome to calculate tax on your behalf. Leaving this field blank will default to NONE.
NONE, STRIPE, ANROK, AVALARA, PRECALCULATED Only applicable if using STRIPE as your payment gate type.
Show child attributes
Show child attributes
If left blank, will default to INVOICE
INVOICE, PAYMENT_INTENT Only applicable if using PRECALCULATED as your tax type.
Show child attributes
Show child attributes
Amount of tax to be applied. This should be in the same currency and denomination as the commit's invoice schedule
Name of the tax to be applied. This may be used in an invoice line item description.
Show child attributes
Show child attributes
When set to false, the contract will not be evaluated against the threshold_amount. Toggling to true will result an immediate evaluation, regardless of prior state.
Specify the threshold amount for the contract. Each time the contract's prepaid balance lowers to this amount, a threshold charge will be initiated.
Specify the amount the balance should be recharged to.
Show child attributes
Show child attributes
The commit product that will be used to generate the line item for commit payment.
Specify the name of the line item for the threshold charge. If left blank, it will default to the commit product name.
Which products the threshold commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products.
The body is of type string<uuid>.
Which tags the threshold commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products.
The body is of type string.
Show child attributes
Show child attributes
Gate access to the commit balance based on successful collection of payment. Select STRIPE for Metronome to facilitate payment via Stripe. Select EXTERNAL to facilitate payment using your own payment integration. Select NONE if you do not wish to payment gate the commit balance.
NONE, STRIPE, EXTERNAL Stripe tax is only supported for Stripe payment gateway. Select NONE if you do not wish Metronome to calculate tax on your behalf. Leaving this field blank will default to NONE.
NONE, STRIPE, ANROK, AVALARA, PRECALCULATED Only applicable if using STRIPE as your payment gate type.
Show child attributes
Show child attributes
If left blank, will default to INVOICE
INVOICE, PAYMENT_INTENT Metadata to be added to the Stripe invoice. Only applicable if using INVOICE as your payment type.
Show child attributes
Show child attributes
Only applicable if using PRECALCULATED as your tax type.
Show child attributes
Show child attributes
Amount of tax to be applied. This should be in the same currency and denomination as the commit's invoice schedule
Name of the tax to be applied. This may be used in an invoice line item description.
If provided, the threshold, recharge-to amount, and the resulting threshold commit amount will be in terms of this credit type instead of the fiat currency.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Frequency to bill subscription with. Together with product_id, must match existing rate on the rate card.
MONTHLY, QUARTERLY, ANNUAL, WEEKLY, monthly, quarterly, annual, weekly Must be subscription type product
ADVANCE, ARREARS, advance, arrears Show child attributes
Show child attributes
Indicates if the partial period will be prorated or charged a full amount.
Indicates how mid-period quantity adjustments are invoiced.
BILL_IMMEDIATELY: Only available when collection schedule is ADVANCE. The quantity increase will be billed immediately on the scheduled date.
BILL_ON_NEXT_COLLECTION_DATE: The quantity increase will be billed for in-arrears at the end of the period.
BILL_IMMEDIATELY, BILL_ON_NEXT_COLLECTION_DATE, bill_immediately, bill_on_next_collection_date The initial quantity for the subscription. It must be non-negative value. Required if quantity_management_mode is QUANTITY_ONLY.
Relative date from contract start date corresponding to the inclusive start time for the subscription. If not provided, defaults to contract start date
A temporary ID used to reference the subscription in recurring commit/credit subscription configs created within the same payload.
Determines how the subscription's quantity is controlled. Defaults to QUANTITY_ONLY. QUANTITY_ONLY: The subscription quantity is specified directly on the subscription. initial_quantity must be provided with this option. Compatible with recurring commits/credits that use POOLED allocation. SEAT_BASED: Use when you want to pass specific seat identifiers (e.g. add user_123) to increment and decrement a subscription quantity, rather than directly providing the quantity. You must use a SEAT_BASED subscription to use a linked recurring credit with an allocation per seat. seat_config must be provided with this option.
SEAT_BASED, seat_based, QUANTITY_ONLY, quantity_only Show child attributes
Show child attributes
The property name, sent on usage events, that identifies the seat ID associated with the usage event. For example, the property name might be seat_id or user_id. The property must be set as a group key on billable metrics and a presentation/pricing group key on contract products. This allows linked recurring credits with an allocation per seat to be consumed by only one seat's usage.
The initial amount of unassigned seats on this subscription.