List plans
⚠️ Preview: The Metering APIs are in preview and subject to change.
List all plans.
path Parameters
bucketIdThe id of the bucket. Zuplo automatically creates buckets for your project. You can find it in your Zuplo Portal under the Settings tab for your project.
query Parameters
includeDeletedInclude deleted plans in response.
Usage: ?includeDeleted=true
idFilter by plan.id attribute
keyFilter by plan.key attribute
Filter by plan.key and plan.version attributes
statusOnly return plans with the given status.
Usage:
?status=active: return only the currently active plan?status=draft: return only the draft plan?status=archived: return only the archived plans
currencyFilter by plan.currency attribute
pagePage index.
Default is 1.
pageSizeThe maximum number of items per page.
Default is 100.
orderThe order direction.
The order direction.
orderByThe order by field.
Order by options for plans.
List plans › Responses
The request has succeeded.
totalCountThe total number of items.
pageThe page index.
pageSizeThe maximum number of items per page.
The items in the current page.
Create a plan
⚠️ Preview: The Metering APIs are in preview and subject to change.
Create a new plan or a new version of an existing plan.
If no plan exists with the given key, a new plan is created with version 1. If a plan with the given key already exists, a new draft version is created with an incremented version number. Only one draft version per plan key is allowed at a time.
path Parameters
bucketIdThe id of the bucket. Zuplo automatically creates buckets for your project. You can find it in your Zuplo Portal under the Settings tab for your project.
Create a plan › Request Body
nameHuman-readable name for the resource. Between 1 and 256 characters.
key^[a-z0-9]+(?:_[a-z0-… · requiredA semi-unique identifier for the resource.
currency^[A-Z]{3}$ · requiredThe currency code of the plan.
billingCadenceThe default billing cadence for subscriptions using this plan. Defines how often customers are billed using ISO8601 duration format. Examples: "P1M" (monthly), "P3M" (quarterly), "P1Y" (annually).
The plan phase or pricing ramp allows changing a plan's rate cards over time as a subscription progresses. A phase switch occurs only at the end of a billing period, ensuring that a single subscription invoice will not include charges from different phase prices.
descriptionOptional description of the resource. Maximum 1024 characters.
Additional metadata for the resource.
Default pro-rating configuration for subscriptions using this plan.
Alignment configuration for the plan.
Create a plan › Responses
The request has succeeded and a new resource has been created as a result.
id^[0-7][0-9A-HJKMNP-T… · requiredA unique identifier for the resource.
nameHuman-readable name for the resource. Between 1 and 256 characters.
createdAtTimestamp of when the resource was created.
updatedAtTimestamp of when the resource was last updated.
key^[a-z0-9]+(?:_[a-z0-… · requiredA semi-unique identifier for the resource.
versionVersion of the plan. Incremented when the plan is updated.
currency^[A-Z]{3}$ · requiredThe currency code of the plan.
billingCadenceThe default billing cadence for subscriptions using this plan. Defines how often customers are billed using ISO8601 duration format. Examples: "P1M" (monthly), "P3M" (quarterly), "P1Y" (annually).
statusThe status of the plan. Computed based on the effective start and end dates:
- draft = no effectiveFrom
- active = effectiveFrom <= now < effectiveTo
- archived / inactive = effectiveTo <= now
- scheduled = now < effectiveFrom < effectiveTo
The plan phase or pricing ramp allows changing a plan's rate cards over time as a subscription progresses. A phase switch occurs only at the end of a billing period, ensuring that a single subscription invoice will not include charges from different phase prices.
List of validation errors.
paymentMethodRequiredIndicates whether a payment method is required to create a subscription with this plan. Computed based on whether ANY phase has billable items (rate cards with prices). Aligns with the subscription validator's billing setup check which checks all phases.
descriptionOptional description of the resource. Maximum 1024 characters.
Additional metadata for the resource.
deletedAtTimestamp of when the resource was permanently deleted.
Default pro-rating configuration for subscriptions using this plan.
effectiveFromThe date and time when the plan becomes effective. When not specified, the plan is a draft.
effectiveToThe date and time when the plan is no longer effective. When not specified, the plan is effective indefinitely.
Alignment configuration for the plan.
Get plan
⚠️ Preview: The Metering APIs are in preview and subject to change.
Get a plan by id or key. The latest published version is returned if latter is used.
path Parameters
bucketIdThe id of the bucket. Zuplo automatically creates buckets for your project. You can find it in your Zuplo Portal under the Settings tab for your project.
planId^[a-z0-9]+(?:_[a-z0-… · requiredquery Parameters
includeLatestInclude latest version of the Plan instead of the version in active state.
Usage: ?includeLatest=true
Get plan › Responses
The request has succeeded.
id^[0-7][0-9A-HJKMNP-T… · requiredA unique identifier for the resource.
nameHuman-readable name for the resource. Between 1 and 256 characters.
createdAtTimestamp of when the resource was created.
updatedAtTimestamp of when the resource was last updated.
key^[a-z0-9]+(?:_[a-z0-… · requiredA semi-unique identifier for the resource.
versionVersion of the plan. Incremented when the plan is updated.
currency^[A-Z]{3}$ · requiredThe currency code of the plan.
billingCadenceThe default billing cadence for subscriptions using this plan. Defines how often customers are billed using ISO8601 duration format. Examples: "P1M" (monthly), "P3M" (quarterly), "P1Y" (annually).
statusThe status of the plan. Computed based on the effective start and end dates:
- draft = no effectiveFrom
- active = effectiveFrom <= now < effectiveTo
- archived / inactive = effectiveTo <= now
- scheduled = now < effectiveFrom < effectiveTo
The plan phase or pricing ramp allows changing a plan's rate cards over time as a subscription progresses. A phase switch occurs only at the end of a billing period, ensuring that a single subscription invoice will not include charges from different phase prices.
List of validation errors.
paymentMethodRequiredIndicates whether a payment method is required to create a subscription with this plan. Computed based on whether ANY phase has billable items (rate cards with prices). Aligns with the subscription validator's billing setup check which checks all phases.
descriptionOptional description of the resource. Maximum 1024 characters.
Additional metadata for the resource.
deletedAtTimestamp of when the resource was permanently deleted.
Default pro-rating configuration for subscriptions using this plan.
effectiveFromThe date and time when the plan becomes effective. When not specified, the plan is a draft.
effectiveToThe date and time when the plan is no longer effective. When not specified, the plan is effective indefinitely.
Alignment configuration for the plan.
Update a plan
⚠️ Preview: The Metering APIs are in preview and subject to change.
Update plan by id.
path Parameters
bucketIdThe id of the bucket. Zuplo automatically creates buckets for your project. You can find it in your Zuplo Portal under the Settings tab for your project.
planId^[0-7][0-9A-HJKMNP-T… · requiredUpdate a plan › Request Body
nameHuman-readable name for the resource. Between 1 and 256 characters.
billingCadenceThe default billing cadence for subscriptions using this plan. Defines how often customers are billed using ISO8601 duration format. Examples: "P1M" (monthly), "P3M" (quarterly), "P1Y" (annually).
The plan phase or pricing ramp allows changing a plan's rate cards over time as a subscription progresses. A phase switch occurs only at the end of a billing period, ensuring that a single subscription invoice will not include charges from different phase prices.
descriptionOptional description of the resource. Maximum 1024 characters.
Additional metadata for the resource.
Default pro-rating configuration for subscriptions using this plan.
Alignment configuration for the plan.
Update a plan › Responses
The request has succeeded.
id^[0-7][0-9A-HJKMNP-T… · requiredA unique identifier for the resource.
nameHuman-readable name for the resource. Between 1 and 256 characters.
createdAtTimestamp of when the resource was created.
updatedAtTimestamp of when the resource was last updated.
key^[a-z0-9]+(?:_[a-z0-… · requiredA semi-unique identifier for the resource.
versionVersion of the plan. Incremented when the plan is updated.
currency^[A-Z]{3}$ · requiredThe currency code of the plan.
billingCadenceThe default billing cadence for subscriptions using this plan. Defines how often customers are billed using ISO8601 duration format. Examples: "P1M" (monthly), "P3M" (quarterly), "P1Y" (annually).
statusThe status of the plan. Computed based on the effective start and end dates:
- draft = no effectiveFrom
- active = effectiveFrom <= now < effectiveTo
- archived / inactive = effectiveTo <= now
- scheduled = now < effectiveFrom < effectiveTo
The plan phase or pricing ramp allows changing a plan's rate cards over time as a subscription progresses. A phase switch occurs only at the end of a billing period, ensuring that a single subscription invoice will not include charges from different phase prices.
List of validation errors.
paymentMethodRequiredIndicates whether a payment method is required to create a subscription with this plan. Computed based on whether ANY phase has billable items (rate cards with prices). Aligns with the subscription validator's billing setup check which checks all phases.
descriptionOptional description of the resource. Maximum 1024 characters.
Additional metadata for the resource.
deletedAtTimestamp of when the resource was permanently deleted.
Default pro-rating configuration for subscriptions using this plan.
effectiveFromThe date and time when the plan becomes effective. When not specified, the plan is a draft.
effectiveToThe date and time when the plan is no longer effective. When not specified, the plan is effective indefinitely.
Alignment configuration for the plan.
Delete plan
⚠️ Preview: The Metering APIs are in preview and subject to change.
Soft delete plan by plan.id.
Once a plan is deleted it cannot be undeleted.
path Parameters
bucketIdThe id of the bucket. Zuplo automatically creates buckets for your project. You can find it in your Zuplo Portal under the Settings tab for your project.
planId^[0-7][0-9A-HJKMNP-T… · requiredDelete plan › Responses
There is no content to send for this request, but the headers may be useful.
Archive plan version
⚠️ Preview: The Metering APIs are in preview and subject to change.
Archive a plan version.
path Parameters
bucketIdThe id of the bucket. Zuplo automatically creates buckets for your project. You can find it in your Zuplo Portal under the Settings tab for your project.
planId^[0-7][0-9A-HJKMNP-T… · requiredArchive plan version › Responses
The request has succeeded.
id^[0-7][0-9A-HJKMNP-T… · requiredA unique identifier for the resource.
nameHuman-readable name for the resource. Between 1 and 256 characters.
createdAtTimestamp of when the resource was created.
updatedAtTimestamp of when the resource was last updated.
key^[a-z0-9]+(?:_[a-z0-… · requiredA semi-unique identifier for the resource.
versionVersion of the plan. Incremented when the plan is updated.
currency^[A-Z]{3}$ · requiredThe currency code of the plan.
billingCadenceThe default billing cadence for subscriptions using this plan. Defines how often customers are billed using ISO8601 duration format. Examples: "P1M" (monthly), "P3M" (quarterly), "P1Y" (annually).
statusThe status of the plan. Computed based on the effective start and end dates:
- draft = no effectiveFrom
- active = effectiveFrom <= now < effectiveTo
- archived / inactive = effectiveTo <= now
- scheduled = now < effectiveFrom < effectiveTo
The plan phase or pricing ramp allows changing a plan's rate cards over time as a subscription progresses. A phase switch occurs only at the end of a billing period, ensuring that a single subscription invoice will not include charges from different phase prices.
List of validation errors.
paymentMethodRequiredIndicates whether a payment method is required to create a subscription with this plan. Computed based on whether ANY phase has billable items (rate cards with prices). Aligns with the subscription validator's billing setup check which checks all phases.
descriptionOptional description of the resource. Maximum 1024 characters.
Additional metadata for the resource.
deletedAtTimestamp of when the resource was permanently deleted.
Default pro-rating configuration for subscriptions using this plan.
effectiveFromThe date and time when the plan becomes effective. When not specified, the plan is a draft.
effectiveToThe date and time when the plan is no longer effective. When not specified, the plan is effective indefinitely.
Alignment configuration for the plan.
Publish plan
⚠️ Preview: The Metering APIs are in preview and subject to change.
Publish a plan version.
path Parameters
bucketIdThe id of the bucket. Zuplo automatically creates buckets for your project. You can find it in your Zuplo Portal under the Settings tab for your project.
planId^[0-7][0-9A-HJKMNP-T… · requiredPublish plan › Responses
The request has succeeded.
id^[0-7][0-9A-HJKMNP-T… · requiredA unique identifier for the resource.
nameHuman-readable name for the resource. Between 1 and 256 characters.
createdAtTimestamp of when the resource was created.
updatedAtTimestamp of when the resource was last updated.
key^[a-z0-9]+(?:_[a-z0-… · requiredA semi-unique identifier for the resource.
versionVersion of the plan. Incremented when the plan is updated.
currency^[A-Z]{3}$ · requiredThe currency code of the plan.
billingCadenceThe default billing cadence for subscriptions using this plan. Defines how often customers are billed using ISO8601 duration format. Examples: "P1M" (monthly), "P3M" (quarterly), "P1Y" (annually).
statusThe status of the plan. Computed based on the effective start and end dates:
- draft = no effectiveFrom
- active = effectiveFrom <= now < effectiveTo
- archived / inactive = effectiveTo <= now
- scheduled = now < effectiveFrom < effectiveTo
The plan phase or pricing ramp allows changing a plan's rate cards over time as a subscription progresses. A phase switch occurs only at the end of a billing period, ensuring that a single subscription invoice will not include charges from different phase prices.
List of validation errors.
paymentMethodRequiredIndicates whether a payment method is required to create a subscription with this plan. Computed based on whether ANY phase has billable items (rate cards with prices). Aligns with the subscription validator's billing setup check which checks all phases.
descriptionOptional description of the resource. Maximum 1024 characters.
Additional metadata for the resource.
deletedAtTimestamp of when the resource was permanently deleted.
Default pro-rating configuration for subscriptions using this plan.
effectiveFromThe date and time when the plan becomes effective. When not specified, the plan is a draft.
effectiveToThe date and time when the plan is no longer effective. When not specified, the plan is effective indefinitely.
Alignment configuration for the plan.