Create a package

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"
  }
}

Packages

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 the starting_at date when a contract is provisioned using a package.
duration: Duration starting from starting_at_offset. Generates the ending_before date 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 createContract endpoint for maximum flexibility.
Billing provider configuration can be set when creating a package by using billing_provider and delivery_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.

POST

packages

create

Create a package

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

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Create a new package

name

string

required

contract_name

string

uniqueness_key

string

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.

Required string length: 1 - 128

net_payment_terms_days

number

rate_card_id

string<uuid>

rate_card_alias

string

Selects the rate card linked to the specified alias as of the contract's start date.

duration

object

Show child attributes

billing_anchor_date

enum<string>

Available options:

contract_start_date,

first_billing_period

commits

object[]

Show child attributes

credits

object[]

Show child attributes

recurring_commits

object[]

Show child attributes

recurring_credits

object[]

Show child attributes

multiplier_override_prioritization

enum<string>

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.

Available options:

LOWEST_MULTIPLIER,

lowest_multiplier,

EXPLICIT,

explicit

overrides

object[]

Show child attributes

scheduled_charges

object[]

Show child attributes

scheduled_charges_on_usage_invoices

enum<string>

Determines 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.

Available options:

ALL

usage_statement_schedule

object

Show child attributes

billing_provider

enum<string>

Available options:

aws_marketplace,

azure_marketplace,

gcp_marketplace,

stripe,

netsuite

delivery_method

enum<string>

Available options:

direct_to_billing_provider,

aws_sqs,

tackle,

aws_sns

spend_threshold_configuration

object

Show child attributes

prepaid_balance_threshold_configuration

object

Show child attributes

subscriptions

object[]

Show child attributes

Response

Success

data

object

required

Show child attributes

⌘I