Metronome Packages API
The Packages API from Metronome — 3 operation(s) for packages.
OpenAPI Specification
openapi: 3.0.1
info:
title: Metronome Alerts Packages API
version: 1.0.0
description: '[Alerts](https://docs.metronome.com/connecting-metronome/alerts/) monitor customer spending, balances, and other billing factors. Use these endpoints to create, retrieve, and archive customer alerts. To view sample alert payloads by alert type, navigate [here.](https://docs.metronome.com/manage-product-access/create-manage-alerts/#webhook-notifications)'
servers:
- url: https://api.metronome.com
description: Production server
security:
- bearerAuth: []
tags:
- name: Packages
paths:
/v1/packages/get:
post:
description: 'Gets the details for a specific package, including name, aliases, duration, and terms. Use this endpoint to understand a package’s alias schedule, or display a specific package’s details to end customers.
'
operationId: getPackage-v1
summary: Get a package
tags:
- Packages
requestBody:
description: Package ID
content:
application/json:
schema:
type: object
required:
- package_id
properties:
package_id:
type: string
format: uuid
example:
package_id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/Package'
example:
data:
id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
name: Basic Package
usage_statement_schedule:
frequency: MONTHLY
created_at: '2019-12-31T14:23:55.234Z'
created_by: Alice
commits:
- id: 62c0cb84-bf3f-48b9-9bcf-a8ddf8c1cf35
type: PREPAID
name: My test commit
description: My test commit description
product:
id: 2e30f074-d04c-412e-a134-851ebfa5ceb2
name: My product A
applicable_product_ids:
- 13a2179b-f0cb-460b-85a1-cd42964ca533
access_schedule:
credit_type:
id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2
name: USD (cents)
schedule_items:
- id: 2d45952c-5a6e-43a9-8aab-f61ee21be81a
amount: 10000000
starting_at_offset:
unit: MONTHS
value: 1
duration:
unit: MONTHS
value: 3
invoice_schedule:
credit_type:
id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2
name: USD (cents)
schedule_items:
- id: f15e4e23-f74e-4de4-9b3a-8b07434116c4
unit_price: 10000000
quantity: 1
date_offset:
unit: MONTHS
value: 4
do_not_invoice: false
overrides:
- id: 6cf3292a-e85c-4be6-822c-e25ba9d19757
starting_at_offset:
unit: MONTHS
value: 1
type: MULTIPLIER
multiplier: 0.1
override_specifiers:
- product_id: eae8903b-693b-41a7-8c0b-f23748c9a9c8
scheduled_charges:
- id: 04dbca69-0bc2-45c6-ba22-a53934353b10
name: Test Scheduled Charge
description: Test Scheduled Charge Description
product:
id: eae8903b-693b-41a7-8c0b-f23748c9a9c8
name: My product B
schedule:
credit_type:
id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2
name: USD (cents)
schedule_items:
- id: f15e4e23-f74e-4de4-9b3a-8b07434116c4
unit_price: 10000000
quantity: 1
date_offset:
unit: MONTHS
value: 4
'404':
$ref: '#/components/responses/NotFound'
/v1/packages/list:
post:
description: 'Lists all packages with details including name, aliases, duration, and terms. To view contracts on a specific package, use the `listContractsOnPackage` endpoint.
'
summary: List all packages
operationId: listPackages-v1
parameters:
- $ref: '#/components/parameters/PageLimit'
description: The maximum number of packages to return. Defaults to 10.
- $ref: '#/components/parameters/NextPage'
requestBody:
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
archive_filter:
type: string
enum:
- ARCHIVED
- NOT_ARCHIVED
- ALL
- archived
- not_archived
- all
description: Filter packages by archived status. Defaults to NOT_ARCHIVED.
example: {}
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
- next_page
properties:
data:
type: array
items:
$ref: '#/components/schemas/Package'
next_page:
type: string
nullable: true
example:
data:
- id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
name: Test Package
usage_statement_schedule:
frequency: MONTHLY
created_at: '2019-12-31T14:23:55.234Z'
created_by: Alice
commits:
- id: 62c0cb84-bf3f-48b9-9bcf-a8ddf8c1cf35
type: PREPAID
name: My test commit
description: My test commit description
product:
id: 2e30f074-d04c-412e-a134-851ebfa5ceb2
name: My product A
applicable_product_ids:
- 13a2179b-f0cb-460b-85a1-cd42964ca533
access_schedule:
credit_type:
id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2
name: USD (cents)
schedule_items:
- id: 2d45952c-5a6e-43a9-8aab-f61ee21be81a
amount: 10000000
starting_at_offset:
unit: MONTHS
value: 1
duration:
unit: MONTHS
value: 3
invoice_schedule:
credit_type:
id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2
name: USD (cents)
schedule_items:
- id: f15e4e23-f74e-4de4-9b3a-8b07434116c4
unit_price: 10000000
quantity: 1
date_offset:
unit: MONTHS
value: 4
do_not_invoice: false
overrides:
- id: 6cf3292a-e85c-4be6-822c-e25ba9d19757
starting_at_offset:
unit: MONTHS
value: 1
type: MULTIPLIER
multiplier: 0.1
override_specifiers:
- product_id: eae8903b-693b-41a7-8c0b-f23748c9a9c8
scheduled_charges:
- id: 04dbca69-0bc2-45c6-ba22-a53934353b10
name: Test Scheduled Charge
description: Test Scheduled Charge Description
product:
id: eae8903b-693b-41a7-8c0b-f23748c9a9c8
name: My product B
schedule:
credit_type:
id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2
name: USD (cents)
schedule_items:
- id: f15e4e23-f74e-4de4-9b3a-8b07434116c4
unit_price: 10000000
quantity: 1
date_offset:
unit: MONTHS
value: 4
- id: 67ee9504-ae43-4317-b70e-1c449910e14f
name: Test Package 2
commits: []
overrides: []
scheduled_charges: []
usage_statement_schedule:
frequency: MONTHLY
created_at: '2021-07-10T00:00:00.000Z'
created_by: Bob
next_page: eyJvZmZzZXQiOjF9
tags:
- Packages
/v1/packages/archive:
post:
description: 'Archive a package. Archived packages cannot be used to create new contracts. However, existing contracts associated with the package will continue to function as normal. Once you archive a package, you can still retrieve it in the UI and API, but you cannot unarchive it.
'
operationId: archivePackage-v1
summary: Archive a package
tags:
- Packages
requestBody:
content:
application/json:
schema:
type: object
required:
- package_id
additionalProperties: false
properties:
package_id:
type: string
format: uuid
description: ID of the package to archive
example:
package_id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/Id'
example:
data:
id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
BillingProviderDeliveryMethodType:
type: string
enum:
- direct_to_billing_provider
- aws_sqs
- tackle
- aws_sns
SpendThresholdConfiguration:
type: object
required:
- is_enabled
- threshold_amount
- commit
- payment_gate_config
properties:
is_enabled:
type: boolean
description: 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.
threshold_amount:
description: Specify the threshold amount for the contract. Each time the contract's usage hits this amount, a threshold charge will be initiated.
type: number
commit:
$ref: '#/components/schemas/SpendThresholdCommit'
payment_gate_config:
$ref: '#/components/schemas/PaymentGateConfig'
discount_configuration:
x-mint:
groups:
- ff:threshold-billing-discounts
$ref: '#/components/schemas/DiscountConfiguration'
SubscriptionSeatConfig:
type: object
required:
- seat_group_key
properties:
seat_group_key:
type: string
description: 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.
RelativeSchedulePointInTime:
type: object
required:
- credit_type
- schedule_items
properties:
credit_type:
$ref: '#/components/schemas/CreditType'
schedule_items:
type: array
items:
type: object
required:
- id
- unit_price
- quantity
- date_offset
properties:
id:
type: string
format: uuid
unit_price:
type: number
quantity:
type: number
date_offset:
$ref: '#/components/schemas/RelativeDate'
OverrideTemplate:
type: object
required:
- id
- starting_at_offset
- override_specifiers
properties:
id:
type: string
format: uuid
product:
type: object
required:
- id
- name
properties:
id:
type: string
format: uuid
name:
type: string
applicable_product_tags:
type: array
items:
type: string
override_specifiers:
type: array
items:
$ref: '#/components/schemas/OverrideSpecifierTemplate'
starting_at_offset:
$ref: '#/components/schemas/RelativeDate'
duration:
$ref: '#/components/schemas/RelativeDate'
entitled:
type: boolean
type:
type: string
enum:
- OVERWRITE
- MULTIPLIER
- TIERED
priority:
type: number
multiplier:
type: number
overwrite_rate:
$ref: '#/components/schemas/OverwriteRate'
override_tiers:
type: array
items:
$ref: '#/components/schemas/OverrideTier'
is_commit_specific:
type: boolean
target:
type: string
enum:
- COMMIT_RATE
- LIST_RATE
SubscriptionConfigAllocation:
type: string
enum:
- INDIVIDUAL
- POOLED
BaseThresholdCommit:
type: object
required:
- product_id
properties:
product_id:
type: string
description: The commit product that will be used to generate the line item for commit payment.
name:
type: string
description: Specify the name of the line item for the threshold charge. If left blank, it will default to the commit product name.
description:
type: string
priority:
type: number
description: The priority of the commit, used to determine drawdown order. Lower priority commits are consumed first. Defaults to 100 if not specified.
ExcludeSpecifier:
type: object
properties:
product_tags:
type: array
items:
type: string
description: If provided, the specifier will not apply to products with all the specified tags.
PackageAlias:
type: object
required:
- name
properties:
name:
type: string
starting_at:
type: string
format: date-time
ending_before:
type: string
format: date-time
PrepaidBalanceThresholdCommit:
type: object
allOf:
- $ref: '#/components/schemas/BaseThresholdCommit'
- type: object
properties:
applicable_product_ids:
type: array
items:
type: string
format: uuid
description: 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.
applicable_product_tags:
type: array
items:
type: string
description: 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.
specifiers:
x-mint:
groups:
- ff:commit-specifiers
type: array
description: 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`.
items:
$ref: '#/components/schemas/CommitSpecifierInput'
SubscriptionProration:
type: object
required:
- is_prorated
- invoice_behavior
properties:
is_prorated:
type: boolean
invoice_behavior:
type: string
enum:
- BILL_IMMEDIATELY
- BILL_ON_NEXT_COLLECTION_DATE
- bill_immediately
- bill_on_next_collection_date
DiscountConfiguration:
type: object
required:
- payment_fraction
properties:
payment_fraction:
type: number
description: The fraction of the original amount that the customer pays after applying the discount. For example, 0.85 means the customer pays 85% of the original amount (a 15% discount).
MinimumConfig:
type: object
description: Only set for TIERED_PERCENTAGE or PERCENTAGE rate_type.
required:
- minimum
properties:
minimum:
type: number
CreditTemplate:
type: object
required:
- id
- type
- product
properties:
id:
type: string
format: uuid
name:
type: string
description:
type: string
priority:
type: number
custom_fields:
x-cf-entity: package_credit
$ref: '#/components/schemas/CustomField'
product:
type: object
required:
- id
- name
properties:
id:
type: string
format: uuid
name:
type: string
applicable_product_ids:
type: array
items:
type: string
format: uuid
applicable_product_tags:
type: array
items:
type: string
specifiers:
type: array
description: 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.
items:
$ref: '#/components/schemas/CommitSpecifier'
access_schedule:
$ref: '#/components/schemas/RelativeScheduleDuration'
rate_type:
type: string
enum:
- COMMIT_RATE
- LIST_RATE
RecurringCommitSubscriptionConfigTemplate:
type: object
required:
- allocation
- apply_seat_increase_config
- subscription_template_id
properties:
allocation:
$ref: '#/components/schemas/SubscriptionConfigAllocation'
apply_seat_increase_config:
$ref: '#/components/schemas/ApplySeatIncreaseConfigForRecurringCommit'
subscription_template_id:
type: string
format: uuid
OverwriteRate:
type: object
required:
- rate_type
properties:
rate_type:
type: string
enum:
- FLAT
- flat
- PERCENTAGE
- percentage
- SUBSCRIPTION
- subscription
- TIERED
- tiered
- TIERED_PERCENTAGE
- tiered_percentage
- CUSTOM
- custom
x-mint-enum:
CUSTOM:
- client_id:5b9e3072-415b-4842-94f0-0b6700c8b6be
- client_id:179e395f-5349-4fe2-bf12-64ab4e5bc560
- client_id:f157d376-0781-4ef3-9db9-775a9052148e
- client_id:7dd2f652-7629-4925-9069-77f5c5d3db37
- client_id:c0ce3dc0-6d3e-4f6b-aadf-dfb90f2bf9f5
- client_id:cf874b25-ca3b-460b-b6fe-5f33b3c2ea33
- client_id:97c07a0c-70db-448a-a1d4-adcd2b8bd1c7
custom:
- client_id:5b9e3072-415b-4842-94f0-0b6700c8b6be
- client_id:179e395f-5349-4fe2-bf12-64ab4e5bc560
- client_id:f157d376-0781-4ef3-9db9-775a9052148e
- client_id:7dd2f652-7629-4925-9069-77f5c5d3db37
- client_id:c0ce3dc0-6d3e-4f6b-aadf-dfb90f2bf9f5
- client_id:cf874b25-ca3b-460b-b6fe-5f33b3c2ea33
- client_id:97c07a0c-70db-448a-a1d4-adcd2b8bd1c7
SUBSCRIPTION:
- ff:legacy-subscriptions-enabled
subscription:
- ff:legacy-subscriptions-enabled
TIERED_PERCENTAGE:
- ff:support-charge-ga
tiered_percentage:
- ff:support-charge-ga
price:
type: number
description: 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.
quantity:
type: number
x-mint:
groups:
- ff:legacy-subscriptions-enabled
description: Default quantity. For SUBSCRIPTION rate_type, this must be >=0.
is_prorated:
type: boolean
x-mint:
groups:
- ff:legacy-subscriptions-enabled
description: Default proration configuration. Only valid for SUBSCRIPTION rate_type. Must be set to true.
tiers:
type: array
items:
$ref: '#/components/schemas/Tier'
description: Only set for TIERED rate_type.
minimum_config:
x-stainless-skip: true
x-mint:
groups:
- ff:support-charge-ga
$ref: '#/components/schemas/MinimumConfig'
custom_rate:
x-mint:
groups:
- client_id:5b9e3072-415b-4842-94f0-0b6700c8b6be
- client_id:179e395f-5349-4fe2-bf12-64ab4e5bc560
- client_id:f157d376-0781-4ef3-9db9-775a9052148e
- client_id:7dd2f652-7629-4925-9069-77f5c5d3db37
- client_id:c0ce3dc0-6d3e-4f6b-aadf-dfb90f2bf9f5
- client_id:cf874b25-ca3b-460b-b6fe-5f33b3c2ea33
- client_id:97c07a0c-70db-448a-a1d4-adcd2b8bd1c7
type: object
additionalProperties: true
description: Only set for CUSTOM rate_type. This field is interpreted by custom rate processors.
credit_type:
$ref: '#/components/schemas/CreditType'
SubscriptionRate:
type: object
required:
- billing_frequency
- product
properties:
billing_frequency:
type: string
enum:
- MONTHLY
- QUARTERLY
- ANNUAL
- WEEKLY
- monthly
- quarterly
- annual
- weekly
product:
type: object
required:
- id
- name
properties:
id:
type: string
format: uuid
name:
type: string
UsageStatementScheduleTemplate:
type: object
required:
- frequency
properties:
frequency:
type: string
enum:
- MONTHLY
- QUARTERLY
- ANNUAL
- WEEKLY
day:
type: string
enum:
- FIRST_OF_MONTH
- CONTRACT_START
CustomField:
type: object
description: 'Custom fields to be added eg. { "key1": "value1", "key2": "value2" }'
additionalProperties:
type: string
SpendThresholdCommit:
type: object
allOf:
- $ref: '#/components/schemas/BaseThresholdCommit'
UniquenessKey:
type: string
minLength: 1
maxLength: 128
description: 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.
Error:
required:
- message
type: object
properties:
message:
type: string
Tier:
type: object
required:
- price
properties:
size:
type: number
price:
type: number
Id:
required:
- id
type: object
properties:
id:
type: string
format: uuid
RelativeDate:
type: object
required:
- value
- unit
properties:
value:
type: integer
unit:
type: string
enum:
- DAYS
- WEEKS
- MONTHS
- YEARS
OverrideSpecifierTemplate:
type: object
properties:
product_id:
type: string
format: uuid
product_tags:
type: array
items:
type: string
pricing_group_values:
type: object
additionalProperties:
type: string
presentation_group_values:
type: object
additionalProperties:
type: string
nullable: true
commit_template_ids:
type: array
items:
type: string
recurring_commit_template_ids:
type: array
items:
type: string
billing_frequency:
type: string
enum:
- MONTHLY
- QUARTERLY
- ANNUAL
- WEEKLY
exclude:
x-stainless-skip: true
x-mint:
groups:
- ff:exclude-specifiers-ga
type: array
description: If provided, the specifier will not apply to product usage that matches the inclusion criteria and any of the excluding values.
items:
$ref: '#/components/schemas/ExcludeSpecifier'
PrepaidBalanceThresholdConfiguration:
type: object
required:
- is_enabled
- threshold_amount
- recharge_to_amount
- commit
- payment_gate_config
properties:
is_enabled:
type: boolean
description: 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.
threshold_amount:
description: Specify the threshold amount for the contract. Each time the contract's prepaid balance lowers to this amount, a threshold charge will be initiated.
type: number
recharge_to_amount:
description: Specify the amount the balance should be recharged to.
type: number
custom_credit_type_id:
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.
type: string
format: uuid
commit:
$ref: '#/components/schemas/PrepaidBalanceThresholdCommit'
payment_gate_config:
$ref: '#/components/schemas/PaymentGateConfig'
discount_configuration:
x-mint:
groups:
- ff:threshold-billing-discounts
$ref: '#/components/schemas/DiscountConfiguration'
RecurringCreditTemplate:
type: object
required:
- id
- product
- access_amount
- priority
- commit_duration
- starting_at_offset
- rate_type
properties:
id:
type: string
format: uuid
name:
type: string
product:
type: object
required:
- id
- name
properties:
id:
type: string
format: uuid
name:
type: string
access_amount:
type: object
required:
- unit_price
- credit_type_id
properties:
unit_price:
type: number
quantity:
type: number
credit_type_id:
type: string
format: uuid
description: The amount of commit to grant.
description:
type: string
rollover_fraction:
type: number
description: 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.
priority:
type: number
applicable_product_ids:
type: array
items:
type: string
format: uuid
description: Will be passed down to the individual commits
applicable_product_tags:
type: array
items:
type: string
description: Will be passed down to the individual commits
specifiers:
type: array
description: 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.
items:
$ref: '#/components/schemas/CommitSpecifier'
rate_type:
type: string
enum:
- COMMIT_RATE
- LIST_RATE
description: Whether the created commits will use the commit rate or list rate
starting_at_offset:
$ref: '#/components/schemas/RelativeDate'
description: Offset relative to the contract start date that determines the start time for the first commit
duration:
$ref: '#/components/schemas/RelativeDate'
description: Offset relative to the recurring credit start that determines when the contract will stop creating recurring commits. optional
commit_duration:
type: object
required:
- value
properties:
value:
type: number
unit:
type: string
enum:
- PERIODS
description: The amount of time each of the created commits will be valid for
recurrence_frequency:
type: string
enum:
- MONTHLY
- QUARTERLY
- ANNUAL
- WEEKLY
description: '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.'
proration:
type: string
enum:
- NONE
- FIRST
- LAST
- FIRST_AND_LAST
description: 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).
subscription_config:
description: Attach a subscription to the recurring commit/credit.
$ref: '#/components/schemas/RecurringCommitSubscriptionConfigTemplate'
ApplySeatIncreaseConfigForRecurringCommit:
type: object
required:
- is_prorated
properties:
is_prorated:
type: boolean
description: Indicat
# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/metronome/refs/heads/main/openapi/metronome-packages-api-openapi.yml