Zuplo
Zuplo Developer API
Zuplo Developer API

Metering - Plans

Download schema

API Metering plan management

List plans

GET
https://dev.zuplo.com
/v3/metering/{bucketId}/plans

⚠️ Preview: The Metering APIs are in preview and subject to change.

List all plans.

List plans › path Parameters

bucketId
​string · required

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

List plans › query Parameters

includeDeleted
​boolean · style: form

Include deleted plans in response.

Usage: ?includeDeleted=true

Default: false
id
​string[] · style: form

Filter by plan.id attribute

key
​string[] · style: form

Filter by plan.key attribute

​object · style: deepObject

Filter by plan.key and plan.version attributes

status
​PlanStatus[] · style: form

Only 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
Enum values:
draft
active
archived
scheduled
currency
​CurrencyCode[] · style: form

Filter by plan.currency attribute

page
​integer · min: 1 · style: form

Page index.

Default is 1.

Default: 1
pageSize
​integer · min: 1 · max: 1000 · style: form

The maximum number of items per page.

Default is 100.

Default: 100
order
​SortOrder · enum · style: form

The order direction.

The order direction.

Enum values:
ASC
DESC
Default: ASC
orderBy
​PlanOrderBy · enum · style: form

The order by field.

Order by options for plans.

Enum values:
id
key
version
created_at
updated_at

List plans › Responses

The request has succeeded.

Paginated response
PlanPaginatedResponse
totalCount
​integer · required

The total number of items.

Example: 500
page
​integer · required

The page index.

Example: 1
pageSize
​integer · required

The maximum number of items per page.

Example: 100
​Plan[] · required

The items in the current page.

Create a plan

POST
https://dev.zuplo.com
/v3/metering/{bucketId}/plans

⚠️ 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.

Create a plan › path Parameters

bucketId
​string · required

The 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

Resource create operation model.
PlanCreate
name
​string · minLength: 1 · maxLength: 256 · required

Human-readable name for the resource. Between 1 and 256 characters.

