Create subscription

post

Body

application/json

BillingSubscriptionCreate

Subscription create request.

labelsobject

Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types.

Keys must be of length 1-63 characters, and cannot start with “kong”, “konnect”, “mesh”, “kic”, or “_”.

Example:{"env":"test"}

customerobjectrequired

The customer to create the subscription for.

Show Child Parameters
planobjectrequired

The plan reference of the subscription.

Show Child Parameters
billing_anchorstring(date-time)

A billing anchor is the fixed point in time that determines the subscription’s recurring billing cycle.
It affects when charges occur and how prorations are calculated.
Common anchors:

  • Calendar month (1st of each month): 2025-01-01T00:00:00Z
  • Subscription anniversary (day customer signed up)
  • Custom date (customer-specified day)

If not provided, the subscription will be created with the subscription’s creation time as the billing anchor.

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

Response

application/json

Subscription created response.

BillingSubscription

Subscription.

idstringrequiredread-only

ULID (Universally Unique Lexicographically Sortable Identifier).

Match pattern:^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:01G65Z755AFWAKHE12NY0CQ9FH

labelsobject

Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types.

Keys must be of length 1-63 characters, and cannot start with “kong”, “konnect”, “mesh”, “kic”, or “_”.

Example:{"env":"test"}

created_atstring(date-time)read-only

An ISO-8601 timestamp representation of entity creation date.

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

updated_atstring(date-time)read-only

An ISO-8601 timestamp representation of entity last update date.

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

deleted_atstring(date-time)read-only

An ISO-8601 timestamp representation of entity deletion date.

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

customer_idstringrequiredread-only

The customer ID of the subscription.

Match pattern:^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:01G65Z755AFWAKHE12NY0CQ9FH

plan_idstringread-only

The plan ID of the subscription.
Set if subscription is created from a plan.

Match pattern:^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:01G65Z755AFWAKHE12NY0CQ9FH

billing_anchorstring(date-time)requiredread-only

A billing anchor is the fixed point in time that determines the subscription’s recurring billing cycle.
It affects when charges occur and how prorations are calculated.
Common anchors:

  • Calendar month (1st of each month): 2025-01-01T00:00:00Z
  • Subscription anniversary (day customer signed up)
  • Custom date (customer-specified day)

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

statusstringrequiredread-only

The status of the subscription.

Allowed values:activeinactivecanceledscheduled

post/openmeter/subscriptions

Body

{ "customer": {}, "plan": {} }
 
application/json

List subscriptions

get

Query Parameters

pageobject

Determines which page of the collection to retrieve.

Show Child Parameters
filterobject

Filter subscriptions.

Show Child Parameters

Response

application/json

Page paginated response.

SubscriptionPagePaginatedResponse

Page paginated response.

dataarray[object]required

Subscription.

Show Child Parameters
metaobjectrequired

returns the pagination information

Show Child Parameters
get/openmeter/subscriptions
 
application/json

Get subscription

get

Path Parameters

subscriptionIdstringrequired

ULID (Universally Unique Lexicographically Sortable Identifier).

Match pattern:^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:01G65Z755AFWAKHE12NY0CQ9FH

Response

application/json

Subscription response.

BillingSubscription

Subscription.

idstringrequiredread-only

ULID (Universally Unique Lexicographically Sortable Identifier).

Match pattern:^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:01G65Z755AFWAKHE12NY0CQ9FH

labelsobject

Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types.

Keys must be of length 1-63 characters, and cannot start with “kong”, “konnect”, “mesh”, “kic”, or “_”.

Example:{"env":"test"}

created_atstring(date-time)read-only

An ISO-8601 timestamp representation of entity creation date.

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

updated_atstring(date-time)read-only

An ISO-8601 timestamp representation of entity last update date.

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

deleted_atstring(date-time)read-only

An ISO-8601 timestamp representation of entity deletion date.

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

customer_idstringrequiredread-only

The customer ID of the subscription.

Match pattern:^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:01G65Z755AFWAKHE12NY0CQ9FH

plan_idstringread-only

The plan ID of the subscription.
Set if subscription is created from a plan.

Match pattern:^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:01G65Z755AFWAKHE12NY0CQ9FH

billing_anchorstring(date-time)requiredread-only

A billing anchor is the fixed point in time that determines the subscription’s recurring billing cycle.
It affects when charges occur and how prorations are calculated.
Common anchors:

  • Calendar month (1st of each month): 2025-01-01T00:00:00Z
  • Subscription anniversary (day customer signed up)
  • Custom date (customer-specified day)

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

statusstringrequiredread-only

The status of the subscription.

Allowed values:activeinactivecanceledscheduled

get/openmeter/subscriptions/{subscriptionId}
 
application/json

Cancel subscription

Cancels the subscription.
Will result in a scheduling conflict if there are other subscriptions scheduled to start after the cancelation time.

post

Path Parameters

subscriptionIdstringrequired

ULID (Universally Unique Lexicographically Sortable Identifier).

Match pattern:^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:01G65Z755AFWAKHE12NY0CQ9FH

Body

application/json

BillingSubscriptionCancel

Request for canceling a subscription.

timingOne Of

If not provided the subscription is canceled immediately.

Default:immediate

Example:immediate

BillingSubscriptionEditTimingEnumstring

Subscription edit timing.
When immediate, the requested changes take effect immediately.
When next_billing_cycle, the requested changes take effect at the next billing cycle.

Allowed values:immediatenext_billing_cycle

Response

application/json

Subscription updated response.

BillingSubscription

Subscription.

idstringrequiredread-only

ULID (Universally Unique Lexicographically Sortable Identifier).

Match pattern:^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:01G65Z755AFWAKHE12NY0CQ9FH

labelsobject

Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types.

Keys must be of length 1-63 characters, and cannot start with “kong”, “konnect”, “mesh”, “kic”, or “_”.

Example:{"env":"test"}

created_atstring(date-time)read-only

An ISO-8601 timestamp representation of entity creation date.

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

updated_atstring(date-time)read-only

An ISO-8601 timestamp representation of entity last update date.

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

deleted_atstring(date-time)read-only

An ISO-8601 timestamp representation of entity deletion date.

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

customer_idstringrequiredread-only

The customer ID of the subscription.

Match pattern:^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:01G65Z755AFWAKHE12NY0CQ9FH

plan_idstringread-only

The plan ID of the subscription.
Set if subscription is created from a plan.

Match pattern:^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:01G65Z755AFWAKHE12NY0CQ9FH

billing_anchorstring(date-time)requiredread-only

A billing anchor is the fixed point in time that determines the subscription’s recurring billing cycle.
It affects when charges occur and how prorations are calculated.
Common anchors:

  • Calendar month (1st of each month): 2025-01-01T00:00:00Z
  • Subscription anniversary (day customer signed up)
  • Custom date (customer-specified day)

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

statusstringrequiredread-only

The status of the subscription.

Allowed values:activeinactivecanceledscheduled

post/openmeter/subscriptions/{subscriptionId}/cancel

Body

{}
 
application/json

Change subscription

Closes a running subscription and starts a new one according to the specification.
Can be used for upgrades, downgrades, and plan changes.

post

Path Parameters

subscriptionIdstringrequired

ULID (Universally Unique Lexicographically Sortable Identifier).

Match pattern:^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:01G65Z755AFWAKHE12NY0CQ9FH

Body

application/json

BillingSubscriptionChange

Request for changing a subscription.

labelsobject

Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types.

Keys must be of length 1-63 characters, and cannot start with “kong”, “konnect”, “mesh”, “kic”, or “_”.

Example:{"env":"test"}

customerobjectrequired

The customer to create the subscription for.

Show Child Parameters
planobjectrequired

The plan reference of the subscription.

Show Child Parameters
billing_anchorstring(date-time)

A billing anchor is the fixed point in time that determines the subscription’s recurring billing cycle.
It affects when charges occur and how prorations are calculated.
Common anchors:

  • Calendar month (1st of each month): 2025-01-01T00:00:00Z
  • Subscription anniversary (day customer signed up)
  • Custom date (customer-specified day)

If not provided, the subscription will be created with the subscription’s creation time as the billing anchor.

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

timingOne Of
required

Timing configuration for the change, when the change should take effect.
For changing a subscription, the accepted values depend on the subscription configuration.

Example:immediate

BillingSubscriptionEditTimingEnumstring

Subscription edit timing.
When immediate, the requested changes take effect immediately.
When next_billing_cycle, the requested changes take effect at the next billing cycle.

Allowed values:immediatenext_billing_cycle

Response

application/json

The request has succeeded.

BillingSubscriptionChangeResponse

Response for changing a subscription.

currentobjectrequired

The current subscription before the change.

Show Child Parameters
nextobjectrequired

The new state of the subscription after the change.

Show Child Parameters
post/openmeter/subscriptions/{subscriptionId}/change

Body

{ "customer": {}, "plan": {}, "timing": {} }
 
application/json