key
​string · minLength: 1 · maxLength: 64 · pattern: ^[a-z0-9]+(?:_[a-z0-… · required

A semi-unique identifier for the resource.

currency
​string · minLength: 3 · maxLength: 3 · pattern: ^[A-Z]{3}$ · required

The currency code of the plan.

Example: USD
Default: USD
billingCadence
​string · duration · required

The 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).

Example: P1M
​PlanPhase[] · minItems: 1 · required

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.

description
​string · maxLength: 1024

Optional description of the resource. Maximum 1024 characters.

​object | null

Additional metadata for the resource.

Example: {"externalId":"019142cc-a016-796a-8113-1a942fecd26d"}
​object

Default pro-rating configuration for subscriptions using this plan.

Default: {"enabled":true,"mode":"max_consumption_based"}

Create a plan › Responses

The request has succeeded and a new resource has been created as a result.

Plans provide a template for subscriptions.
Plan
id
​string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

A unique identifier for the resource.

Example: 01G65Z755AFWAKHE12NY0CQ9FH
name
​string · minLength: 1 · maxLength: 256 · required

Human-readable name for the resource. Between 1 and 256 characters.

createdAt
​string · date-time · readOnly · required

Timestamp of when the resource was created.

Example: 2024-01-01T01:01:01.001Z
updatedAt
​string · date-time · readOnly · required

Timestamp of when the resource was last updated.

Example: 2024-01-01T01:01:01.001Z
key
​string · minLength: 1 · maxLength: 64 · pattern: ^[a-z0-9]+(?:_[a-z0-… · required

A semi-unique identifier for the resource.

version
​integer · min: 1 · readOnly · required

Version of the plan. Incremented when the plan is updated.

Default: 1
currency
​string · minLength: 3 · maxLength: 3 · pattern: ^[A-Z]{3}$ · required

The currency code of the plan.

Example: USD
Default: USD
billingCadence
​string · duration · required

The 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).

Example: P1M
status
​string · enum · readOnly · required

The 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
Enum values:
draft
active
archived
scheduled
​PlanPhase[] · minItems: 1 · required

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.

​array | null · readOnly · required

List of validation errors.

paymentMethodRequired
​boolean · readOnly · required

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

description
​string · maxLength: 1024

Optional description of the resource. Maximum 1024 characters.

​object | null

Additional metadata for the resource.

Example: {"externalId":"019142cc-a016-796a-8113-1a942fecd26d"}
deletedAt
​string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

Example: 2024-01-01T01:01:01.001Z
​object

Default pro-rating configuration for subscriptions using this plan.

Default: {"enabled":true,"mode":"max_consumption_based"}
effectiveFrom
​string · date-time · readOnly

The date and time when the plan becomes effective. When not specified, the plan is a draft.

Example: 2023-01-01T01:01:01.001Z
effectiveTo
​string · date-time · readOnly

The date and time when the plan is no longer effective. When not specified, the plan is effective indefinitely.

Example: 2023-01-01T01:01:01.001Z

Get plan

GET
https://dev.zuplo.com
/v3/metering/{bucketId}/plans/{planId}

⚠️ 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.

Get plan › path Parameters

bucketId
​string · required

The 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
​string · minLength: 1 · maxLength: 64 · pattern: ^[a-z0-9]+(?:_[a-z0-… · required

Get plan › query Parameters

includeLatest
​boolean · style: form

Include latest version of the Plan instead of the version in active state.

Usage: ?includeLatest=true

Default: false

Get plan › Responses

The request has succeeded.

Plans provide a template for subscriptions.
Plan
id
​string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

A unique identifier for the resource.

Example: 01G65Z755AFWAKHE12NY0CQ9FH
name
​string · minLength: 1 · maxLength: 256 · required

Human-readable name for the resource. Between 1 and 256 characters.

createdAt
​string · date-time · readOnly · required

Timestamp of when the resource was created.

Example: 2024-01-01T01:01:01.001Z
updatedAt
​string · date-time · readOnly · required

Timestamp of when the resource was last updated.

Example: 2024-01-01T01:01:01.001Z
key
​string · minLength: 1 · maxLength: 64 · pattern: ^[a-z0-9]+(?:_[a-z0-… · required

A semi-unique identifier for the resource.

version
​integer · min: 1 · readOnly · required

Version of the plan. Incremented when the plan is updated.

Default: 1
currency
​string · minLength: 3 · maxLength: 3 · pattern: ^[A-Z]{3}$ · required

The currency code of the plan.

Example: USD
Default: USD
billingCadence
​string · duration · required

The 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).

Example: P1M
status
​string · enum · readOnly · required

The 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
Enum values:
draft
active
archived
scheduled
​PlanPhase[] · minItems: 1 · required

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.

​array | null · readOnly · required

List of validation errors.

paymentMethodRequired
​boolean · readOnly · required

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

description
​string · maxLength: 1024

Optional description of the resource. Maximum 1024 characters.

​object | null

Additional metadata for the resource.

Example: {"externalId":"019142cc-a016-796a-8113-1a942fecd26d"}
deletedAt
​string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

Example: 2024-01-01T01:01:01.001Z
​object

Default pro-rating configuration for subscriptions using this plan.

Default: {"enabled":true,"mode":"max_consumption_based"}
effectiveFrom
​string · date-time · readOnly

The date and time when the plan becomes effective. When not specified, the plan is a draft.

Example: 2023-01-01T01:01:01.001Z
effectiveTo
​string · date-time · readOnly

The date and time when the plan is no longer effective. When not specified, the plan is effective indefinitely.

Example: 2023-01-01T01:01:01.001Z

Update a plan

PUT
https://dev.zuplo.com
/v3/metering/{bucketId}/plans/{planId}

⚠️ Preview: The Metering APIs are in preview and subject to change.

Update plan by id.

Update a plan › path Parameters

bucketId
​string · required

The 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
​string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Update a plan › Request Body

Resource update operation model.
PlanReplaceUpdate
name
​string · minLength: 1 · maxLength: 256 · required

Human-readable name for the resource. Between 1 and 256 characters.

billingCadence
​string · duration · required

The 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).

Example: P1M
​PlanPhase[] · minItems: 1 · required

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.

description
​string · maxLength: 1024

Optional description of the resource. Maximum 1024 characters.

​object | null

Additional metadata for the resource.

Example: {"externalId":"019142cc-a016-796a-8113-1a942fecd26d"}
​object

Default pro-rating configuration for subscriptions using this plan.

Default: {"enabled":true,"mode":"max_consumption_based"}

Update a plan › Responses

The request has succeeded.

Plans provide a template for subscriptions.
Plan
id
​string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

A unique identifier for the resource.

Example: 01G65Z755AFWAKHE12NY0CQ9FH
name
​string · minLength: 1 · maxLength: 256 · required

Human-readable name for the resource. Between 1 and 256 characters.

createdAt
​string · date-time · readOnly · required

Timestamp of when the resource was created.

Example: 2024-01-01T01:01:01.001Z
updatedAt
​string · date-time · readOnly · required

Timestamp of when the resource was last updated.

Example: 2024-01-01T01:01:01.001Z
key
​string · minLength: 1 · maxLength: 64 · pattern: ^[a-z0-9]+(?:_[a-z0-… · required

A semi-unique identifier for the resource.

version
​integer · min: 1 · readOnly · required

Version of the plan. Incremented when the plan is updated.

Default: 1
currency
​string · minLength: 3 · maxLength: 3 · pattern: ^[A-Z]{3}$ · required

The currency code of the plan.

Example: USD
Default: USD
billingCadence
​string · duration · required

The 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).

Example: P1M
status
​string · enum · readOnly · required

The 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
Enum values:
draft
active
archived
scheduled
​PlanPhase[] · minItems: 1 · required

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.

​array | null · readOnly · required

List of validation errors.

paymentMethodRequired
​boolean · readOnly · required

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

description
​string · maxLength: 1024

Optional description of the resource. Maximum 1024 characters.

​object | null

Additional metadata for the resource.

Example: {"externalId":"019142cc-a016-796a-8113-1a942fecd26d"}
deletedAt
​string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

Example: 2024-01-01T01:01:01.001Z
​object

Default pro-rating configuration for subscriptions using this plan.

Default: {"enabled":true,"mode":"max_consumption_based"}
effectiveFrom
​string · date-time · readOnly

The date and time when the plan becomes effective. When not specified, the plan is a draft.

Example: 2023-01-01T01:01:01.001Z
effectiveTo
​string · date-time · readOnly

The date and time when the plan is no longer effective. When not specified, the plan is effective indefinitely.

Example: 2023-01-01T01:01:01.001Z

Delete plan

DELETE
https://dev.zuplo.com
/v3/metering/{bucketId}/plans/{planId}

⚠️ 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.

Delete plan › path Parameters

bucketId
​string · required

The 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
​string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Delete plan › Responses

There is no content to send for this request, but the headers may be useful.

No data returned

Archive plan version

POST
https://dev.zuplo.com
/v3/metering/{bucketId}/plans/{planId}/archive

⚠️ Preview: The Metering APIs are in preview and subject to change.

Archive a plan version.

Archive plan version › path Parameters

bucketId
​string · required

The 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
​string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Archive plan version › Responses

The request has succeeded.

Plans provide a template for subscriptions.
Plan
id
​string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

A unique identifier for the resource.

Example: 01G65Z755AFWAKHE12NY0CQ9FH
name
​string · minLength: 1 · maxLength: 256 · required

Human-readable name for the resource. Between 1 and 256 characters.

createdAt
​string · date-time · readOnly · required

Timestamp of when the resource was created.

Example: 2024-01-01T01:01:01.001Z
updatedAt
​string · date-time · readOnly · required

Timestamp of when the resource was last updated.

Example: 2024-01-01T01:01:01.001Z
key
​string · minLength: 1 · maxLength: 64 · pattern: ^[a-z0-9]+(?:_[a-z0-… · required

A semi-unique identifier for the resource.

version
​integer · min: 1 · readOnly · required

Version of the plan. Incremented when the plan is updated.

Default: 1
currency
​string · minLength: 3 · maxLength: 3 · pattern: ^[A-Z]{3}$ · required

The currency code of the plan.

Example: USD
Default: USD
billingCadence
​string · duration · required

The 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).

Example: P1M
status
​string · enum · readOnly · required

The 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
Enum values:
draft
active
archived
scheduled
​PlanPhase[] · minItems: 1 · required

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.

​array | null · readOnly · required

List of validation errors.

paymentMethodRequired
​boolean · readOnly · required

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

description
​string · maxLength: 1024

Optional description of the resource. Maximum 1024 characters.

​object | null

Additional metadata for the resource.

Example: {"externalId":"019142cc-a016-796a-8113-1a942fecd26d"}
deletedAt
​string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

Example: 2024-01-01T01:01:01.001Z
​object

Default pro-rating configuration for subscriptions using this plan.

Default: {"enabled":true,"mode":"max_consumption_based"}
effectiveFrom
​string · date-time · readOnly

The date and time when the plan becomes effective. When not specified, the plan is a draft.

Example: 2023-01-01T01:01:01.001Z
effectiveTo
​string · date-time · readOnly

The date and time when the plan is no longer effective. When not specified, the plan is effective indefinitely.

Example: 2023-01-01T01:01:01.001Z

Publish plan

POST
https://dev.zuplo.com
/v3/metering/{bucketId}/plans/{planId}/publish

⚠️ Preview: The Metering APIs are in preview and subject to change.

Publish a plan version.

Publish plan › path Parameters

bucketId
​string · required

The 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
​string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Publish plan › Responses

The request has succeeded.

Plans provide a template for subscriptions.
Plan
id
​string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

A unique identifier for the resource.

Example: 01G65Z755AFWAKHE12NY0CQ9FH
name
​string · minLength: 1 · maxLength: 256 · required

Human-readable name for the resource. Between 1 and 256 characters.

createdAt
​string · date-time · readOnly · required

Timestamp of when the resource was created.

Example: 2024-01-01T01:01:01.001Z
updatedAt
​string · date-time · readOnly · required

Timestamp of when the resource was last updated.

Example: 2024-01-01T01:01:01.001Z
key
​string · minLength: 1 · maxLength: 64 · pattern: ^[a-z0-9]+(?:_[a-z0-… · required

A semi-unique identifier for the resource.

version
​integer · min: 1 · readOnly · required

Version of the plan. Incremented when the plan is updated.

Default: 1
currency
​string · minLength: 3 · maxLength: 3 · pattern: ^[A-Z]{3}$ · required

The currency code of the plan.

Example: USD
Default: USD
billingCadence
​string · duration · required

The 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).

Example: P1M
status
​string · enum · readOnly · required

The 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
Enum values:
draft
active
archived
scheduled
​PlanPhase[] · minItems: 1 · required

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.

​array | null · readOnly · required

List of validation errors.

paymentMethodRequired
​boolean · readOnly · required

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

description
​string · maxLength: 1024

Optional description of the resource. Maximum 1024 characters.

​object | null

Additional metadata for the resource.

Example: {"externalId":"019142cc-a016-796a-8113-1a942fecd26d"}
deletedAt
​string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

Example: 2024-01-01T01:01:01.001Z
​object

Default pro-rating configuration for subscriptions using this plan.

Default: {"enabled":true,"mode":"max_consumption_based"}
effectiveFrom
​string · date-time · readOnly

The date and time when the plan becomes effective. When not specified, the plan is a draft.

Example: 2023-01-01T01:01:01.001Z
effectiveTo
​string · date-time · readOnly

The date and time when the plan is no longer effective. When not specified, the plan is effective indefinitely.

Example: 2023-01-01T01:01:01.001Z
Metering - MetersProjects