Schemas - Zuplo Docs

ApiKeyBulkCreateOrUpdateBody

Zuplo.ApiKeys.ApiKeyCreateOrUpdateBody[]

Zuplo.ApiKeys.ApiKeyCreateOrUpdateBody

expiresOn

string · date-time

When the key expires.

description

string

The description of the api key.

key

string

The API key's value. You can use this parameter to override Zuplo's default key format, but this is not recommended as you will lose our API Key Leak Detection

Zuplo.Accounts.Account

A Zuplo account

id

string · required

The id of the account

Example: 103f832d-5331-42db-9d38-bbac05a68305

name

string · required

The name of the account

Example: my-account

label

string

The label of the account

Example: My Account

Zuplo.Accounts.AccountsList

Zuplo.Accounts.Account[] · required

Zuplo.ApiKeys.ApiKey

A Consumer can have any number of API keys associated with it. Each API Key shares the same identity (i.e. Consumer) when authenticating with this service. Keys can have their own description to note the use of the key and can have an expiration date. Expired keys will not be permitted to authenticate after their expiration.

createdOn

string · date-time · readOnly · required

When the item was created.

Example: 2023-04-18T05:54:34.408Z

updatedOn

string · date-time · readOnly · required

When the item was last updated.

Example: 2023-04-20T05:54:34.408Z

id

string · readOnly · required

expiresOn

string · date-time

When the key expires.

description

string

The description of the api key.

key

string

The API key's value. You can use this parameter to override Zuplo's default key format, but this is not recommended as you will lose our API Key Leak Detection

Zuplo.ApiKeys.ApiKeyCreateOrUpdateBody

expiresOn

string · date-time

When the key expires.

description

string

The description of the api key.

key

string

The API key's value. You can use this parameter to override Zuplo's default key format, but this is not recommended as you will lose our API Key Leak Detection

Zuplo.ApiKeys.ApiKeys

Zuplo.ApiKeys.ApiKey[] · required

limit

integer · uint32

offset

integer · uint32

total

integer · uint32

Zuplo.ApiKeys.Bucket

Top level group for API key mangement. A bucket could be used with a single Zuplo environment or shared among multiple environments or projects. By default a Zuplo API Gateway project will be created with several buckets that map to production, preview, and working copy environments.

createdOn

string · date-time · readOnly · required

When the item was created.

Example: 2023-04-18T05:54:34.408Z

updatedOn

string · date-time · readOnly · required

When the item was last updated.

Example: 2023-04-20T05:54:34.408Z

id

string · readOnly · required

name

string · pattern: ^[a-z0-9-]{5,128}$ · required

A friendly name for the bucket.

isRetrievable

boolean

Whether the API keys stored in the bucket are retrievable

description

string

A description of the bucket.

object

Key value pairs to associate with the bucket.

Zuplo.ApiKeys.BucketCreateBody

name

string · pattern: ^[a-z0-9-]{5,128}$ · required

A friendly name for the bucket.

description

string

A description of the bucket.

object

Key value pairs to associate with the bucket.

Zuplo.ApiKeys.BucketUpdateBody

description

string

A description of the bucket.

object

Key value pairs to associate with the bucket.

Zuplo.ApiKeys.Buckets

Zuplo.ApiKeys.Bucket[] · required

limit

integer · uint32

offset

integer · uint32

total

integer · uint32

Zuplo.ApiKeys.Consumer

Consumers are the core of the API Key service. The consumer is the 'identity' of any API Keys that are created.

createdOn

string · date-time · readOnly · required

When the item was created.

Example: 2023-04-18T05:54:34.408Z

updatedOn

string · date-time · readOnly · required

When the item was last updated.

Example: 2023-04-20T05:54:34.408Z

id

string · readOnly · required

name

string · pattern: ^[a-z0-9-]{1,128}$ · required

A friendly name for the consumer. This name is used as the default user.sub property in the API Key Authentication policy.

Zuplo.ApiKeys.ApiKey[]

description

string

A description of the consumer.

object

Key value pairs to associate with the consumer.

object

Generic metadata associated with the consumer.

Zuplo.ApiKeys.ConsumerCreateBody

name

string · pattern: ^[a-z0-9-]{1,128}$ · required

A friendly name for the consumer. This name is used as the default user.sub property in the API Key Authentication policy.

Email addresses of the managers to invite or a list of managers (with subs) to add to the consumer.

Zuplo.ApiKeys.ApiKey[]

description

string

A description of the consumer.

object

Key value pairs to associate with the consumer.

object

Generic metadata associated with the consumer.

Zuplo.ApiKeys.ConsumerUpdateBody

description

string

A description of the consumer.

object

Key value pairs to associate with the consumer.

object

Generic metadata associated with the consumer.

Zuplo.ApiKeys.Consumers

Zuplo.ApiKeys.Consumer[] · required

limit

integer · uint32

offset

integer · uint32

total

integer · uint32

Zuplo.ApiKeys.KeyFormat

string · enum

Enum values:

none

visible

masked

Zuplo.ApiKeys.Manager

Managers are users that have access to a consumer. Managers can be added directly to a consumer (using email and sub) or invited (using only email) to a consumer.

email

string · required

The email address of the manager

sub

string · required

The sub of the manager in the identity provider

Zuplo.ApiKeys.ManagerCreateBody

email

string · required

The email address of the manager

sub

string · required

The sub of the manager in the identity provider

Zuplo.ApiKeys.Managers

Zuplo.ApiKeys.Manager[] · required

limit

integer · uint32

offset

integer · uint32

total

integer · uint32

Zuplo.AuditLogs.ActingAs

Details about the user being impersonated, if applicable

sub

string · required

The subject identifier of the user being impersonated

email

string | null · required

The email address of the impersonated user (if available)

Zuplo.AuditLogs.Actor

Details about the actor who performed the action

sub

string · required

The subject identifier of the actor (user ID, API key, etc.)

email

string | null · required

The email address of the actor (only for user actors)

type

string · required

The type of actor (e.g., 'user', 'consumer', 'service', 'anonymous')

connection

string | null · required

The authentication connection used (e.g., 'auth0', 'google')

actingAs

object | null · required

Information about the user being impersonated, if any

object | null · required

Additional metadata about the actor

Zuplo.AuditLogs.AuditLog

An audit log entry representing an action performed in the system

action

string · required

The action that was performed (e.g., 'account.create', 'project.delete')

object | null · required

Additional metadata about the action

object · required

Details about the actor who performed the action

array | null · required

List of resources affected by this action

object · required

Contextual information about where and how the action was performed

object · required

Information about the API route that triggered this audit event

timestamp

string · date-time · required

The timestamp when the action occurred

requestId

string · required

The unique request ID for correlation

success

boolean | null · required

Whether the action was successful

error

string | null · required

Error message if the action failed

Zuplo.AuditLogs.AuditLogsPagination

Pagination information for audit logs

limit

integer · int32 · required

Maximum number of results returned

offset

integer · int32 · required

Number of results skipped

total

integer · int32 · required

Total number of results available

hasMore

boolean · required

Whether there are more results available

Zuplo.AuditLogs.AuditLogsResponse

Response containing a list of audit logs with pagination

Zuplo.AuditLogs.AuditLog[] · required

Array of audit log entries

object · required

Pagination information

Zuplo.AuditLogs.Context

Contextual information about where and how the action was performed

ipAddress

string | null · required

The IP address of the request

userAgent

string | null · required

The user agent string of the request

country

string | null · required

The ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB')

region

string | null · required

The region/state code (e.g., 'CA' for California)

city

string | null · required

The city name from which the request originated

postalCode

string | null · required

The postal/ZIP code

metroCode

string | null · required

The metro code (DMA code in the US)

asOrg

string | null · required

The Autonomous System organization (ISP name)

Zuplo.AuditLogs.Resource

A resource affected by the action

type

string · required

The type of resource (e.g., 'account', 'project', 'deployment')

id

string · required

The unique identifier of the resource

object | null · required

Additional metadata about the resource

Zuplo.AuditLogs.Route

Information about the API route that triggered this audit event

source

string | null · required

The source system or API that handled the request (e.g., 'api', 'gateway')

url

string | null · required

The full URL path of the request

method

string | null · required

The HTTP method used for the request

Zuplo.BuildLogs.BuildLogRow

string[] · minItems: 3 · maxItems: 3

A single build-log row, returned as a fixed 3-tuple of [timestamp (ISO 8601), severity, message].

Example: {"0":"2024-01-01T00:00:00.000Z","1":"INFO","2":"Build started"}

Zuplo.BuildLogs.BuildLogStage

string · enum

Enum values:

api

dev-portal

The build stage that produced a set of build logs. Wire values are kebab-case (api, dev-portal); the response groups logs under camelCase keys (api, devPortal). Mirrors tenant-api's DeploymentStageNameSchema — keep in sync when new stages are added upstream.

Zuplo.BuildLogs.BuildLogStepGroup

Build logs for a stage, grouped by build step. Keys are step names (e.g. "build"); values are ordered arrays of build-log rows.

Zuplo.BuildLogs.BuildLogRow[]

Zuplo.BuildLogs.BuildLogsData

Build logs grouped by stage (API vs Dev Portal) and then by build step.

object · required

Build logs for the API/gateway build stage, grouped by step.

object · required

Build logs for the Dev Portal build stage, grouped by step.

Zuplo.BuildLogs.BuildLogsResponse

Response containing the build logs for a deployment build.

object · required

Build logs grouped by stage and step.

Zuplo.ClientAuth.JwksResponse

object · required

Zuplo.ClientAuth.OAuthAccessTokenResponse

access_token

string · required

token_type

string · enum · required

Enum values:

Bearer

Example: Bearer

expires_in

integer · required

scope

string

Zuplo.ClientAuth.OAuthErrorResponse

error

string · required

error_description

string · required

Zuplo.ClientMtlsCaCertificates.ClientMtlsCaCertificate

A client mTLS CA certificate configured for an account.

id

string · readOnly · required

The unique identifier for the client mTLS CA certificate.

Example: cert_abc123

name

string · minLength: 1 · maxLength: 120 · required

The name of the client mTLS CA certificate.

Example: my_client_ca

object · required

Certificate information.

createdOn

string · date-time · readOnly · required

When the item was created.

Example: 2023-04-18T05:54:34.408Z

updatedOn

string · date-time · readOnly · required

When the item was last updated.

Example: 2023-04-20T05:54:34.408Z

Zuplo.ClientMtlsCaCertificates.ClientMtlsCaCertificateCreateBody

name

string · minLength: 1 · maxLength: 120 · required

The name of the client mTLS CA certificate.

Example: my_client_ca

certificate

string · minLength: 1 · required

The PEM-encoded CA certificate.

Zuplo.ClientMtlsCaCertificates.ClientMtlsCaCertificateInfo

Details parsed from a client mTLS CA certificate.

subject

string · required

Certificate subject.

Example: CN=Example Client CA

issuer

string · required

Certificate issuer.

Example: CN=Example Root CA

validFrom

string · required

Certificate valid from date.

Example: 2024-01-01T00:00:00Z

validTo

string · required

Certificate valid to date.

Example: 2025-01-01T00:00:00Z

serialNumber

string · required

Certificate serial number.

Example: 12345

Zuplo.ClientMtlsCaCertificates.ClientMtlsCaCertificateListResponse

Zuplo.ClientMtlsCaCertificates.ClientMtlsCaCertificate[] · required

List of client mTLS CA certificates.

offset

integer · int32 · required

Offset for pagination.

limit

integer · int32 · required

Limit for pagination.

Zuplo.ClientMtlsCaCertificates.ClientMtlsCaCertificateUpdateBody

name

string · minLength: 1 · maxLength: 120 · required

The name of the client mTLS CA certificate.

Example: my_client_ca

Zuplo.Common.ExpiresOnField

expiresOn

string · date-time · required

When the item will expire.

Example: 2050-04-18T05:54:34.408Z

Zuplo.Configurations.Configuration

accountName

string · required

projectName

string · required

environmentType

string · enum · required

Enum values:

production

preview

development

Example: production

systemConfigurations

string · required

Zuplo.ConsumerAnalytics.CallsByStatusCodeData

Zuplo.ConsumerAnalytics.CallsDetailData

consumer

string · readOnly · required

timeStamp

string · readOnly · required

totalCalls

integer · readOnly · required

Zuplo.ConsumerAnalytics.CallsByStatusCodeData[] · readOnly · required

Zuplo.ConsumerAnalytics.RecentCallsData

Zuplo.ConsumerAnalytics.RequestData[] · readOnly · required

Zuplo.ConsumerAnalytics.ReponseStatsByStatusCodeData

object · readOnly · required

Zuplo.ConsumerAnalytics.RequestData

consumer

string · readOnly · required

method

string · readOnly · required

routePath

string · readOnly · required

statusCode

string · readOnly · required

timeStamp

string · readOnly · required

city

string · readOnly · required

country

string · readOnly · required

Zuplo.ConsumerAnalytics.StatsByStatusCode.TimeWindowFilter

string · enum

Enum values:

last-hour

last-24-hours

last-7-days

last-30-days

last-3-months

Zuplo.ConsumerAnalytics.StatsByStatusCodeData

Zuplo.ConsumerAnalytics.StatsData[] · readOnly

Zuplo.ConsumerAnalytics.CallsDetailData[] · readOnly

Zuplo.ConsumerAnalytics.StatsData

totalCalls

integer · readOnly · required

consumer

string · readOnly · required

Zuplo.ConsumerAnalytics.CallsByStatusCodeData[] · readOnly · required

Zuplo.CustomDomains.CustomDomain

A custom domain configured for an account.

id

string · required

The unique identifier for the custom domain.

Example: cdm_01HZX8D7A1M9S0K4Y2N6P3Q8R5

accountName

string · required

The account that owns the custom domain.

Example: chocolate_great_buzzard

projectName

string · required

The project associated with the custom domain.

Example: todo-list-api

Zuplo.CustomDomains.CustomDomainDeployment[] · required

The deployments currently mapped to this hostname.

hostname

string · required

The hostname assigned to the custom domain.

Example: api.example.com

provider

string · enum · required

The provider backing the custom domain.

Enum values:

cloudflare

amazon

custom

alias

Example: cloudflare

Zuplo.CustomDomains.CustomDomainCreateBody

Request body for creating a custom domain.

hostname

string · required

The hostname to configure as a custom domain.

Example: api.example.com

deploymentName

string

The deployment to associate with the hostname.

Example: todo-list-api-main-59eec11

stage

string · enum

The stage to expose on the hostname.

Enum values:

api

dev-portal

Example: api

isDefault

boolean

Whether this domain should be the default domain for the deployment.

Example: true

isAlias

boolean

Whether the domain should be configured as an alias.

Example: false

Zuplo.CustomDomains.CustomDomainDeployment

A deployment bound to a custom domain.

deploymentName

string | null · required

The deployment name associated with the custom domain.

Example: todo-list-api-main-59eec11

branch

string | null · required

The branch associated with the deployment.

Example: main

environmentType

string · enum · required

The environment type associated with the deployment.

Enum values:

PRODUCTION

PREVIEW

WORKING_COPY

Example: PRODUCTION

isDefault

boolean · required

Whether this deployment is the default for the hostname.

Example: true

stage

string · enum · required

The stage exposed by this custom domain mapping.

Enum values:

api

dev-portal

Example: api

cname

string | null · required

The CNAME target for this deployment.

Example: todo-list-api-main-59eec11.zuplo.app

Zuplo.CustomDomains.CustomDomainEnvironmentType

string · enum

Enum values:

PRODUCTION

PREVIEW

WORKING_COPY

The environment type targeted by a custom domain deployment.

Zuplo.CustomDomains.CustomDomainMutationResult

The result of creating or updating a custom domain.

deploymentName

string | null · required

The deployment associated with the hostname.

Example: todo-list-api-main-59eec11

hostname

string · required

The hostname that was created or updated.

Example: api.example.com

stage

string · enum · required

The stage exposed by the hostname.

Enum values:

api

dev-portal

Example: api

ownershipVerification

object | null · required

The DNS record required to verify domain ownership, if any.

Example: {"name":"_zuplo.api.example.com","type":"TXT","value":"zuplo-verification-token"}

cname

string | null · required

The CNAME target for the custom domain, if any.

Example: todo-list-api-main-59eec11.zuplo.app

Zuplo.CustomDomains.CustomDomainProvider

string · enum

Enum values:

cloudflare

amazon

custom

alias

The provider backing a custom domain.

Zuplo.CustomDomains.CustomDomainStage

string · enum

Enum values:

api

dev-portal

The stage exposed by a custom domain.

Zuplo.CustomDomains.CustomDomainUpdateBody

Request body for updating a custom domain.

hostname

string · required

The hostname to update.

Example: api.example.com

deploymentName

string

The deployment to associate with the hostname.

Example: todo-list-api-main-59eec11

isDefault

boolean

Whether this domain should be the default domain for the deployment.

Example: true

Zuplo.CustomDomains.CustomDomainsList

Response containing a paginated list of custom domains.

Zuplo.CustomDomains.CustomDomain[] · required

The custom domains returned for the account.

offset

integer · uint32 · required

The number of records skipped.

Example: 0

limit

integer · uint32 · required

The maximum number of records returned.

Example: 100

Zuplo.CustomDomains.OwnershipVerification

DNS record details used to verify domain ownership.

name

string · required

The DNS record name to create.

Example: _zuplo.api.example.com

type

string · required

The DNS record type to create.

Example: TXT

value

string · required

The DNS record value to create.

Example: zuplo-verification-token

Zuplo.DeploymentStatus.DeploymentStatus

Status of a Zuplo project deployment, including the status, build results, and a URL to view more details.

status

string · enum · required

Enum values:

SUCCESS

ERROR

IN_PROGRESS

Example: SUCCESS

url

string · required

object · required

Zuplo.Deployments.Deployment

A single deployment of a Zup.

name

string · required

The name of the deployment. You can find this in the Zuplo Portal under Settings > Environments.

Example: lime-fox-main-bbe7540

url

string · required

label

string · required

urlParameter

string · required

createdOn

string · required

updatedOn

string · required

loggingId

string · required

accountName

string · required

projectName

string · required

state

string · required

message

string · enum · required

Enum values:

Example:

branchName

string · required

environmentType

string · required

Zuplo.Deployments.DeploymentsList

Zuplo.Deployments.Deployment[] · required

Zuplo.Deploys.DeploymentResponse

status

string · required

Zuplo.Deploys.SourceCreateBody

accountName

string · required

The name of the account

Example: my-account

projectName

string · required

The name of the project

Example: my-project

branchName

string · required

The name of the branch for deployment

Example: main

Zuplo.Deploys.SourceUrlCreateBody

accountName

string · required

The name of the account

Example: my-account

projectName

string · required

The name of the project

Example: my-project

branchName

string · required

The name of the branch for deployment

Example: main

repositoryUrl

string

The git repository url of the source code

Example: https://github.com/my-account/my-project

branch

string

The git branch

Example: main

sha

string

The git sha of the commit

Example: 9fb5c38a83013be1625c9b5cb2d1bdf458ff827e

Zuplo.Environments.Environment

The environment representing a Zup. This is mainly used in self-hosting deployments.

name

string · required

The name of the environment.

Example: lime-fox-main-bbe7540

createdOn

string · required

accountName

string · required

projectName

string · required

branchName

string · required

environmentType

string · enum · required

Enum values:

production

preview

development

Example: production

Zuplo.Environments.EnvironmentCreateBody

accountName

string · required

The name of the account

Example: my-account

projectName

string · required

The name of the project

Example: my-project

environmentType

string · enum · required

The name of the branch for deployment

Enum values:

production

preview

Example: preview

branchName

string · required

The name of the branch for deployment

Example: main

Zuplo.Environments.EnvironmentsList

Zuplo.Environments.Environment[] · required

Zuplo.HttpProblemDetails.BadRequestProblemResponse

type

string · enum · required

Enum values:

https://httpproblems.com/http-status/400

title

string · enum · required

Enum values:

Bad Request

detail

string

instance

string

Zuplo.HttpProblemDetails.InternalServerErrorProblemResponse

type

string · enum · required

Enum values:

https://httpproblems.com/http-status/500

title

string · enum · required

Enum values:

Internal Server Error

detail

string

instance

string

Zuplo.HttpProblemDetails.NotFoundProblemResponse

type

string · enum · required

Enum values:

https://httpproblems.com/http-status/404

title

string · enum · required

Enum values:

Not Found

detail

string

instance

string

Zuplo.HttpProblemDetails.UnauthorizedProblemResponse

type

string · enum · required

Enum values:

https://httpproblems.com/http-status/401

title

string · enum · required

Enum values:

Unauthorized

detail

string

instance

string

Zuplo.ManagedDedicated.Fleet

Fleet information

id

string · required

Fleet ID

name

string · required

Fleet name

vendor

string · enum · required

Fleet vendor

Enum values:

akamai

amazon

google

microsoft

controlPlaneUrl

string · required

Control plane URL

isAccountDefault

boolean · required

Whether this is the default fleet for the account

createdOn

string · date-time · required

Creation timestamp

updatedOn

string · date-time · required

Last update timestamp

Zuplo.ManagedDedicated.FleetConfigurationRequest

Fleet configuration request

No data returned

Zuplo.ManagedDedicated.FleetConfigurationResponse

Fleet configuration response

No data returned

Zuplo.ManagedDedicated.FleetListResponse

Fleet list response

Zuplo.ManagedDedicated.Fleet[] · required

List of fleets

Zuplo.ManagedDedicated.FleetVendor

string · enum

Enum values:

akamai

amazon

google

microsoft

Fleet vendor

Zuplo.Metering.Bucket

createdOn

string · date-time · readOnly · required

When the item was created.

Example: 2023-04-18T05:54:34.408Z

updatedOn

string · date-time · readOnly · required

When the item was last updated.

Example: 2023-04-20T05:54:34.408Z

id

string · readOnly · required

accountName

string · readOnly · required

Zuplo.Metering.Buckets

Zuplo.Metering.Bucket[] · required

limit

integer · uint32

offset

integer · uint32

total

integer · uint32

Zuplo.Metering.Plan

createdOn

string · date-time · readOnly · required

When the item was created.

Example: 2023-04-18T05:54:34.408Z

updatedOn

string · date-time · readOnly · required

When the item was last updated.

Example: 2023-04-20T05:54:34.408Z

id

string · readOnly · required

hasSubscriptions

boolean · readOnly · required

label

string · required

planExternalId

string · required

object · required

trialDays

integer

trialEndStatus

string · enum

Enum values:

paused

canceled

Example: paused

isTrialCollectPayment

boolean

Zuplo.Metering.PlanCreateBody

label

string · required

planExternalId

string · required

object · required

trialDays

integer

trialEndStatus

string · enum

Enum values:

paused

canceled

Example: paused

isTrialCollectPayment

boolean

Zuplo.Metering.PlanUpdateBody

label

string

planExternalId

string

object

trialDays

integer

trialEndStatus

string · enum

Enum values:

paused

canceled

Example: paused

isTrialCollectPayment

boolean

Zuplo.Metering.Plans

Zuplo.Metering.Plan[] · required

limit

integer · uint32

offset

integer · uint32

total

integer · uint32

Zuplo.Metering.Quota

integer

Zuplo.Metering.Subscription

createdOn

string · date-time · readOnly · required

When the item was created.

Example: 2023-04-18T05:54:34.408Z

updatedOn

string · date-time · readOnly · required

When the item was last updated.

Example: 2023-04-20T05:54:34.408Z

id

string · readOnly · required

planIds

string[] · required

planExternalIds

string[] · required

status

string · enum · required

Enum values:

active

inactive

incomplete

incomplete-expired

trialing

past-due

canceled

unpaid

type

string · enum · required

Enum values:

periodic

renewalStrategy

string · enum · required

Enum values:

monthly

yearly

region

string · enum · required

Enum values:

us-central1

us-east1

europe-west4

customerKey

string · required

subscriptionExternalId

string · required

customerExternalId

string · required

quotaResetAnchor

string · date-time

object

trialEndStatus

string

trialEndDate

string · date-time

trialStartDate

string · date-time

nextBillingCycle

string · date-time

productKey

string

Zuplo.Metering.SubscriptionCreateBody

planIds

string[] · required

planExternalIds

string[] · required

status

string · enum · required

Enum values:

active

inactive

incomplete

incomplete-expired

trialing

past-due

canceled

unpaid

type

string · enum · required

Enum values:

periodic

renewalStrategy

string · enum · required

Enum values:

monthly

yearly

region

string · enum · required

Enum values:

us-central1

us-east1

europe-west4

customerKey

string · required

subscriptionExternalId

string · required

customerExternalId

string · required

quotaResetAnchor

string · date-time

object

trialEndStatus

string

trialEndDate

string · date-time

trialStartDate

string · date-time

nextBillingCycle

string · date-time

productKey

string

Zuplo.Metering.SubscriptionUpdateBody

planExternalIds

string[]

status

string · enum

Enum values:

active

inactive

incomplete

incomplete-expired

trialing

past-due

canceled

unpaid

prorate

number

object

trialEndDate

string · date-time

Zuplo.Metering.Subscriptions

Zuplo.Metering.Subscription[] · required

limit

integer · uint32

offset

integer · uint32

total

integer · uint32

Zuplo.MeteringV3.CreatePaymentCheckoutSessionRequestBody

orgId

string · required

The customer subject key

billingEmail

string · required

The billing email address

planId

string · required

The plan ID

successUrl

string · required

The URL to which the payment provider should send the customer when payment or setup is complete.

cancelUrl

string · required

If set, the payment provider displays a back button and the customer is directed to this URL if they decide to cancel payment.

Zuplo.MeteringV3.CreatePaymentCheckoutSessionResponseBody

url

string · required

The URL to redirect the customer to. Points to Stripe checkout for new customers, or directly to the success URL for customers with existing Stripe billing.

Zuplo.MeteringV3.CreateSubscriptionRequestBody

customerSub

string · required

The customer subject key (OpenMeter customer key)

customerEmail

string · required

The customer email address

planId

string · required

The plan ID

Zuplo.MeteringV3.CustomInvoicingTaxConfig

code

string · required

Zuplo.MeteringV3.DiscountPercentage

percentage

string · required

Zuplo.MeteringV3.DiscountUsage

quantity

string · required

Zuplo.MeteringV3.Discounts

Zuplo.MeteringV3.DiscountPercentage

Zuplo.MeteringV3.DiscountUsage

Zuplo.MeteringV3.Entitlement

Zuplo.MeteringV3.Feature

createdAt

string · date-time · required

id

string · required

key

string · required

name

string · required

updatedAt

string · date-time · required

object

archivedAt

string · date-time

deletedAt

string · date-time

object

meterSlug

string

Zuplo.MeteringV3.Period

from

string · date-time · required

to

string · date-time · required

Zuplo.MeteringV3.PlanReference

id

string · required

key

string · required

version

integer · int64 · required

Zuplo.MeteringV3.ProRatingConfig

enabled

boolean · required

mode

string · required

Zuplo.MeteringV3.RateCardUsageBasedPrice

Zuplo.MeteringV3.StripeTaxConfig

code

string · required

Zuplo.MeteringV3.SubscriptionAlignment

billablesMustAlign

boolean

Zuplo.MeteringV3.Period

Zuplo.MeteringV3.SubscriptionApiKey

id

string · required

The ID of the API key

key

string · required

The API key

createdOn

string · date-time · required

The creation date of the API key

updatedOn

string · date-time · required

The last update date of the API key

description

string

The description of the API key

expiresOn

string · date-time

The expiration date of the API key

Zuplo.MeteringV3.SubscriptionConsumerResponse

id

string · required

The consumer id

name

string · required

The consumer name

createdOn

string · date-time · required

Date in which the record was created

updatedOn

string · date-time · required

Date in which the record was updated

object · required

The consumer tags

object · required

The consumer metadata

array | null · required

description

string

The consumer description

Zuplo.MeteringV3.SubscriptionItem

activeFrom

string · date-time · required

billingCadence

string | null · required

createdAt

string · date-time · required

id

string · required

key

string · required

object · required

name

string · required

price

Zuplo.MeteringV3.RateCardUsageBasedPrice · required

updatedAt

string · date-time · required

activeTo

string · date-time

deletedAt

string · date-time

description

string

Zuplo.MeteringV3.Discounts

featureKey

string

Zuplo.MeteringV3.SubscriptionItemIncluded

Zuplo.MeteringV3.TaxConfig

Zuplo.MeteringV3.SubscriptionItemIncluded

Zuplo.MeteringV3.Feature · required

entitlement

Zuplo.MeteringV3.Entitlement

Zuplo.MeteringV3.SubscriptionManager

id

string · required

Manager record id

email

string · required

Manager email address

sub

string · required

Manager sub

createdOn

string · date-time · required

Date in which the record was created

Zuplo.MeteringV3.SubscriptionPhaseExpanded

activeFrom

string · date-time · required

createdAt

string · date-time · required

id

string · required

key

string · required

object · required

name

string · required

updatedAt

string · date-time · required

object · required

array | null · required

activeTo

string · date-time

deletedAt

string · date-time

description

string

Zuplo.MeteringV3.Discounts

Zuplo.MeteringV3.SubscriptionWithAPIKeysResponse

activeFrom

string · date-time · required

billingAnchor

string · date-time · required

billingCadence

string · required

Zuplo.MeteringV3.SubscriptionConsumerResponse · required

createdAt

string · date-time · required

currency

string · required

customerId

string · required

id

string · required

object · required

name

string · required

array | null · required

status

string · required

updatedAt

string · date-time · required

activeTo

string · date-time

Zuplo.MeteringV3.SubscriptionAlignment

object

deletedAt

string · date-time

description

string

Zuplo.MeteringV3.PlanReference

Zuplo.MeteringV3.ProRatingConfig

Zuplo.MeteringV3.TaxConfig

behavior

string

Zuplo.MeteringV3.CustomInvoicingTaxConfig

Zuplo.MeteringV3.StripeTaxConfig

Zuplo.MtlsCertificates.CertificateInfo

subject

string · required

Certificate subject

Example: CN=example.com

issuer

string · required

Certificate issuer

Example: CN=Example CA

validFrom

string · required

Certificate valid from date

Example: 2024-01-01T00:00:00Z

validTo

string · required

Certificate valid to date

Example: 2025-01-01T00:00:00Z

serialNumber

string · required

Certificate serial number

Example: 12345

Zuplo.MtlsCertificates.Environments

development

boolean · required

Whether the certificate is enabled for the development environment

preview

boolean · required

Whether the certificate is enabled for the preview environment

production

boolean · required

Whether the certificate is enabled for the production environment

Zuplo.MtlsCertificates.MtlsCertificate

id

string · readOnly · required

The unique identifier for the certificate

Example: cert_abc123

name

string · minLength: 1 · maxLength: 120 · required

The name of the certificate. Must be alphanumeric with underscores.

Example: my_client_cert

object · required

Certificate information

object · required

Environments where the certificate is enabled

createdOn

string · date-time · readOnly · required

When the item was created.

Example: 2023-04-18T05:54:34.408Z

updatedOn

string · date-time · readOnly · required

When the item was last updated.

Example: 2023-04-20T05:54:34.408Z

Zuplo.MtlsCertificates.MtlsCertificateCreateBody

name

string · minLength: 1 · maxLength: 120 · required

The name of the certificate. Must be alphanumeric with underscores.

Example: my_client_cert

certificate

string · minLength: 1 · required

The PEM-encoded certificate

key

string · minLength: 1 · required

The PEM-encoded private key

environments

string[] · minItems: 1 · required

List of environments where the certificate should be enabled

Enum values:

development

preview

production

Zuplo.MtlsCertificates.MtlsCertificateListResponse

Zuplo.MtlsCertificates.MtlsCertificate[] · required

List of mTLS certificates

offset

integer · int32 · required

Offset for pagination

limit

integer · int32 · required

Limit for pagination

Zuplo.MtlsCertificates.MtlsCertificateUpdateBody

environments

string[] · minItems: 1

List of environments where the certificate should be enabled

Enum values:

development

preview

production

Zuplo.Projects.Project

A single project.

name

string · required

The name of the project

Example: lime-fox

accountName

string · required

The name of the account this project belongs to

Example: lime-fox

Zuplo.Projects.ProjectCreateBody

The body of the project creation request.

name

string · required

The name of the project

Example: lime-fox

Zuplo.Projects.ProjectsList

Zuplo.Projects.Project[] · required

Zuplo.RuntimeLogs.RequestLogDetail

Detailed information about a single request, returned in the detail response.

requestId

string · required

Unique identifier for the request.

timestamp

string · date-time · required

ISO 8601 timestamp when the request was received.

httpMethod

string · required

HTTP method of the request.

httpStatus

integer · int32 · required

HTTP status code of the response.

routePath

string · required

Matched route path on the deployment.

durationMs

integer · int32 · required

End-to-end duration of the request in milliseconds.

colo

string · required

Edge colo (point of presence) that served the request.

country

string · required

ISO 3166-1 alpha-2 country code of the client.

city

string · required

City the request was made from, when derivable from the client IP.

continent

string · required

Continent code (e.g. NA, EU) of the client.

clientIp

string · required

IP address of the client.

asOrganization

string · required

AS organization (ISP name) for the client IP.

userSub

string · required

Authenticated user/consumer subject for the request, or (anonymous) if unauthenticated.

systemRouteName

string · required

Internal system route name (Zuplo-defined), if applicable.

zuploUserAgent

string · required

User-Agent header captured by the Zuplo runtime.

Zuplo.RuntimeLogs.RequestLogDetailResponse

Response containing the request detail and all log entries for a single request.

object · required

The request summary and contextual fields.

Zuplo.RuntimeLogs.RequestLogEntry[] · required

All log entries emitted during the request, ordered by emit time.

Zuplo.RuntimeLogs.RequestLogEntry

A single log entry emitted during a request.

logId

string · required

Unique identifier for the log entry.

timestamp

string · date-time · required

ISO 8601 timestamp when the log entry was emitted.

severity

string · required

Severity of the log entry (debug, info, warn, error).

messages

string[] · required

Ordered array of message strings for the entry.

object · required

Structured attributes attached to the entry.

source

string · required

Source that emitted the log (e.g. policy or handler name).

requestId

string · required

Request ID this log entry belongs to.

atomicCounter

integer · int32 · required

Monotonically increasing counter used to preserve emit order within a single request.

Zuplo.RuntimeLogs.RequestLogSummary

Summary information for a single request, returned in the list response. Mirrors the per-row shape returned by tenant-api's request-list query.

requestId

string · required

Unique identifier for the request (correlation ID stamped by the gateway).

Example: c21fefe0-8938-4f17-8fb8-c844d68042f3

timestamp

string · date-time · required

ISO 8601 timestamp when the request was received.

Example: 2026-05-14T12:00:00.000Z

httpMethod

string · required

HTTP method of the request.

Example: GET

httpStatus

integer · int32 · required

HTTP status code of the response.

Example: 200

routePath

string · required

Matched route path on the deployment.

Example: /v1/items/:id

durationMs

integer · int32 · required

End-to-end duration of the request in milliseconds.

Example: 42

colo

string · required

Edge colo (point of presence) that served the request.

Example: SFO

country

string · required

ISO 3166-1 alpha-2 country code of the client.

Example: US

maxSeverity

string | null · required

Maximum log severity recorded during this request, or null if no logs were emitted.

Example: info

logCount

integer · int32 · required

Total number of log entries recorded for this request.

Example: 3

Zuplo.RuntimeLogs.RequestLogsListResponse

Response listing request-log summaries for a deployment.

Zuplo.RuntimeLogs.RequestLogSummary[] · required

Array of request-log summaries, ordered most recent first.

object · required

Pagination state for the result set.

Zuplo.RuntimeLogs.RequestLogsPagination

Pagination information for a request-log list page.

cursor

string | null · required

Opaque cursor to pass as cursor on the next request to fetch the next page. Treat as a string the client does not introspect — the encoding is owned by tenant-api and can change. null when there is no further page.

hasMore

boolean · required

Whether more results are available beyond this page.

Zuplo.Sources.Source

uploadUrl

string · required

Zuplo.Tunnels.Tunnel

Tunnels allow you to expose services running on bare metal, on-premises, or other non-cloud providers to the Zuplo platform. [Further reading](https://zuplo.com/docs/articles/secure-tunnel).

tunnelId

string · readOnly · required

name

string · pattern: ^[a-zA-Z0-9-]{3,24}$ · required

A friendly name for the tunnel.

Example: api-service-tunnel

token

string · readOnly · required

Set your TUNNEL_TOKEN to this value to connect to the tunnel.

Example: eyJhIjoiODJh[..]m89In0=

Zuplo.Tunnels.TunnelList

Zuplo.Tunnels.TunnelListItem[] · required

limit

integer · uint32

offset

integer · uint32

total

integer · uint32

Zuplo.Tunnels.TunnelListItem

id

string · readOnly · required

name

string · pattern: ^[a-zA-Z0-9-]{3,24}$ · required

A friendly name for the tunnel.

Example: api-service-tunnel

Zuplo.Tunnels.TunnelTeardownOperation

id

string · readOnly · required

status

string · enum · required

Enum values:

in-progress

success

error

Example: success

message

string

details

string

Zuplo.Tunnels.TunneledServiceConfiguration

Tunnel service configuration.

name

string · pattern: ^[a-zA-Z0-9-]{3,24}$ · required

A friendly name for the service. This name needs to be unique across all your tunneled services. Changing this will invalidate existing services with the name.

Example: authservice

endpoint

string · required

The URL of the service that the tunnel will forward to, e.g, http://localhost:3000

Example: https://localhost:3000

object[] · required

A list of projects that should have access to this tunneled service under the service://name URL scheme.

Zuplo.Tunnels.TunneledServicesConfiguration

version

integer · uint8 · required

The version of this configuration format.

Example: 1

Zuplo.Tunnels.TunneledServiceConfiguration[] · required

A list of services that the tunnel will connect to.

Zuplo.Tunnels.TunneledServicesProvisioningOperation

id

string · readOnly · required

status

string · enum · required

Enum values:

in-progress

success

error

Example: success

message

string

details

string

Zuplo.Variables.Variable

branch

string · readOnly · required

createdOn

string · date-time · readOnly · required

When the item was created.

Example: 2023-04-18T05:54:34.408Z

updatedOn

string · date-time · readOnly · required

When the item was last updated.

Example: 2023-04-20T05:54:34.408Z

name

string · required

The name of the variable. Must be named in SCREAMING_SNAKE_CASE.

Example: APP_ENVIRONMENT_KEY

isSecret

boolean · required

Whether the variable is a secret.

Example: true

value

string · required

The value of the variable.

Zuplo.Variables.VariableCreateBody

name

string · required

The name of the variable. Must be named in SCREAMING_SNAKE_CASE.

Example: APP_ENVIRONMENT_KEY

isSecret

boolean · required

Whether the variable is a secret.

Example: true

value

string · required

The value of the variable.

Zuplo.Variables.VariableUpdateBody

value

string

The value of the variable.

Zuplo.WhoAmI.WhoAmI

sub

string · required

account

string

email

string

Addon

Add-on allows extending subscriptions with compatible plans with additional ratecards.

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 add-on. Incremented when the add-on is updated.

Default: 1

instanceType

string · enum · required

The instanceType of the add-ons. Can be "single" or "multiple".

Enum values:

single

multiple

currency

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

The currency code of the add-on.

Example: USD

Default: USD

status

string · enum · readOnly · required

The status of the add-on. Computed based on the effective start and end dates:

draft = no effectiveFrom
active = effectiveFrom <= now < effectiveTo
archived = effectiveTo <= now

Enum values:

draft

active

archived

RateCard[] · required

The rate cards of the add-on.

array | null · readOnly · required

List of validation errors.

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 · readOnly

Set of key-value pairs managed by the system. Cannot be modified by user.

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

effectiveFrom

string · date-time · readOnly

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

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

effectiveTo

string · date-time · readOnly

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

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

AddonCreate

Resource create operation model.

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.

instanceType

string · enum · required

The instanceType of the add-ons. Can be "single" or "multiple".

Enum values:

single

multiple

currency

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

The currency code of the add-on.

Example: USD

Default: USD

RateCard[] · required

The rate cards of the add-on.

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

AddonInstanceType

string · enum

Enum values:

single

multiple

The instanceType of the add-on. Single instance add-ons can be added to subscription only once while add-ons with multiple type can be added more then once.

AddonOrderBy

string · enum

Enum values:

id

key

version

created_at

updated_at

Order by options for add-ons.

AddonPaginatedResponse

Paginated response

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

Addon[] · required

The items in the current page.

AddonReplaceUpdate

Resource update operation model.

name

string · minLength: 1 · maxLength: 256 · required

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

instanceType

string · enum · required

The instanceType of the add-ons. Can be "single" or "multiple".

Enum values:

single

multiple

RateCard[] · required

The rate cards of the add-on.

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

AddonStatus

string · enum

Enum values:

draft

active

archived

The status of the add-on defined by the effectiveFrom and effectiveTo properties.

Address

country

string · minLength: 2 · maxLength: 2 · pattern: ^[A-Z]{2}$

Country code in ISO 3166-1 alpha-2 format.

Example: US

postalCode

string

Postal code.

state

string

State or province.

city

string

City.

line1

string

First line of the address.

line2

string

Second line of the address.

phoneNumber

string

Phone number.

Alignment

Alignment configuration for a plan or subscription.

Annotations

Set of key-value pairs managed by the system. Cannot be modified by user.

No data returned

App

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · type="stripe" · requires: id, name, createdAt +6 more
	type = object · type="sandbox" · requires: id, name, createdAt +3 more
	type = object · type="custom_invoicing" · requires: id, name, createdAt +5 more

Properties for Variant 1:

A installed Stripe app object.

StripeApp

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

object · readOnly · required

The marketplace listing that this installed app is based on.

Example: {"type":"stripe","name":"Stripe","description":"Stripe interation allows you to collect payments with Stripe.","capabilities":[{"type":"calculateTax","key":"stripe_calculate_tax","name":"Calculate Tax","description":"Stripe Tax calculates tax portion of the invoices."},{"type":"invoiceCustomers","key":"stripe_invoice_customers","name":"Invoice Customers","description":"Stripe invoices customers with due amount."},{"type":"collectPayments","key":"stripe_collect_payments","name":"Collect Payments","description":"Stripe payments collects outstanding revenue with Stripe customer's default payment method."}],"installMethods":["with_oauth2","with_api_key"]}

status

string · enum · readOnly · required

Status of the app connection.

Enum values:

ready

unauthorized

type

string · enum · required

The app's type is Stripe.

Enum values:

stripe

stripeAccountId

string · readOnly · required

The Stripe account ID.

livemode

boolean · readOnly · required

Livemode, true if the app is in production mode.

maskedAPIKey

string · readOnly · required

The masked API key. Only shows the first 8 and last 3 characters.

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

AppBase

Abstract base model for installed apps. Represent an app installed to the organization. This is an actual instance, with its own configuration and credentials.

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

object · readOnly · required

The marketplace listing that this installed app is based on.

Example: {"type":"stripe","name":"Stripe","description":"Stripe interation allows you to collect payments with Stripe.","capabilities":[{"type":"calculateTax","key":"stripe_calculate_tax","name":"Calculate Tax","description":"Stripe Tax calculates tax portion of the invoices."},{"type":"invoiceCustomers","key":"stripe_invoice_customers","name":"Invoice Customers","description":"Stripe invoices customers with due amount."},{"type":"collectPayments","key":"stripe_collect_payments","name":"Collect Payments","description":"Stripe payments collects outstanding revenue with Stripe customer's default payment method."}],"installMethods":["with_oauth2","with_api_key"]}

status

string · enum · readOnly · required

Status of the app connection.

Enum values:

ready

unauthorized

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

AppCapability

App capability. Capabilities only exist in config so they don't extend the Resource model.

type

string · enum · required

The capability type.

Enum values:

reportUsage

reportEvents

calculateTax

invoiceCustomers

collectPayments

key

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

Key

name

string · required

The capability name.

description

string · required

The capability description.

AppCapabilityType

string · enum

Enum values:

reportUsage

reportEvents

calculateTax

invoiceCustomers

collectPayments

App capability type.

AppPaginatedResponse

Paginated response

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

App[] · required

The items in the current page.

AppReadOrCreateOrUpdateOrDeleteOrQuery

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · type="stripe" · requires: id, name, createdAt +6 more
	type = object · type="sandbox" · requires: id, name, createdAt +3 more
	type = object · type="custom_invoicing" · requires: id, name, createdAt +5 more

Properties for Variant 1:

A installed Stripe app object.

StripeAppReadOrCreateOrUpdateOrDeleteOrQuery

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

object · readOnly · required

The marketplace listing that this installed app is based on.

Example: {"type":"stripe","name":"Stripe","description":"Stripe interation allows you to collect payments with Stripe.","capabilities":[{"type":"calculateTax","key":"stripe_calculate_tax","name":"Calculate Tax","description":"Stripe Tax calculates tax portion of the invoices."},{"type":"invoiceCustomers","key":"stripe_invoice_customers","name":"Invoice Customers","description":"Stripe invoices customers with due amount."},{"type":"collectPayments","key":"stripe_collect_payments","name":"Collect Payments","description":"Stripe payments collects outstanding revenue with Stripe customer's default payment method."}],"installMethods":["with_oauth2","with_api_key"]}

status

string · enum · readOnly · required

Status of the app connection.

Enum values:

ready

unauthorized

type

string · enum · required

The app's type is Stripe.

Enum values:

stripe

stripeAccountId

string · readOnly · required

The Stripe account ID.

livemode

boolean · readOnly · required

Livemode, true if the app is in production mode.

maskedAPIKey

string · readOnly · required

The masked API key. Only shows the first 8 and last 3 characters.

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

secretAPIKey

string · password

The Stripe API key.

AppReference

App reference Can be used as a short reference to an app if the full app object is not needed.

id

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The ID of the app.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

AppReplaceUpdate

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · type="stripe" · requires: name
	type = object · type="sandbox" · requires: name
	type = object · type="custom_invoicing" · requires: name, enableDraftSyncHook, enableIssuingSyncHook

Properties for Variant 1:

Resource update operation model.

StripeAppReplaceUpdate

name

string · minLength: 1 · maxLength: 256 · required

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

type

string · enum · required

The app's type is Stripe.

Enum values:

stripe

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

secretAPIKey

string · password

The Stripe API key.

AppStatus

string · enum

Enum values:

ready

unauthorized

App installed status.

AppType

string · enum

Enum values:

stripe

sandbox

custom_invoicing

Type of the app.

BadRequestProblemResponse

The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

type

string · uri · required

Type contains a URI that identifies the problem type.

Example: about:blank

Default: about:blank

title

string · required

A a short, human-readable summary of the problem type.

Example: Bad Request

detail

string · required

A human-readable explanation specific to this occurrence of the problem.

Example: The request body must be a JSON object.

instance

string · uri · required

A URI reference that identifies the specific occurrence of the problem.

Example: urn:request:local/JMOlctsKV8-000001

status

integer · int16 · min: 400 · max: 599

The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 400

object

Additional properties specific to the problem type may be present.

Example: {"validationErrors":[{"code":"validation_error","message":"Validation error"}],"otherAttribute":"otherValue"}

No data returned

BalanceHistoryWindow

The balance history window.

Period · required

A period with a start and end time.

usage

number · double · readOnly · required

The total usage of the feature in the period.

Example: 100

balanceAtStart

number · double · readOnly · required

The entitlement balance at the start of the period.

Example: 100

BillingCollectionAlignment

string · enum

Enum values:

subscription

anchored

BillingCollectionAlignment specifies when the pending line items should be collected into an invoice.

BillingCustomerProfile

Customer specific merged profile. This profile is calculated from the customer override and the billing profile it references or the default. Thus this does not have any kind of resource fields, only the calculated values.

object · readOnly · required

The name and contact information for the supplier this billing profile represents

object · readOnly · required

The billing workflow settings for this profile

readOnly · required

The applications used by this billing profile.

Expand settings govern if this includes the whole app object or just the ID references.

BillingDiscountMetadata

Billing specific fields for product catalog discounts.

correlationId

string · pattern: ^[0-7][0-9A-HJKMNP-T…

Correlation ID for the discount.

This is used to link discounts across different invoices (progressive billing use case).

If not provided, the invoicing engine will auto-generate one. When editing an invoice line, please make sure to keep the same correlation ID of the discount or in progressive billing setups the discount amounts might be incorrect.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

BillingDiscountPercentage

A percentage discount.

percentage

number · double · min: 0 · max: 100 · required

The percentage of the discount.

Example: 50

correlationId

string · pattern: ^[0-7][0-9A-HJKMNP-T…

Correlation ID for the discount.

This is used to link discounts across different invoices (progressive billing use case).

If not provided, the invoicing engine will auto-generate one. When editing an invoice line, please make sure to keep the same correlation ID of the discount or in progressive billing setups the discount amounts might be incorrect.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

BillingDiscountReason

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · type="maximum_spend"
	type = object · type="ratecard_percentage" · requires: percentage
	type = object · type="ratecard_usage" · requires: quantity
	type = object · type="proration_credit" · requires: previousSubscriptionId, maxPercentage

Properties for Variant 1:

The reason for the discount is a maximum spend.

DiscountReasonMaximumSpend

type

string · enum · required

Enum values:

maximum_spend

BillingDiscountUsage

A usage discount.

quantity

string · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The quantity of the usage discount.

Must be positive.

correlationId

string · pattern: ^[0-7][0-9A-HJKMNP-T…

Correlation ID for the discount.

This is used to link discounts across different invoices (progressive billing use case).

If not provided, the invoicing engine will auto-generate one. When editing an invoice line, please make sure to keep the same correlation ID of the discount or in progressive billing setups the discount amounts might be incorrect.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

BillingDiscounts

A discount by type.

object

The percentage discount.

object

The usage discount.

BillingInvoiceCustomerExtendedDetails

BillingInvoiceCustomerExtendedDetails is a collection of fields that are used to extend the billing party details for invoices. These fields contain the Zuplo Metering specific details for the customer, that are not strictly required for the invoice itself.

object · required

Mapping to attribute metered usage to the customer

id

string · readOnly

Unique identifier for the party (if available)

key

string · minLength: 1 · maxLength: 256

An optional unique key of the party (if available)

name

string

Legal name or representation of the organization.

object

The entity's legal ID code used for tax purposes. They may have other numbers, but we're only interested in those valid for tax purposes.

Address[] · maxItems: 1

Regular post addresses for where information should be sent if needed.

BillingParty

Party represents a person or business entity.

id

string · readOnly

Unique identifier for the party (if available)

key

string · minLength: 1 · maxLength: 256

An optional unique key of the party (if available)

name

string

Legal name or representation of the organization.

object

The entity's legal ID code used for tax purposes. They may have other numbers, but we're only interested in those valid for tax purposes.

Address[] · maxItems: 1

Regular post addresses for where information should be sent if needed.

BillingPartyReplaceUpdate

Resource update operation model.

key

string · minLength: 1 · maxLength: 256

An optional unique key of the party (if available)

name

string

Legal name or representation of the organization.

object

The entity's legal ID code used for tax purposes. They may have other numbers, but we're only interested in those valid for tax purposes.

Address[] · maxItems: 1

Regular post addresses for where information should be sent if needed.

BillingPartyTaxIdentity

Identity stores the details required to identify an entity for tax purposes in a specific country.

code

string · minLength: 1 · maxLength: 32

Normalized tax code shown on the original identity document.

BillingProfile

BillingProfile represents a billing profile

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

object · required

The name and contact information for the supplier this billing profile represents

object · readOnly · required

The billing workflow settings for this profile

readOnly · required

The applications used by this billing profile.

Expand settings govern if this includes the whole app object or just the ID references.

default

boolean · required

Is this the default profile?

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

BillingProfileAppReferences

BillingProfileAppReferences represents the references (id, type) to the apps used by a billing profile

object · readOnly · required

The tax app used for this workflow

object · readOnly · required

The invoicing app used for this workflow

object · readOnly · required

The payment app used for this workflow

BillingProfileApps

BillingProfileApps represents the applications used by a billing profile

object · readOnly · required

The tax app used for this workflow

object · readOnly · required

The invoicing app used for this workflow

object · readOnly · required

The payment app used for this workflow

BillingProfileAppsCreate

BillingProfileAppsCreate represents the input for creating a billing profile's apps

tax

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The tax app used for this workflow

Example: 01G65Z755AFWAKHE12NY0CQ9FH

invoicing

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The invoicing app used for this workflow

Example: 01G65Z755AFWAKHE12NY0CQ9FH

payment

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The payment app used for this workflow

Example: 01G65Z755AFWAKHE12NY0CQ9FH

BillingProfileAppsOrReference

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = object · requires: tax, invoicing, payment
	type = object · requires: tax, invoicing, payment

Properties for Variant 1:

BillingProfileApps represents the applications used by a billing profile

BillingProfileApps

object · readOnly · required

The tax app used for this workflow

object · readOnly · required

The invoicing app used for this workflow

object · readOnly · required

The payment app used for this workflow

BillingProfileCreate

BillingProfileCreate represents the input for creating a billing profile

name

string · minLength: 1 · maxLength: 256 · required

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

object · required

The name and contact information for the supplier this billing profile represents

default

boolean · required

Is this the default profile?

object · required

The billing workflow settings for this profile.

object · required

The apps used by this billing profile.

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

BillingProfileCustomerOverride

Customer override values.

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

customerId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The customer id this override is associated with.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

billingProfileId

string · pattern: ^[0-7][0-9A-HJKMNP-T…

The billing profile this override is associated with.

If empty the default profile is looked up dynamically.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

BillingProfileCustomerOverrideCreate

Payload for creating a new or updating an existing customer override.

billingProfileId

string · pattern: ^[0-7][0-9A-HJKMNP-T…

The billing profile this override is associated with.

If not provided, the default billing profile is chosen if available.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

BillingProfileCustomerOverrideExpand

string · enum

Enum values:

apps

customer

CustomerOverrideExpand specifies the parts of the profile to expand.

BillingProfileCustomerOverrideOrderBy

string · enum

Enum values:

customerId

customerName

customerKey

customerPrimaryEmail

customerCreatedAt

Order by options for customers.

BillingProfileCustomerOverrideWithDetails

Customer specific workflow overrides.

baseBillingProfileId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The billing profile the customerProfile is associated with at the time of query.

customerOverride contains the explicit mapping set in the customer override object. If that is empty, then the baseBillingProfileId is the default profile.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

object

The customer override values.

If empty the merged values are calculated based on the default profile.

object

Merged billing profile with the customer specific overrides.

object

The customer this override belongs to.

Example: {"id":"01G65Z755AFWAKHE12NY0CQ9FH","name":"ACME Inc.","usageAttribution":{"subjectKeys":["my_subject_key"]},"createdAt":"2024-01-01T01:01:01.001Z","updatedAt":"2024-01-01T01:01:01.001Z"}

BillingProfileCustomerOverrideWithDetailsPaginatedResponse

Paginated response

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

BillingProfileCustomerOverrideWithDetails[] · required

The items in the current page.

BillingProfileCustomerWorkflowOverride

Customer specific workflow overrides.

object · readOnly · required

The tax app used for this workflow

object · readOnly · required

The invoicing app used for this workflow

object · readOnly · required

The payment app used for this workflow

object

The collection settings for this workflow

object

The invoicing settings for this workflow

object

The payment settings for this workflow

object

The tax settings for this workflow

BillingProfileExpand

string · enum

Enum values:

apps

BillingProfileExpand details what profile fields to expand

BillingProfileOrderBy

string · enum

Enum values:

createdAt

updatedAt

default

name

BillingProfileOrderBy specifies the ordering options for profiles

BillingProfilePaginatedResponse

Paginated response

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

BillingProfile[] · required

The items in the current page.

BillingProfileReplaceUpdateWithWorkflow

BillingProfileReplaceUpdate represents the input for updating a billing profile The apps field cannot be updated directly, if an app change is desired a new profile should be created.

name

string · minLength: 1 · maxLength: 256 · required

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

object · required

The name and contact information for the supplier this billing profile represents

default

boolean · required

Is this the default profile?

object · required

The billing workflow settings for this profile.

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

BillingTaxIdentificationCode

string · minLength: 1 · maxLength: 32

TaxIdentificationCode is a normalized tax code shown on the original identity document.

BillingWorkflow

BillingWorkflow represents the settings for a billing workflow.

object

The collection settings for this workflow

object

The invoicing settings for this workflow

object

The payment settings for this workflow

object

The tax settings for this workflow

BillingWorkflowAppReferenceType

string · enum

Enum values:

app_id

app_type

App reference type specifies the type of reference inside an app reference

BillingWorkflowCollectionAlignment

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · type="subscription"
	type = object · type="anchored" · requires: recurringPeriod

Properties for Variant 1:

BillingWorkflowCollectionAlignmentSubscription specifies the alignment for collecting the pending line items into an invoice.

BillingWorkflowCollectionAlignmentSubscription

type

string · enum · required

The type of alignment.

Enum values:

subscription

BillingWorkflowCollectionAlignmentAnchored

BillingWorkflowCollectionAlignmentAnchored specifies the alignment for collecting the pending line items into an invoice.

type

string · enum · required

The type of alignment.

Enum values:

anchored

object · required

The recurring period for the alignment.

BillingWorkflowCollectionAlignmentSubscription

BillingWorkflowCollectionAlignmentSubscription specifies the alignment for collecting the pending line items into an invoice.

type

string · enum · required

The type of alignment.

Enum values:

subscription

BillingWorkflowCollectionSettings

Workflow collection specifies how to collect the pending line items for an invoice

object

The alignment for collecting the pending line items into an invoice.

Default: {"type":"subscription"}

interval

string · ISO8601

This grace period can be used to delay the collection of the pending line items specified in alignment.

This is useful, in case of multiple subscriptions having slightly different billing periods.

Example: P1D

Default: PT1H

BillingWorkflowCreate

Resource create operation model.

object

The collection settings for this workflow

object

The invoicing settings for this workflow

object

The payment settings for this workflow

object

The tax settings for this workflow

BillingWorkflowInvoicingSettings

BillingWorkflowInvoicingSettings represents the invoice settings for a billing workflow

autoAdvance

boolean

Whether to automatically issue the invoice after the draftPeriod has passed.

Default: true

draftPeriod

string · ISO8601

The period for the invoice to be kept in draft status for manual reviews.

Example: P1D

Default: P0D

dueAfter

string · ISO8601

The period after which the invoice is due. With some payment solutions it's only applicable for manual collection method.

Example: P30D

Default: P30D

progressiveBilling

boolean

Should progressive billing be allowed for this workflow?

Default: false

object

Default tax configuration to apply to the invoices.

BillingWorkflowLineResolution

string · enum

Enum values:

day

period

BillingWorkflowLineResolution specifies how the line items should be resolved in the invoice

BillingWorkflowPaymentSettings

BillingWorkflowPaymentSettings represents the payment settings for a billing workflow

collectionMethod

string · enum

The payment method for the invoice.

Enum values:

charge_automatically

send_invoice

Default: charge_automatically

BillingWorkflowTaxSettings

BillingWorkflowTaxSettings represents the tax settings for a billing workflow

enabled

boolean

Enable automatic tax calculation when tax is supported by the app. For example, with Stripe Invoicing when enabled, tax is calculated via Stripe Tax.

Default: true

enforced

boolean

Enforce tax calculation when tax is supported by the app. When enabled, Zuplo Metering will not allow to create an invoice without tax calculation. Enforcement is different per apps, for example, Stripe app requires customer to have a tax location when starting a paid subscription.

Default: false

CalculateTaxRequest

CalculateTaxRequest is the input for calculating tax.

TaxCalculationItem[] · minItems: 1 · required

The line items to calculate tax for.

currency

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

Three-letter ISO currency code.

Example: USD

customerId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The customer ID to calculate tax for. The customer must have a linked Stripe customer with a valid billing address.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

CalculateTaxResponse

CalculateTaxResponse contains the tax calculation result for an order confirmation page.

currency

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

Three-letter ISO currency code.

Example: USD

subtotal

integer · required

The original amount before tax in the smallest currency unit.

taxAmount

integer · required

The total tax amount in the smallest currency unit.

total

integer · required

The total amount including tax in the smallest currency unit.

taxInclusive

boolean · required

Whether the tax is included in the subtotal amount.

TaxItem[] · required

Per-jurisdiction tax breakdown.

TaxCalculationItemResult[] · required

Per-item tax calculation results, in the same order as the request items.

CheckoutSessionCustomTextAfterSubmitParams

Stripe CheckoutSession.custom_text

object

Custom text that should be displayed after the payment confirmation button.

object

Custom text that should be displayed alongside shipping address collection.

object

Custom text that should be displayed alongside the payment confirmation button.

object

Custom text that should be displayed in place of the default terms of service agreement text.

CheckoutSessionUIMode

string · enum

Enum values:

embedded

hosted

Stripe CheckoutSession.ui_mode

ClientAppStartResponse

Response from the client app (Zuplo Metering backend) to start the OAuth2 flow.

url

string · required

The URL to start the OAuth2 authorization code grant flow.

CollectionMethod

string · enum

Enum values:

charge_automatically

send_invoice

CollectionMethod specifies how the invoice should be collected (automatic vs manual)

ConflictProblemResponse

The request could not be completed due to a conflict with the current state of the target resource.

type

string · uri · required

Type contains a URI that identifies the problem type.

Example: about:blank

Default: about:blank

title

string · required

A a short, human-readable summary of the problem type.

Example: Bad Request

detail

string · required

A human-readable explanation specific to this occurrence of the problem.

Example: The request body must be a JSON object.

instance

string · uri · required

A URI reference that identifies the specific occurrence of the problem.

Example: urn:request:local/JMOlctsKV8-000001

status

integer · int16 · min: 400 · max: 599

The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 400

object

Additional properties specific to the problem type may be present.

Example: {"validationErrors":[{"code":"validation_error","message":"Validation error"}],"otherAttribute":"otherValue"}

No data returned

CountryCode

string · minLength: 2 · maxLength: 2 · pattern: ^[A-Z]{2}$

ISO 3166-1 alpha-2 country code. Custom two-letter country codes are also supported for convenience.

Example: US

CreateCheckoutSessionTaxIdCollection

Create Stripe checkout session tax ID collection.

enabled

boolean · required

Enable tax ID collection during checkout. Defaults to false.

required

string · enum

Describes whether a tax ID is required during checkout. Defaults to never.

Enum values:

if_supported

never

CreateCheckoutSessionTaxIdCollectionRequired

string · enum

Enum values:

if_supported

never

Create Stripe checkout session tax ID collection required.

CreateStripeCheckoutSessionBillingAddressCollection

string · enum

Enum values:

auto

required

Specify whether Checkout should collect the customer’s billing address.

CreateStripeCheckoutSessionConsentCollection

Configure fields for the Checkout Session to gather active consent from customers.

object

Determines the position and visibility of the payment method reuse agreement in the UI. When set to auto, Stripe’s defaults will be used. When set to hidden, the payment method reuse agreement text will always be hidden in the UI.

promotions

string · enum

If set to auto, enables the collection of customer consent for promotional communications. The Checkout Session will determine whether to display an option to opt into promotional communication from the merchant depending on the customer’s locale. Only available to US merchants.

Enum values:

auto

none

termsOfService

string · enum

If set to required, it requires customers to check a terms of service checkbox before being able to pay. There must be a valid terms of service URL set in your Stripe Dashboard settings. https://dashboard.stripe.com/settings/public

Enum values:

none

required

CreateStripeCheckoutSessionConsentCollectionPaymentMethodReuseAgreement

Create Stripe checkout session payment method reuse agreement.

position

CreateStripeCheckoutSessionConsentCollectionPaymentMethodReuseAgreementPosition · enum

Create Stripe checkout session consent collection agreement position.

Enum values:

auto

hidden

CreateStripeCheckoutSessionConsentCollectionPaymentMethodReuseAgreementPosition

string · enum

Enum values:

auto

hidden

Create Stripe checkout session consent collection agreement position.

CreateStripeCheckoutSessionConsentCollectionPromotions

string · enum

Enum values:

auto

none

Create Stripe checkout session consent collection promotions.

CreateStripeCheckoutSessionConsentCollectionTermsOfService

string · enum

Enum values:

none

required

Create Stripe checkout session consent collection terms of service.

CreateStripeCheckoutSessionCustomerUpdate

Controls what fields on Customer can be updated by the Checkout Session.

address

string · enum

Describes whether Checkout saves the billing address onto customer.address. To always collect a full billing address, use billing_address_collection. Defaults to never.

Enum values:

auto

never

name

string · enum

Describes whether Checkout saves the name onto customer.name. Defaults to never.

Enum values:

auto

never

shipping

string · enum

Describes whether Checkout saves shipping information onto customer.shipping. To collect shipping information, use shipping_address_collection. Defaults to never.

Enum values:

auto

never

CreateStripeCheckoutSessionCustomerUpdateBehavior

string · enum

Enum values:

auto

never

Create Stripe checkout session customer update behavior.

CreateStripeCheckoutSessionRedirectOnCompletion

string · enum

Enum values:

always

if_required

never

Create Stripe checkout session redirect on completion.

CreateStripeCheckoutSessionRequest

Create Stripe checkout session request.

required

Provide a customer ID or key to use an existing Zuplo Metering customer. or provide a customer object to create a new customer.

object · required

Options passed to Stripe when creating the checkout session.

appId

string · pattern: ^[0-7][0-9A-HJKMNP-T…

If not provided, the default Stripe app is used if any.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

stripeCustomerId

string

Stripe customer ID. If not provided Zuplo Metering creates a new Stripe customer or uses the Zuplo Metering customer's default Stripe customer ID.

CreateStripeCheckoutSessionRequestOptions

Create Stripe checkout session options See https://docs.stripe.com/api/checkout/sessions/create

billingAddressCollection

string · enum

Specify whether Checkout should collect the customer’s billing address. Defaults to auto.

Enum values:

auto

required

cancelURL

string

If set, Checkout displays a back button and customers will be directed to this URL if they decide to cancel payment and return to your website. This parameter is not allowed if ui_mode is embedded.

clientReferenceID

string

A unique string to reference the Checkout Session. This can be a customer ID, a cart ID, or similar, and can be used to reconcile the session with your internal systems.

object

Controls what fields on Customer can be updated by the Checkout Session.

object

Configure fields for the Checkout Session to gather active consent from customers.

currency

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

Three-letter ISO currency code, in lowercase.

Example: USD

object

Display additional text for your customers using custom text.

expiresAt

integer · int64

The Epoch time in seconds at which the Checkout Session will expire. It can be anywhere from 30 minutes to 24 hours after Checkout Session creation. By default, this value is 24 hours from creation.

locale

string

object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

returnURL

string

The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method’s app or site. This parameter is required if ui_mode is embedded and redirect-based payment methods are enabled on the session.

successURL

string

The URL to which Stripe should send customers when payment or setup is complete. This parameter is not allowed if ui_mode is embedded. If you’d like to use information from the successful Checkout Session on your page, read the guide on customizing your success page: https://docs.stripe.com/payments/checkout/custom-success-page

uiMode

string · enum

The UI mode of the Session. Defaults to hosted.

Enum values:

embedded

hosted

paymentMethodTypes

string[]

A list of the types of payment methods (e.g., card) this Checkout Session can accept.

redirectOnCompletion

string · enum

This parameter applies to ui_mode: embedded. Defaults to always. Learn more about the redirect behavior of embedded sessions at https://docs.stripe.com/payments/checkout/custom-success-page?payment-ui=embedded-form

Enum values:

always

if_required

never

object

Controls tax ID collection during checkout.

CreateStripeCheckoutSessionResult

Create Stripe Checkout Session response.

customerId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The Zuplo Metering customer ID.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

stripeCustomerId

string · required

The Stripe customer ID.

sessionId

string · required

The checkout session ID.

setupIntentId

string · required

The checkout session setup intent ID.

createdAt

string · date-time · required

Timestamp at which the checkout session was created.

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

mode

string · enum · required

Mode Always setup for now.

Enum values:

setup

clientSecret

string

The client secret of the checkout session. This can be used to initialize Stripe.js for your client-side implementation.

clientReferenceId

string

A unique string to reference the Checkout Session. This can be a customer ID, a cart ID, or similar, and can be used to reconcile the session with your internal systems.

customerEmail

string

Customer's email address provided to Stripe.

currency

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

Three-letter ISO currency code, in lowercase.

Example: USD

expiresAt

string · date-time

Timestamp at which the checkout session will expire.

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

object

Set of key-value pairs attached to the checkout session.

status

string

The status of the checkout session.

url

string

URL to show the checkout session.

cancelURL

string

Cancel URL.

successURL

string

Success URL.

returnURL

string

Return URL.

CreateStripeCustomerPortalSessionParams

Stripe customer portal request params.

configurationId

string

The ID of an existing configuration to use for this session, describing its functionality and features. If not specified, the session uses the default configuration.

See https://docs.stripe.com/api/customer_portal/sessions/create#create_portal_session-configuration

locale

string

The IETF language tag of the locale customer portal is displayed in. If blank or auto, the customer’s preferred_locales or browser’s locale is used.

See: https://docs.stripe.com/api/customer_portal/sessions/create#create_portal_session-locale

returnUrl

string

The URL to redirect the customer to after they have completed their requested actions.

See: https://docs.stripe.com/api/customer_portal/sessions/create#create_portal_session-return_url

CreditNoteOriginalInvoiceRef

CreditNoteOriginalInvoiceRef is used to reference the original invoice that a credit note is based on.

type

string · enum · readOnly · required

Type of the invoice.

Enum values:

credit_note_original_invoice

url

string · uri · readOnly · required

Link to the source document.

issuedAt

string · date-time · readOnly

IssueAt reflects the time the document was issued.

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

number

string · minLength: 1 · maxLength: 256 · readOnly

(Serial) Number of the referenced document.

Example: INV-2024-01-01-01

reason

string · readOnly

Human readable description on why this reference is here or needs to be used.

description

string · readOnly

Additional details about the document.

Currency

Currency describes a currency supported by Zuplo Metering.

code

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

The currency ISO code.

Example: USD

name

string · required

The currency name.

symbol

string · required

The currency symbol.

subunits

integer · uint32 · required

Subunit of the currency.

CurrencyCode

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

Three-letter ISO4217 currency code. Custom three-letter currency codes are also supported for convenience.

Example: USD

CustomInvoicingApp

Custom Invoicing app can be used for interface with any invoicing or payment system. This app provides ways to manipulate invoices and payments, however the integration must rely on Notifications API to get notified about invoice changes.

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

object · readOnly · required

The marketplace listing that this installed app is based on.

Example: {"type":"stripe","name":"Stripe","description":"Stripe interation allows you to collect payments with Stripe.","capabilities":[{"type":"calculateTax","key":"stripe_calculate_tax","name":"Calculate Tax","description":"Stripe Tax calculates tax portion of the invoices."},{"type":"invoiceCustomers","key":"stripe_invoice_customers","name":"Invoice Customers","description":"Stripe invoices customers with due amount."},{"type":"collectPayments","key":"stripe_collect_payments","name":"Collect Payments","description":"Stripe payments collects outstanding revenue with Stripe customer's default payment method."}],"installMethods":["with_oauth2","with_api_key"]}

status

string · enum · readOnly · required

Status of the app connection.

Enum values:

ready

unauthorized

type

string · enum · required

The app's type is CustomInvoicing.

Enum values:

custom_invoicing

enableDraftSyncHook

boolean · required

Enable draft.sync hook.

If the hook is not enabled, the invoice will be progressed to the next state automatically.

enableIssuingSyncHook

boolean · required

Enable issuing.sync hook.

If the hook is not enabled, the invoice will be progressed to the next state automatically.

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

CustomInvoicingAppReplaceUpdate

Resource update operation model.

name

string · minLength: 1 · maxLength: 256 · required

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

type

string · enum · required

The app's type is CustomInvoicing.

Enum values:

custom_invoicing

enableDraftSyncHook

boolean · required

Enable draft.sync hook.

If the hook is not enabled, the invoice will be progressed to the next state automatically.

enableIssuingSyncHook

boolean · required

Enable issuing.sync hook.

If the hook is not enabled, the invoice will be progressed to the next state automatically.

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

CustomInvoicingCustomerAppData

Custom Invoicing Customer App Data.

type

string · enum · required

The app name.

Enum values:

custom_invoicing

object · readOnly

The installed custom invoicing app this data belongs to.

id

string · pattern: ^[0-7][0-9A-HJKMNP-T…

The app ID. If not provided, it will use the global default for the app type.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

object

Metadata to be used by the custom invoicing provider.

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

CustomInvoicingDraftSynchronizedRequest

Information to finalize the draft details of an invoice.

object

The result of the synchronization.

CustomInvoicingFinalizedInvoicingRequest

Information to finalize the invoicing details of an invoice.

invoiceNumber

string · minLength: 1 · maxLength: 256

If set the invoice's number will be set to this value.

Example: INV-2024-01-01-01

sentToCustomerAt

string · date-time

If set the invoice's sent to customer at will be set to this value.

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

CustomInvoicingFinalizedPaymentRequest

Information to finalize the payment details of an invoice.

externalId

string

If set the invoice's payment external ID will be set to this value.

CustomInvoicingFinalizedRequest

Information to finalize the invoice. If invoicing.invoiceNumber is not set, then a new invoice number will be generated (INV- prefix).

object

The result of the synchronization.

object

The result of the payment synchronization.

CustomInvoicingLineDiscountExternalIdMapping

Mapping between line discounts and external IDs.

lineDiscountId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The line discount ID.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

externalId

string · required

The external ID (e.g. custom invoicing system's ID).

CustomInvoicingLineExternalIdMapping

Mapping between lines and external IDs.

lineId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The line ID.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

externalId

string · required

The external ID (e.g. custom invoicing system's ID).

CustomInvoicingPaymentTrigger

string · enum

Enum values:

paid

payment_failed

payment_uncollectible

payment_overdue

action_required

void

Payment trigger to execute on a finalized invoice.

CustomInvoicingSyncResult

Information to synchronize the invoice. Can be used to store external app's IDs on the invoice or lines.

invoiceNumber

string · minLength: 1 · maxLength: 256

If set the invoice's number will be set to this value.

Example: INV-2024-01-01-01

externalId

string

If set the invoice's invoicing external ID will be set to this value.

CustomInvoicingLineExternalIdMapping[]

If set the invoice's line external IDs will be set to this value.

This can be used to reference the external system's entities in the invoice.

CustomInvoicingLineDiscountExternalIdMapping[]

If set the invoice's line discount external IDs will be set to this value.

This can be used to reference the external system's entities in the invoice.

CustomInvoicingTaxConfig

Custom invoicing tax config.

code

string · required

Tax code.

The tax code should be interpreted by the custom invoicing provider.

CustomInvoicingUpdatePaymentStatusRequest

Update payment status request. Can be used to manipulate invoice's payment status (when custominvoicing app is being used).

trigger

string · enum · required

The trigger to be executed on the invoice.

Enum values:

paid

payment_failed

payment_uncollectible

payment_overdue

action_required

void

CustomPlanInput

Plan input for custom subscription creation (without key and version).

name

string · minLength: 1 · maxLength: 256 · required

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

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

CustomSubscriptionChange

Change a custom subscription.

required

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

object · required

The custom plan description which defines the Subscription.

billingAnchor

string · date-time

The billing anchor of the subscription. The provided date will be normalized according to the billing cadence to the nearest recurrence before start time. If not provided, the previous subscription billing anchor will be used.

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

CustomSubscriptionCreate

Create a custom subscription.

object · required

The custom plan description which defines the Subscription.

Timing configuration for the change, when the change should take effect. The default is immediate.

Default: immediate

customerId

string · pattern: ^[0-7][0-9A-HJKMNP-T…

The ID of the customer. Provide either the key or ID. Has presedence over the key.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

customerKey

string · minLength: 1 · maxLength: 256

The key of the customer. Provide either the key or ID.

billingAnchor

string · date-time

The billing anchor of the subscription. The provided date will be normalized according to the billing cadence to the nearest recurrence before start time. If not provided, the subscription start time will be used.

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

Customer

A customer object.

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

object · required

Mapping to attribute metered usage to the customer

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

key

string · minLength: 1 · maxLength: 256

An optional unique key of the customer. Useful to reference the customer in external systems. For example, your database ID.

primaryEmail

string

The primary email address of the customer.

currency

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

Currency of the customer. Used for billing, tax and invoicing.

Example: USD

object

The billing address of the customer. Used for tax and invoicing.

currentSubscriptionId

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T…

The ID of the Subscription if the customer has one.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

Subscription[] · readOnly

The subscriptions of the customer. Only with the subscriptions expand option.

object · readOnly

Set of key-value pairs managed by the system. Cannot be modified by user.

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

CustomerAccess

CustomerAccess describes what features the customer has access to.

SubscriptionEntitlements[] · readOnly · required

List of subscription-based entitlements grouped by subscription. Each item contains a subscription ID and its associated entitlements.

CustomerAppData

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · type="stripe" · requires: stripeCustomerId
	type = object · type="sandbox"
	type = object · type="custom_invoicing"

Properties for Variant 1:

Stripe Customer App Data.

StripeCustomerAppData

type

string · enum · required

The app name.

Enum values:

stripe

stripeCustomerId

string · required

The Stripe customer ID.

id

string · pattern: ^[0-7][0-9A-HJKMNP-T…

The app ID. If not provided, it will use the global default for the app type.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

stripeDefaultPaymentMethodId

string

The Stripe default payment method ID.

object · readOnly

The installed stripe app this data belongs to.

Example: {"id":"01G65Z755AFWAKHE12NY0CQ9FH","type":"stripe","name":"Stripe","status":"ready","listing":{"type":"stripe","name":"Stripe","description":"Stripe interation allows you to collect payments with Stripe.","capabilities":[{"type":"calculateTax","key":"stripe_calculate_tax","name":"Calculate Tax","description":"Stripe Tax calculates tax portion of the invoices."},{"type":"invoiceCustomers","key":"stripe_invoice_customers","name":"Invoice Customers","description":"Stripe invoices customers with due amount."},{"type":"collectPayments","key":"stripe_collect_payments","name":"Collect Payments","description":"Stripe payments collects outstanding revenue with Stripe customer's default payment method."}],"installMethods":["with_oauth2","with_api_key"]},"createdAt":"2024-01-01T01:01:01.001Z","updatedAt":"2024-01-01T01:01:01.001Z","stripeAccountId":"acct_123456789","livemode":true,"maskedAPIKey":"sk_live_************abc"}

CustomerAppDataCreateOrUpdateItem

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · type="stripe" · requires: stripeCustomerId
	type = object · type="sandbox"
	type = object · type="custom_invoicing"

Properties for Variant 1:

Stripe Customer App Data.

StripeCustomerAppDataCreateOrUpdateItem

type

string · enum · required

The app name.

Enum values:

stripe

stripeCustomerId

string · required

The Stripe customer ID.

id

string · pattern: ^[0-7][0-9A-HJKMNP-T…

The app ID. If not provided, it will use the global default for the app type.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

stripeDefaultPaymentMethodId

string

The Stripe default payment method ID.

CustomerAppDataPaginatedResponse

Paginated response

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

CustomerAppData[] · required

The items in the current page.

CustomerCreate

Resource create operation model.

name

string · minLength: 1 · maxLength: 256 · required

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

object · required

Mapping to attribute metered usage to the customer

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

key

string · minLength: 1 · maxLength: 256

An optional unique key of the customer. Useful to reference the customer in external systems. For example, your database ID.

primaryEmail

string

The primary email address of the customer.

currency

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

Currency of the customer. Used for billing, tax and invoicing.

Example: USD

object

The billing address of the customer. Used for tax and invoicing.

CustomerExpand

string · enum

Enum values:

subscriptions

CustomerExpand specifies the parts of the customer to expand in the list output.

CustomerId

Create Stripe checkout session with customer ID.

id

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

ULID (Universally Unique Lexicographically Sortable Identifier).

Example: 01G65Z755AFWAKHE12NY0CQ9FH

CustomerKey

Create Stripe checkout session with customer key.

key

string · required

CustomerOrderBy

string · enum

Enum values:

id

name

createdAt

Order by options for customers.

CustomerPaginatedResponse

Paginated response

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

Customer[] · required

The items in the current page.

CustomerReplaceUpdate

Resource update operation model.

name

string · minLength: 1 · maxLength: 256 · required

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

object · required

Mapping to attribute metered usage to the customer

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

key

string · minLength: 1 · maxLength: 256

An optional unique key of the customer. Useful to reference the customer in external systems. For example, your database ID.

primaryEmail

string

The primary email address of the customer.

currency

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

Currency of the customer. Used for billing, tax and invoicing.

Example: USD

object

The billing address of the customer. Used for tax and invoicing.

CustomerSubscriptionOrderBy

string · enum

Enum values:

activeFrom

activeTo

Order by options for customer subscriptions.

CustomerUsageAttribution

Mapping to attribute metered usage to the customer. One customer can have multiple subjects, but one subject can only belong to one customer.

subjectKeys

string[] · minItems: 1 · maxItems: 1 · required

The subjects that are attributed to the customer.

DiscountPercentage

Percentage discount.

percentage

number · double · min: 0 · max: 100 · required

The percentage of the discount.

Example: 50

DiscountReasonMaximumSpend

The reason for the discount is a maximum spend.

type

string · enum · required

Enum values:

maximum_spend

DiscountReasonProrationCredit

The reason for the discount is a proration credit from a previous subscription.

type

string · enum · required

Enum values:

proration_credit

previousSubscriptionId

string · required

The ID of the previous subscription that generated this credit.

maxPercentage

string · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The maximum percentage (of time or consumption) used to calculate the credit.

DiscountReasonRatecardPercentage

The reason for the discount is a ratecard percentage.

type

string · enum · required

Enum values:

ratecard_percentage

percentage

number · double · min: 0 · max: 100 · required

The percentage of the discount.

Example: 50

correlationId

string · pattern: ^[0-7][0-9A-HJKMNP-T…

Correlation ID for the discount.

This is used to link discounts across different invoices (progressive billing use case).

If not provided, the invoicing engine will auto-generate one. When editing an invoice line, please make sure to keep the same correlation ID of the discount or in progressive billing setups the discount amounts might be incorrect.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

DiscountReasonRatecardUsage

The reason for the discount is a ratecard usage.

type

string · enum · required

Enum values:

ratecard_usage

quantity

string · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The quantity of the usage discount.

Must be positive.

correlationId

string · pattern: ^[0-7][0-9A-HJKMNP-T…

Correlation ID for the discount.

This is used to link discounts across different invoices (progressive billing use case).

If not provided, the invoicing engine will auto-generate one. When editing an invoice line, please make sure to keep the same correlation ID of the discount or in progressive billing setups the discount amounts might be incorrect.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

DiscountReasonType

string · enum

Enum values:

maximum_spend

ratecard_percentage

ratecard_usage

proration_credit

The type of the discount reason.

DiscountUsage

Usage discount. Usage discount means that the first N items are free. From billing perspective this means that any usage on a specific feature is considered 0 until this discount is exhausted.

quantity

string · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The quantity of the usage discount.

Must be positive.

Discounts

Discount by type on a price

object

The percentage discount.

object

The usage discount.

DynamicPrice

Dynamic price. The underlying meter's value is considered the base price in the customer's currency. The rate specifies the markup over the price.

type

string · enum · required

The type of the price.

Enum values:

dynamic

multiplier

string · pattern: ^\-?[0-9]+(\.[0-9]+)…

The multiplier to apply to the base price to get the dynamic price.

Examples:

0.0: the price is zero
0.5: the price is 50% of the base price
1.0: the price is the same as the base price
1.5: the price is 150% of the base price

Default: 1

DynamicPriceWithCommitments

Dynamic price with spend commitments.

type

string · enum · required

The type of the price.

Enum values:

dynamic

multiplier

string · pattern: ^\-?[0-9]+(\.[0-9]+)…

The multiplier to apply to the base price to get the dynamic price.

Examples:

0.0: the price is zero
0.5: the price is 50% of the base price
1.0: the price is the same as the base price
1.5: the price is 150% of the base price

Default: 1

minimumAmount

string · pattern: ^\-?[0-9]+(\.[0-9]+)…

The customer is committed to spend at least the amount.

maximumAmount

string · pattern: ^\-?[0-9]+(\.[0-9]+)…

The customer is limited to spend at most the amount.

EditOp

string · enum

Enum values:

add_item

remove_item

unschedule_edit

add_phase

remove_phase

stretch_phase

Enum listing the different operation types.

EditSubscriptionAddItem

Add a new item to a phase.

op

string · enum · required

Enum values:

add_item

phaseKey

string · required

RateCard · required

A rate card defines the pricing and entitlement of a feature or service.

EditSubscriptionAddPhase

Add a new phase

op

string · enum · required

Enum values:

add_phase

SubscriptionPhaseCreate · required

Subscription phase create input.

EditSubscriptionRemoveItem

Remove an item from a phase.

op

string · enum · required

Enum values:

remove_item

phaseKey

string · required

itemKey

string · required

EditSubscriptionRemovePhase

Remove a phase

op

string · enum · required

Enum values:

remove_phase

phaseKey

string · required

shift

RemovePhaseShifting · enum · required

The direction of the phase shift when a phase is removed.

Enum values:

EditSubscriptionStretchPhase

Stretch a phase

op

string · enum · required

Enum values:

stretch_phase

phaseKey

string · required

extendBy

string · duration · required

EditSubscriptionUnscheduleEdit

Unschedules any edits from the current phase.

op

string · enum · required

Enum values:

unschedule_edit

Entitlement

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · type="metered" · requires: createdAt, updatedAt, activeFrom +8 more
	type = object · type="static" · requires: config, createdAt, updatedAt +5 more
	type = object · type="boolean" · requires: createdAt, updatedAt, activeFrom +4 more

Properties for Variant 1:

Metered entitlements are useful for many different use cases, from setting up usage based access to implementing complex credit systems. Access is determined based on feature usage using a balance calculation (the "usage allowance" provided by the issued grants is "burnt down" by the usage).

EntitlementMetered

type

string · enum · required

Enum values:

metered

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

activeFrom

string · date-time · required

The cadence start of the resource.

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Readonly unique ULID identifier.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

subjectKey

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

The identifier key unique to the subject. NOTE: Subjects are being deprecated, please use the new customer APIs.

Example: customer-1

featureKey

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

The feature the subject is entitled to use.

Example: example-feature-key

featureId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The feature the subject is entitled to use.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

lastReset

string · date-time · readOnly · required

The time the last reset happened.

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

object · readOnly · required

The current usage period.

measureUsageFrom

string · date-time · readOnly · required

The time from which usage is measured. If not specified on creation, defaults to entitlement creation time.

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

isSoftLimit

boolean

If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true.

Default: false

issueAfterReset

number · double · min: 0

You can grant usage automatically alongside the entitlement, the example scenario would be creating a starting balance. If an amount is specified here, a grant will be created alongside the entitlement with the specified amount. That grant will have it's rollover settings configured in a way that after each reset operation, the balance will return the original amount specified here. Manually creating such a grant would mean having the "amount", "minRolloverAmount", and "maxRolloverAmount" fields all be the same.

issueAfterResetPriority

integer · uint8 · min: 1 · max: 255

Defines the grant priority for the default grant.

Default: 1

preserveOverageAtReset

boolean

If true, the overage is preserved at reset. If false, the usage is reset to 0.

Default: false

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

object

Additional metadata for the feature.

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

activeTo

string · date-time

The cadence end of the resource.

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

object · readOnly

The annotations of the entitlement.

Example: {"subscription.id":"sub_123"}

EntitlementBaseTemplate

Shared fields of the entitlement templates.

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

activeFrom

string · date-time · required

The cadence start of the resource.

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Readonly unique ULID identifier.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

type

string · enum · required

The type of the entitlement.

Enum values:

metered

boolean

static

subjectKey

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

The identifier key unique to the subject. NOTE: Subjects are being deprecated, please use the new customer APIs.

Example: customer-1

featureKey

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

The feature the subject is entitled to use.

Example: example-feature-key

featureId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The feature the subject is entitled to use.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

object

Additional metadata for the feature.

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

activeTo

string · date-time

The cadence end of the resource.

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

object · readOnly

The annotations of the entitlement.

Example: {"subscription.id":"sub_123"}

object

The current usage period.

EntitlementBoolean

Entitlement template of a boolean entitlement.

type

string · enum · required

Enum values:

boolean

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

activeFrom

string · date-time · required

The cadence start of the resource.

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Readonly unique ULID identifier.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

subjectKey

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

The identifier key unique to the subject. NOTE: Subjects are being deprecated, please use the new customer APIs.

Example: customer-1

featureKey

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

The feature the subject is entitled to use.

Example: example-feature-key

featureId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The feature the subject is entitled to use.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

object

Additional metadata for the feature.

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

activeTo

string · date-time

The cadence end of the resource.

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

object · readOnly

The annotations of the entitlement.

Example: {"subscription.id":"sub_123"}

object

The current usage period.

EntitlementBooleanCreateInputs

Create inputs for boolean entitlement

type

string · enum · required

Enum values:

boolean

featureKey

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

The feature the subject is entitled to use. Either featureKey or featureId is required.

Example: example-feature-key

featureId

string · pattern: ^[0-7][0-9A-HJKMNP-T…

The feature the subject is entitled to use. Either featureKey or featureId is required.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

object

Additional metadata for the feature.

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

object

The usage period associated with the entitlement.

Example: {"interval":"DAY","anchor":"2023-01-01T01:01:01.001Z"}

EntitlementBooleanV2

Entitlement template of a boolean entitlement.

type

string · enum · required

Enum values:

boolean

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

activeFrom

string · date-time · required

The cadence start of the resource.

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Readonly unique ULID identifier.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

featureKey

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

The feature the subject is entitled to use.

Example: example-feature-key

featureId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The feature the subject is entitled to use.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

customerId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The identifier unique to the customer

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

object

Additional metadata for the feature.

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

activeTo

string · date-time

The cadence end of the resource.

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

object · readOnly

The annotations of the entitlement.

Example: {"subscription.id":"sub_123"}

object

The current usage period.

customerKey

string

The identifier key unique to the customer

Example: customer-1

EntitlementCreateInputs

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · type="metered" · requires: usagePeriod
	type = object · type="static" · requires: config
	type = object · type="boolean"

Properties for Variant 1:

Create inpurs for metered entitlement

EntitlementMeteredCreateInputs

type

string · enum · required

Enum values:

metered

object · required

The usage period associated with the entitlement.

Example: {"interval":"DAY","anchor":"2023-01-01T01:01:01.001Z"}

featureKey

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

The feature the subject is entitled to use. Either featureKey or featureId is required.

Example: example-feature-key

featureId

string · pattern: ^[0-7][0-9A-HJKMNP-T…

The feature the subject is entitled to use. Either featureKey or featureId is required.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

object

Additional metadata for the feature.

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

isSoftLimit

boolean

If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true.

Default: false

Defines the time from which usage is measured. If not specified on creation, defaults to entitlement creation time.

issueAfterReset

number · double · min: 0

You can grant usage automatically alongside the entitlement, the example scenario would be creating a starting balance. If an amount is specified here, a grant will be created alongside the entitlement with the specified amount. That grant will have it's rollover settings configured in a way that after each reset operation, the balance will return the original amount specified here. Manually creating such a grant would mean having the "amount", "minRolloverAmount", and "maxRolloverAmount" fields all be the same.

issueAfterResetPriority

integer · uint8 · min: 1 · max: 255

Defines the grant priority for the default grant.

Default: 1

preserveOverageAtReset

boolean

If true, the overage is preserved at reset. If false, the usage is reset to 0.

Default: false

EntitlementCreateSharedFields

Shared fields for entitlement creation

featureKey

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

The feature the subject is entitled to use. Either featureKey or featureId is required.

Example: example-feature-key

featureId

string · pattern: ^[0-7][0-9A-HJKMNP-T…

The feature the subject is entitled to use. Either featureKey or featureId is required.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

object

Additional metadata for the feature.

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

object

The usage period associated with the entitlement.

Example: {"interval":"DAY","anchor":"2023-01-01T01:01:01.001Z"}

EntitlementCustomerFields

Customer fields for entitlements

customerId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The identifier unique to the customer

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

customerKey

string

The identifier key unique to the customer

Example: customer-1

EntitlementGrant

The grant.

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

amount

number · double · min: 0 · required

The amount to grant. Should be a positive number.

Example: 100

effectiveAt

string · date-time · required

Effective date for grants and anchor for recurring grants. Provided value will be ceiled to metering windowSize (minute).

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

object · required

The grant expiration definition

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Readonly unique ULID identifier.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

entitlementId

string · readOnly · required

The unique entitlement ULID that the grant is associated with.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

priority

integer · uint8 · min: 1 · max: 255

The priority of the grant. Grants with higher priority are applied first. Priority is a positive decimal numbers. With lower numbers indicating higher importance. For example, a priority of 1 is more urgent than a priority of 2. When there are several grants available for the same subject, the system selects the grant with the highest priority. In cases where grants share the same priority level, the grant closest to its expiration will be used first. In the case of two grants have identical priorities and expiration dates, the system will use the grant that was created first.

Example: 1

maxRolloverAmount

number · double

Grants are rolled over at reset, after which they can have a different balance compared to what they had before the reset. Balance after the reset is calculated as: Balance_After_Reset = MIN(MaxRolloverAmount, MAX(Balance_Before_Reset, MinRolloverAmount))

Example: 100

Default: 0

minRolloverAmount

number · double

Grants are rolled over at reset, after which they can have a different balance compared to what they had before the reset. Balance after the reset is calculated as: Balance_After_Reset = MIN(MaxRolloverAmount, MAX(Balance_Before_Reset, MinRolloverAmount))

Example: 100

Default: 0

object

The grant metadata.

Example: {"stripePaymentId":"pi_4OrAkhLvyihio9p51h9iiFnB"}

nextRecurrence

string · date-time

The next time the grant will recurr.

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

expiresAt

string · date-time · readOnly

The time the grant expires.

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

voidedAt

string · date-time

The time the grant was voided.

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

object

Grant annotations

Example: {"issueAfterReset":true}

EntitlementGrantCreateInput

The grant creation input.

amount

number · double · min: 0 · required

The amount to grant. Should be a positive number.

Example: 100

effectiveAt

string · date-time · required

Effective date for grants and anchor for recurring grants. Provided value will be ceiled to metering windowSize (minute).

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

object · required

The grant expiration definition

priority

integer · uint8 · min: 1 · max: 255

The priority of the grant. Grants with higher priority are applied first. Priority is a positive decimal numbers. With lower numbers indicating higher importance. For example, a priority of 1 is more urgent than a priority of 2. When there are several grants available for the same subject, the system selects the grant with the highest priority. In cases where grants share the same priority level, the grant closest to its expiration will be used first. In the case of two grants have identical priorities and expiration dates, the system will use the grant that was created first.

Example: 1

maxRolloverAmount

number · double

Grants are rolled over at reset, after which they can have a different balance compared to what they had before the reset. Balance after the reset is calculated as: Balance_After_Reset = MIN(MaxRolloverAmount, MAX(Balance_Before_Reset, MinRolloverAmount))

Example: 100

Default: 0

minRolloverAmount

number · double

Grants are rolled over at reset, after which they can have a different balance compared to what they had before the reset. Balance after the reset is calculated as: Balance_After_Reset = MIN(MaxRolloverAmount, MAX(Balance_Before_Reset, MinRolloverAmount))

Example: 100

Default: 0

object

The grant metadata.

Example: {"stripePaymentId":"pi_4OrAkhLvyihio9p51h9iiFnB"}

object

The subject of the grant.

Example: {"interval":"DAY","anchor":"2023-01-01T01:01:01.001Z"}

EntitlementGrantCreateInputV2

The grant creation input.

amount

number · double · min: 0 · required

The amount to grant. Should be a positive number.

Example: 100

effectiveAt

string · date-time · required

Effective date for grants and anchor for recurring grants. Provided value will be ceiled to metering windowSize (minute).

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

priority

integer · uint8 · min: 1 · max: 255

The priority of the grant. Grants with higher priority are applied first. Priority is a positive decimal numbers. With lower numbers indicating higher importance. For example, a priority of 1 is more urgent than a priority of 2. When there are several grants available for the same subject, the system selects the grant with the highest priority. In cases where grants share the same priority level, the grant closest to its expiration will be used first. In the case of two grants have identical priorities and expiration dates, the system will use the grant that was created first.

Example: 1

minRolloverAmount

number · double

Grants are rolled over at reset, after which they can have a different balance compared to what they had before the reset. Balance after the reset is calculated as: Balance_After_Reset = MIN(MaxRolloverAmount, MAX(Balance_Before_Reset, MinRolloverAmount))

Example: 100

Default: 0

object

The grant metadata.

Example: {"stripePaymentId":"pi_4OrAkhLvyihio9p51h9iiFnB"}

object

The subject of the grant.

Example: {"interval":"DAY","anchor":"2023-01-01T01:01:01.001Z"}

maxRolloverAmount

number · double

Grants are rolled over at reset, after which they can have a different balance compared to what they had before the reset. The default value equals grant amount. Balance after the reset is calculated as: Balance_After_Reset = MIN(MaxRolloverAmount, MAX(Balance_Before_Reset, MinRolloverAmount))

Example: 100

object

The grant expiration definition. If no expiration is provided, the grant can be active indefinitely.

object

Grant annotations

Example: {"internal_reference":"internal_reference"}

EntitlementGrantV2

The grant.

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

amount

number · double · min: 0 · required

The amount to grant. Should be a positive number.

Example: 100

effectiveAt

string · date-time · required

Effective date for grants and anchor for recurring grants. Provided value will be ceiled to metering windowSize (minute).

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Readonly unique ULID identifier.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

entitlementId

string · readOnly · required

The unique entitlement ULID that the grant is associated with.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

priority

integer · uint8 · min: 1 · max: 255

The priority of the grant. Grants with higher priority are applied first. Priority is a positive decimal numbers. With lower numbers indicating higher importance. For example, a priority of 1 is more urgent than a priority of 2. When there are several grants available for the same subject, the system selects the grant with the highest priority. In cases where grants share the same priority level, the grant closest to its expiration will be used first. In the case of two grants have identical priorities and expiration dates, the system will use the grant that was created first.

Example: 1

minRolloverAmount

number · double

Grants are rolled over at reset, after which they can have a different balance compared to what they had before the reset. Balance after the reset is calculated as: Balance_After_Reset = MIN(MaxRolloverAmount, MAX(Balance_Before_Reset, MinRolloverAmount))

Example: 100

Default: 0

object

The grant metadata.

Example: {"stripePaymentId":"pi_4OrAkhLvyihio9p51h9iiFnB"}

maxRolloverAmount

number · double

Grants are rolled over at reset, after which they can have a different balance compared to what they had before the reset. The default value equals grant amount. Balance after the reset is calculated as: Balance_After_Reset = MIN(MaxRolloverAmount, MAX(Balance_Before_Reset, MinRolloverAmount))

Example: 100

object

The grant expiration definition. If no expiration is provided, the grant can be active indefinitely.

object

Grant annotations

Example: {"internal_reference":"internal_reference"}

nextRecurrence

string · date-time

The next time the grant will recurr.

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

expiresAt

string · date-time · readOnly

The time the grant expires.

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

voidedAt

string · date-time

The time the grant was voided.

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

EntitlementMetered

Metered entitlements are useful for many different use cases, from setting up usage based access to implementing complex credit systems. Access is determined based on feature usage using a balance calculation (the "usage allowance" provided by the issued grants is "burnt down" by the usage).

type

string · enum · required

Enum values:

metered

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

activeFrom

string · date-time · required

The cadence start of the resource.

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Readonly unique ULID identifier.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

subjectKey

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

The identifier key unique to the subject. NOTE: Subjects are being deprecated, please use the new customer APIs.

Example: customer-1

featureKey

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

The feature the subject is entitled to use.

Example: example-feature-key

featureId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The feature the subject is entitled to use.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

lastReset

string · date-time · readOnly · required

The time the last reset happened.

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

object · readOnly · required

The current usage period.

measureUsageFrom

string · date-time · readOnly · required

The time from which usage is measured. If not specified on creation, defaults to entitlement creation time.

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

isSoftLimit

boolean

If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true.

Default: false

issueAfterReset

number · double · min: 0

You can grant usage automatically alongside the entitlement, the example scenario would be creating a starting balance. If an amount is specified here, a grant will be created alongside the entitlement with the specified amount. That grant will have it's rollover settings configured in a way that after each reset operation, the balance will return the original amount specified here. Manually creating such a grant would mean having the "amount", "minRolloverAmount", and "maxRolloverAmount" fields all be the same.

issueAfterResetPriority

integer · uint8 · min: 1 · max: 255

Defines the grant priority for the default grant.

Default: 1

preserveOverageAtReset

boolean

If true, the overage is preserved at reset. If false, the usage is reset to 0.

Default: false

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

object

Additional metadata for the feature.

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

activeTo

string · date-time

The cadence end of the resource.

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

object · readOnly

The annotations of the entitlement.

Example: {"subscription.id":"sub_123"}

EntitlementMeteredCalculatedFields

Calculated fields for metered entitlements.

lastReset

string · date-time · readOnly · required

The time the last reset happened.

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

object · readOnly · required

The current usage period.

measureUsageFrom

string · date-time · readOnly · required

The time from which usage is measured. If not specified on creation, defaults to entitlement creation time.

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

EntitlementMeteredCreateInputs

Create inpurs for metered entitlement

type

string · enum · required

Enum values:

metered

object · required

The usage period associated with the entitlement.

Example: {"interval":"DAY","anchor":"2023-01-01T01:01:01.001Z"}

featureKey

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

The feature the subject is entitled to use. Either featureKey or featureId is required.

Example: example-feature-key

featureId

string · pattern: ^[0-7][0-9A-HJKMNP-T…

The feature the subject is entitled to use. Either featureKey or featureId is required.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

object

Additional metadata for the feature.

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

isSoftLimit

boolean

If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true.

Default: false

Defines the time from which usage is measured. If not specified on creation, defaults to entitlement creation time.

issueAfterReset

number · double · min: 0

You can grant usage automatically alongside the entitlement, the example scenario would be creating a starting balance. If an amount is specified here, a grant will be created alongside the entitlement with the specified amount. That grant will have it's rollover settings configured in a way that after each reset operation, the balance will return the original amount specified here. Manually creating such a grant would mean having the "amount", "minRolloverAmount", and "maxRolloverAmount" fields all be the same.

issueAfterResetPriority

integer · uint8 · min: 1 · max: 255

Defines the grant priority for the default grant.

Default: 1

preserveOverageAtReset

boolean

If true, the overage is preserved at reset. If false, the usage is reset to 0.

Default: false

EntitlementMeteredV2

Metered entitlements are useful for many different use cases, from setting up usage based access to implementing complex credit systems. Access is determined based on feature usage using a balance calculation (the "usage allowance" provided by the issued grants is "burnt down" by the usage).

type

string · enum · required

Enum values:

metered

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

activeFrom

string · date-time · required

The cadence start of the resource.

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Readonly unique ULID identifier.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

featureKey

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

The feature the subject is entitled to use.

Example: example-feature-key

featureId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The feature the subject is entitled to use.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

lastReset

string · date-time · readOnly · required

The time the last reset happened.

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

object · readOnly · required

The current usage period.

measureUsageFrom

string · date-time · readOnly · required

The time from which usage is measured. If not specified on creation, defaults to entitlement creation time.

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

customerId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The identifier unique to the customer

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

isSoftLimit

boolean

If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true.

Default: false

preserveOverageAtReset

boolean

If true, the overage is preserved at reset. If false, the usage is reset to 0.

Default: false

object

Issue after reset

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

object

Additional metadata for the feature.

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

activeTo

string · date-time

The cadence end of the resource.

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

object · readOnly

The annotations of the entitlement.

Example: {"subscription.id":"sub_123"}

customerKey

string

The identifier key unique to the customer

Example: customer-1

EntitlementMeteredV2CreateInputs

Create inputs for metered entitlement

type

string · enum · required

Enum values:

metered

object · required

The usage period associated with the entitlement.

Example: {"interval":"DAY","anchor":"2023-01-01T01:01:01.001Z"}

featureKey

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

The feature the subject is entitled to use. Either featureKey or featureId is required.

Example: example-feature-key

featureId

string · pattern: ^[0-7][0-9A-HJKMNP-T…

The feature the subject is entitled to use. Either featureKey or featureId is required.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

object

Additional metadata for the feature.

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

isSoftLimit

boolean

If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true.

Default: false

Defines the time from which usage is measured. If not specified on creation, defaults to entitlement creation time.

preserveOverageAtReset

boolean

If true, the overage is preserved at reset. If false, the usage is reset to 0.

Default: false

object

Issue after reset

EntitlementGrantCreateInputV2[]

Grants

EntitlementOrderBy

string · enum

Enum values:

createdAt

updatedAt

Order by options for entitlements.

EntitlementPaginatedResponse

Paginated response

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

Entitlement[] · required

The items in the current page.

EntitlementStatic

A static entitlement.

type

string · enum · required

Enum values:

static

config

string · json · required

The JSON parsable config of the entitlement. This value is also returned when checking entitlement access and it is useful for configuring fine-grained access settings to the feature, implemented in your own system. Has to be an object.

Example: { "integrations": ["github"] }

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

activeFrom

string · date-time · required

The cadence start of the resource.

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Readonly unique ULID identifier.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

subjectKey

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

The identifier key unique to the subject. NOTE: Subjects are being deprecated, please use the new customer APIs.

Example: customer-1

featureKey

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

The feature the subject is entitled to use.

Example: example-feature-key

featureId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The feature the subject is entitled to use.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

object

Additional metadata for the feature.

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

activeTo

string · date-time

The cadence end of the resource.

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

object · readOnly

The annotations of the entitlement.

Example: {"subscription.id":"sub_123"}

object

The current usage period.

EntitlementStaticCreateInputs

Create inputs for static entitlement

type

string · enum · required

Enum values:

static

config

string · json · required

The JSON parsable config of the entitlement. This value is also returned when checking entitlement access and it is useful for configuring fine-grained access settings to the feature, implemented in your own system. Has to be an object.

Example: { "integrations": ["github"] }

featureKey

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

The feature the subject is entitled to use. Either featureKey or featureId is required.

Example: example-feature-key

featureId

string · pattern: ^[0-7][0-9A-HJKMNP-T…

The feature the subject is entitled to use. Either featureKey or featureId is required.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

object

Additional metadata for the feature.

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

object

The usage period associated with the entitlement.

Example: {"interval":"DAY","anchor":"2023-01-01T01:01:01.001Z"}

EntitlementStaticV2

A static entitlement.

type

string · enum · required

Enum values:

static

config

string · json · required

The JSON parsable config of the entitlement. This value is also returned when checking entitlement access and it is useful for configuring fine-grained access settings to the feature, implemented in your own system. Has to be an object.

Example: { "integrations": ["github"] }

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

activeFrom

string · date-time · required

The cadence start of the resource.

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Readonly unique ULID identifier.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

featureKey

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

The feature the subject is entitled to use.

Example: example-feature-key

featureId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The feature the subject is entitled to use.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

customerId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The identifier unique to the customer

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

object

Additional metadata for the feature.

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

activeTo

string · date-time

The cadence end of the resource.

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

object · readOnly

The annotations of the entitlement.

Example: {"subscription.id":"sub_123"}

object

The current usage period.

customerKey

string

The identifier key unique to the customer

Example: customer-1

EntitlementType

string · enum

Enum values:

metered

boolean

static

Type of the entitlement.

EntitlementV2

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · type="metered" · requires: createdAt, updatedAt, activeFrom +8 more
	type = object · type="static" · requires: config, createdAt, updatedAt +5 more
	type = object · type="boolean" · requires: createdAt, updatedAt, activeFrom +4 more

Properties for Variant 1:

Metered entitlements are useful for many different use cases, from setting up usage based access to implementing complex credit systems. Access is determined based on feature usage using a balance calculation (the "usage allowance" provided by the issued grants is "burnt down" by the usage).

EntitlementMeteredV2

type

string · enum · required

Enum values:

metered

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

activeFrom

string · date-time · required

The cadence start of the resource.

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Readonly unique ULID identifier.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

featureKey

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

The feature the subject is entitled to use.

Example: example-feature-key

featureId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The feature the subject is entitled to use.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

lastReset

string · date-time · readOnly · required

The time the last reset happened.

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

object · readOnly · required

The current usage period.

measureUsageFrom

string · date-time · readOnly · required

The time from which usage is measured. If not specified on creation, defaults to entitlement creation time.

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

customerId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The identifier unique to the customer

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

isSoftLimit

boolean

If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true.

Default: false

preserveOverageAtReset

boolean

If true, the overage is preserved at reset. If false, the usage is reset to 0.

Default: false

object

Issue after reset

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

object

Additional metadata for the feature.

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

activeTo

string · date-time

The cadence end of the resource.

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

object · readOnly

The annotations of the entitlement.

Example: {"subscription.id":"sub_123"}

customerKey

string

The identifier key unique to the customer

Example: customer-1

EntitlementV2CreateInputs

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · type="metered" · requires: usagePeriod
	type = object · type="static" · requires: config
	type = object · type="boolean"

Properties for Variant 1:

Create inputs for metered entitlement

EntitlementMeteredV2CreateInputs

type

string · enum · required

Enum values:

metered

object · required

The usage period associated with the entitlement.

Example: {"interval":"DAY","anchor":"2023-01-01T01:01:01.001Z"}

featureKey

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

The feature the subject is entitled to use. Either featureKey or featureId is required.

Example: example-feature-key

featureId

string · pattern: ^[0-7][0-9A-HJKMNP-T…

The feature the subject is entitled to use. Either featureKey or featureId is required.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

object

Additional metadata for the feature.

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

isSoftLimit

boolean

If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true.

Default: false

Defines the time from which usage is measured. If not specified on creation, defaults to entitlement creation time.

preserveOverageAtReset

boolean

If true, the overage is preserved at reset. If false, the usage is reset to 0.

Default: false

object

Issue after reset

EntitlementGrantCreateInputV2[]

Grants

EntitlementV2PaginatedResponse

Paginated response

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

EntitlementV2[] · required

The items in the current page.

EntitlementValue

Entitlements are the core of Zuplo Metering access management. They define access to features for subjects. Entitlements can be metered, boolean, or static.

hasAccess

boolean · readOnly · required

Whether the subject has access to the feature. Shared accross all entitlement types.

Example: true

balance

number · double · readOnly

Only available for metered entitlements. Metered entitlements are built around a balance calculation where feature usage is deducted from the issued grants. Balance represents the remaining balance of the entitlement, it's value never turns negative.

Example: 100

usage

number · double · readOnly

Only available for metered entitlements. Returns the total feature usage in the current period.

Example: 50

overage

number · double · readOnly

Only available for metered entitlements. Overage represents the usage that wasn't covered by grants, e.g. if the subject had a total feature usage of 100 in the period but they were only granted 80, there would be 20 overage.

Example: 0

config

string · readOnly

Only available for static entitlements. The JSON parsable config of the entitlement.

Example: { key: "value" }

ErrorExtension

Generic ErrorExtension as part of HTTPProblem.Extensions.[StatusCode]

field

string · readOnly · required

The path to the field.

Example: addons/pro/ratecards/token/featureKey

code

string · readOnly · required

The machine readable description of the error.

Example: invalid_feature_key

message

string · readOnly · required

The human readable description of the error.

Example: not found feature by key

No data returned

Event

CloudEvents Specification JSON Schema Optional properties are nullable according to the CloudEvents specification: OPTIONAL not omitted attributes MAY be represented as a null JSON value.

id

string · minLength: 1 · required

Identifies the event.

Example: 5c10fade-1c9e-4d6c-8275-c52c36731d3c

source

string · uri-reference · minLength: 1 · required

Identifies the context in which an event happened.

Example: service-name

specversion

string · minLength: 1 · required

The version of the CloudEvents specification which the event uses.

Example: 1.0

Default: 1.0

type

string · minLength: 1 · required

Contains a value describing the type of event related to the originating occurrence.

Example: com.example.someevent

subject

string · minLength: 1 · required

Describes the subject of the event in the context of the event producer (identified by source).

Example: customer-id

subscription

string · minLength: 1 · required

The subscription ID this event belongs to. Required extension field for event attribution to subscriptions.

Example: 01HZXABCD3M6E7K8J9PQRS1TUV

datacontenttype

string | null · enum

Content type of the CloudEvents data value. Only the value "application/json" is allowed over HTTP.

Enum values:

application/json

Example: application/json

dataschema

string | null · uri · minLength: 1

Identifies the schema that data adheres to.

time

string | null · date-time

Timestamp of when the occurrence happened. Must adhere to RFC 3339.

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

object | null

The event payload. Optional, if present it must be a JSON object.

EventDeliveryAttemptResponse

The response of the event delivery attempt.

body

string · readOnly · required

The body of the response.

durationMs

integer · readOnly · required

The duration of the response in milliseconds.

statusCode

integer · readOnly

Status code of the response if available.

url

string · readOnly

URL where the event was sent in case of notification channel with webhook type.

ExpirationDuration

string · enum

Enum values:

HOUR

DAY

WEEK

MONTH

YEAR

The expiration duration enum

ExpirationPeriod

The grant expiration definition

duration

string · enum · required

The unit of time for the expiration period.

Enum values:

HOUR

DAY

WEEK

MONTH

YEAR

count

integer · uint32 · min: 1 · max: 1000 · required

The number of time units in the expiration period.

Example: 12

Feature

Represents a feature that can be enabled or disabled for a plan. Used both for product catalog and entitlements.

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 key is a unique string that is used to identify a resource.

name

string · required

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Readonly unique ULID identifier.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

archivedAt

string · date-time · readOnly

Timestamp of when the resource was archived.

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

object

Set of key-value pairs. Metadata can be used to store additional information about a resource.

Example: {"key":"value"}

meterSlug

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

A key is a unique string that is used to identify a resource.

Example: tokens_total

object

Optional advanced meter group by filters. You can use this to filter for values of the meter groupBy fields.

Example: {"model":{"$in":["gpt-4","gpt-4o"]},"type":{"$eq":"input"}}

FeatureCreateInputs

Represents a feature that can be enabled or disabled for a plan. Used both for product catalog and entitlements.

key

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

A key is a unique string that is used to identify a resource.

name

string · required

object

Set of key-value pairs. Metadata can be used to store additional information about a resource.

Example: {"key":"value"}

meterSlug

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

A key is a unique string that is used to identify a resource.

Example: tokens_total

object

Optional advanced meter group by filters. You can use this to filter for values of the meter groupBy fields.

Example: {"model":{"$in":["gpt-4","gpt-4o"]},"type":{"$eq":"input"}}

FeatureMeta

Limited representation of a feature resource which includes only its unique identifiers (id, key).

id

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Unique identifier of a feature.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

key

string · required

The key is an immutable unique identifier of the feature used throughout the API, for example when interacting with a subject's entitlements.

Example: gpt4_tokens

FeatureOrderBy

string · enum

Enum values:

id

key

name

createdAt

updatedAt

Order by options for features.

FeaturePaginatedResponse

Paginated response

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

Feature[] · required

The items in the current page.

FilterBoolean

A filter for a boolean field.

$eq

boolean | null

The field must be equal to the provided value.

FilterFloat

A filter for a float field.

$eq

number | null · double

The field must be equal to the provided value.

$ne

number | null · double

The field must not be equal to the provided value.

$gt

number | null · double

The field must be greater than the provided value.

$gte

number | null · double

The field must be greater than or equal to the provided value.

$lt

number | null · double

The field must be less than the provided value.

$lte

number | null · double

The field must be less than or equal to the provided value.

array | null

Provide a list of filters to be combined with a logical AND.

array | null

Provide a list of filters to be combined with a logical OR.

FilterIDExact

A filter for a ID (ULID) field allowing only equality or inclusion.

$in

array | null

The field must be in the provided list of values.

FilterInteger

A filter for an integer field.

$eq

integer | null

The field must be equal to the provided value.

$ne

integer | null

The field must not be equal to the provided value.

$gt

integer | null

The field must be greater than the provided value.

$gte

integer | null

The field must be greater than or equal to the provided value.

$lt

integer | null

The field must be less than the provided value.

$lte

integer | null

The field must be less than or equal to the provided value.

array | null

Provide a list of filters to be combined with a logical AND.

array | null

Provide a list of filters to be combined with a logical OR.

FilterString

A filter for a string field.

$eq

string | null

The field must be equal to the provided value.

$ne

string | null

The field must not be equal to the provided value.

$in

array | null

The field must be in the provided list of values.

$nin

array | null

The field must not be in the provided list of values.

$like

string | null

The field must match the provided value.

$nlike

string | null

The field must not match the provided value.

$ilike

string | null

The field must match the provided value, ignoring case.

$nilike

string | null

The field must not match the provided value, ignoring case.

$gt

string | null

The field must be greater than the provided value.

$gte

string | null

The field must be greater than or equal to the provided value.

$lt

string | null

The field must be less than the provided value.

$lte

string | null

The field must be less than or equal to the provided value.

array | null

Provide a list of filters to be combined with a logical AND.

array | null

Provide a list of filters to be combined with a logical OR.

FilterTime

A filter for a time field.

$gt

string | null · date-time

The field must be greater than the provided value.

$gte

string | null · date-time

The field must be greater than or equal to the provided value.

$lt

string | null · date-time

The field must be less than the provided value.

$lte

string | null · date-time

The field must be less than or equal to the provided value.

array | null

Provide a list of filters to be combined with a logical AND.

array | null

Provide a list of filters to be combined with a logical OR.

FlatPrice

Flat price.

type

string · enum · required

The type of the price.

Enum values:

flat

amount

string · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The amount of the flat price.

FlatPriceWithPaymentTerm

Flat price with payment term.

type

string · enum · required

The type of the price.

Enum values:

flat

amount

string · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The amount of the flat price.

paymentTerm

string · enum

The payment term of the flat price. Defaults to in advance.

Enum values:

in_advance

in_arrears

Default: in_advance

ForbiddenProblemResponse

The server understood the request but refuses to authorize it.

type

string · uri · required

Type contains a URI that identifies the problem type.

Example: about:blank

Default: about:blank

title

string · required

A a short, human-readable summary of the problem type.

Example: Bad Request

detail

string · required

A human-readable explanation specific to this occurrence of the problem.

Example: The request body must be a JSON object.

instance

string · uri · required

A URI reference that identifies the specific occurrence of the problem.

Example: urn:request:local/JMOlctsKV8-000001

status

integer · int16 · min: 400 · max: 599

The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 400

object

Additional properties specific to the problem type may be present.

Example: {"validationErrors":[{"code":"validation_error","message":"Validation error"}],"otherAttribute":"otherValue"}

No data returned

GatewayTimeoutProblemResponse

The server, while acting as a gateway or proxy, did not receive a timely response from an upstream server it needed to access in order to complete the request.

type

string · uri · required

Type contains a URI that identifies the problem type.

Example: about:blank

Default: about:blank

title

string · required

A a short, human-readable summary of the problem type.

Example: Bad Request

detail

string · required

A human-readable explanation specific to this occurrence of the problem.

Example: The request body must be a JSON object.

instance

string · uri · required

A URI reference that identifies the specific occurrence of the problem.

Example: urn:request:local/JMOlctsKV8-000001

status

integer · int16 · min: 400 · max: 599

The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 400

object

Additional properties specific to the problem type may be present.

Example: {"validationErrors":[{"code":"validation_error","message":"Validation error"}],"otherAttribute":"otherValue"}

No data returned

GrantBurnDownHistorySegment

A segment of the grant burn down history. A given segment represents the usage of a grant between events that changed either the grant burn down priority order or the usag period.

object · required

The period of the segment.

usage

number · double · readOnly · required

The total usage of the grant in the period.

Example: 100

overage

number · double · readOnly · required

Overuse that wasn't covered by grants.

Example: 100

balanceAtStart

number · double · readOnly · required

entitlement balance at the start of the period.

Example: 100

object · readOnly · required

The balance breakdown of each active grant at the start of the period: GrantID: Balance

Example: {"01G65Z755AFWAKHE12NY0CQ9FH":100}

balanceAtEnd

number · double · readOnly · required

The entitlement balance at the end of the period.

Example: 100

object · readOnly · required

The balance breakdown of each active grant at the end of the period: GrantID: Balance

Example: {"01G65Z755AFWAKHE12NY0CQ9FH":100}

GrantUsageRecord[] · readOnly · required

Which grants were actually burnt down in the period and by what amount.

GrantOrderBy

string · enum

Enum values:

id

createdAt

updatedAt

Order by options for grants.

GrantPaginatedResponse

Paginated response

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

EntitlementGrant[] · required

The items in the current page.

GrantUsageRecord

Usage Record

grantId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The id of the grant

Example: 01G65Z755AFWAKHE12NY0CQ9FH

usage

number · double · required

The usage in the period

Example: 100

GrantV2PaginatedResponse

Paginated response

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

EntitlementGrantV2[] · required

The items in the current page.

IDResource

IDResource is a resouce with an ID.

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

A unique identifier for the resource.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

IngestEventsBody

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = object · requires: id, source, specversion +3 more
	type = array

Properties for Variant 1:

CloudEvents Specification JSON Schema Optional properties are nullable according to the CloudEvents specification: OPTIONAL not omitted attributes MAY be represented as a null JSON value.

Event

id

string · minLength: 1 · required

Identifies the event.

Example: 5c10fade-1c9e-4d6c-8275-c52c36731d3c

source

string · uri-reference · minLength: 1 · required

Identifies the context in which an event happened.

Example: service-name

specversion

string · minLength: 1 · required

The version of the CloudEvents specification which the event uses.

Example: 1.0

Default: 1.0

type

string · minLength: 1 · required

Contains a value describing the type of event related to the originating occurrence.

Example: com.example.someevent

subject

string · minLength: 1 · required

Describes the subject of the event in the context of the event producer (identified by source).

Example: customer-id

subscription

string · minLength: 1 · required

The subscription ID this event belongs to. Required extension field for event attribution to subscriptions.

Example: 01HZXABCD3M6E7K8J9PQRS1TUV

datacontenttype

string | null · enum

Content type of the CloudEvents data value. Only the value "application/json" is allowed over HTTP.

Enum values:

application/json

Example: application/json

dataschema

string | null · uri · minLength: 1

Identifies the schema that data adheres to.

time

string | null · date-time

Timestamp of when the occurrence happened. Must adhere to RFC 3339.

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

object | null

The event payload. Optional, if present it must be a JSON object.

IngestedEvent

An ingested event with optional validation error.

object · required

The original event ingested.

Example: {"id":"5c10fade-1c9e-4d6c-8275-c52c36731d3c","source":"service-name","specversion":"1.0","type":"prompt","subject":"customer-id","time":"2023-01-01T01:01:01.001Z","subscription":"01HZXABCD3M6E7K8J9PQRS1TUV"}

ingestedAt

string · date-time · required

The date and time the event was ingested.

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

storedAt

string · date-time · required

The date and time the event was stored.

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

customerId

string · pattern: ^[0-7][0-9A-HJKMNP-T…

The customer ID if the event is associated with a customer.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

validationError

string

The validation error if the event failed validation.

IngestedEventCursorPaginatedResponse

A response for cursor pagination.

IngestedEvent[] · maxItems: 100 · required

The items in the response.

nextCursor

string

The cursor of the last item in the list.

InstallMethod

string · enum

Enum values:

with_oauth2

with_api_key

no_credentials_required

Install method of the application.

InternalServerErrorProblemResponse

The server encountered an unexpected condition that prevented it from fulfilling the request.

type

string · uri · required

Type contains a URI that identifies the problem type.

Example: about:blank

Default: about:blank

title

string · required

A a short, human-readable summary of the problem type.

Example: Bad Request

detail

string · required

A human-readable explanation specific to this occurrence of the problem.

Example: The request body must be a JSON object.

instance

string · uri · required

A URI reference that identifies the specific occurrence of the problem.

Example: urn:request:local/JMOlctsKV8-000001

status

integer · int16 · min: 400 · max: 599

The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 400

object

Additional properties specific to the problem type may be present.

Example: {"validationErrors":[{"code":"validation_error","message":"Validation error"}],"otherAttribute":"otherValue"}

No data returned

Invoice

Invoice represents an invoice in the system.

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

A unique identifier for the resource.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

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

type

string · enum · readOnly · required

Type of the invoice.

The type of invoice determines the purpose of the invoice and how it should be handled.

Supported types:

standard: A regular commercial invoice document between a supplier and customer.
credit_note: Reflects a refund either partial or complete of the preceding document. A credit note effectively extends the previous document.

Enum values:

standard

credit_note

object · required

The taxable entity supplying the goods or services.

object · required

Legal entity receiving the goods or services.

number

string · minLength: 1 · maxLength: 256 · readOnly · required

Number specifies the human readable key used to reference this Invoice.

The invoice number can change in the draft phases, as we are allocating temporary draft invoice numbers, but it's final as soon as the invoice gets finalized (issued state).

Please note that the number is (depending on the upstream settings) either unique for the whole organization or unique for the customer, or in multi (stripe) account setups unique for the account.

Example: INV-2024-01-01-01

currency

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

Currency for all invoice line items.

Multi currency invoices are not supported yet.

Example: USD

object · readOnly · required

Summary of all the invoice totals, including taxes (calculated).

status

string · enum · readOnly · required

The status of the invoice.

This field only conatins a simplified status, for more detailed information use the statusDetails field.

Enum values:

gathering

draft

issuing

issued

payment_processing

overdue

paid

uncollectible

object · readOnly · required

The details of the current invoice status.

object · required

The workflow associated with the invoice.

It is always a snapshot of the workflow settings at the time of invoice creation. The field is optional as it should be explicitly requested with expand options.

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

InvoiceDocumentRef[] · readOnly

Key information regarding previous invoices and potentially details as to why they were corrected.

issuedAt

string · date-time · readOnly

The time the invoice was issued.

Depending on the status of the invoice this can mean multiple things:

draft, gathering: The time the invoice will be issued based on the workflow settings.
issued: The time the invoice was issued.

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

draftUntil

string · date-time

The time until the invoice is in draft status.

On draft invoice creation it is calculated from the workflow settings.

If manual approval is required, the draftUntil time is set.

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

quantitySnapshotedAt

string · date-time · readOnly

The time when the quantity snapshots on the invoice lines were taken.

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

collectionAt

string · date-time · readOnly

The time when the invoice will be/has been collected.

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

dueAt

string · date-time · readOnly

Due time of the fulfillment of the invoice (if available).

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

object

The period the invoice covers. If the invoice has no line items, it's not set.

voidedAt

string · date-time · readOnly

The time the invoice was voided.

If the invoice was voided, this field will be set to the time the invoice was voided.

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

sentToCustomerAt

string · date-time · readOnly

The time the invoice was sent to customer.

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

InvoiceLine[]

List of invoice lines representing each of the items sold to the customer.

object · readOnly

Information on when, how, and to whom the invoice should be paid.

ValidationIssue[] · readOnly

Validation issues reported by the invoice workflow.

object · readOnly

External IDs of the invoice in other apps such as Stripe.

InvoiceAppExternalIds

InvoiceAppExternalIds contains the external IDs of the invoice in other apps such as Stripe.

invoicing

string · readOnly

The external ID of the invoice in the invoicing app if available.

tax

string · readOnly

The external ID of the invoice in the tax app if available.

payment

string · readOnly

The external ID of the invoice in the payment app if available.

InvoiceAvailableActionDetails

InvoiceAvailableActionInvoiceDetails represents the details of the invoice action for non-gathering invoices.

resultingState

string · readOnly · required

The state the invoice will reach if the action is activated and all intermediate steps are successful.

For example advancing a draft_created invoice will result in a draft_manual_approval_needed invoice.

InvoiceAvailableActionInvoiceDetails

InvoiceAvailableActionInvoiceDetails represents the details of the invoice action for gathering invoices.

InvoiceAvailableActions

InvoiceAvailableActions represents the actions that can be performed on the invoice.

object · readOnly

Advance the invoice to the next status.

object · readOnly

Approve an invoice that requires manual approval.

object · readOnly

Delete the invoice (only non-issued invoices can be deleted).

object · readOnly

Retry an invoice issuing step that failed.

object · readOnly

Snapshot quantities for usage based line items.

object · readOnly

Void an already issued invoice.

invoice

object · readOnly

Invoice a gathering invoice

InvoiceDetailedLine

InvoiceDetailedLine represents a line item that is sold to the customer as a manually added fee.

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

id

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

ID of the line.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

managedBy

string · enum · readOnly · required

managedBy specifies if the line is manually added via the api or managed by Zuplo Metering.

Enum values:

subscription

system

manual

status

string · enum · readOnly · required

Status of the line.

External calls always create valid lines, other line types are managed by the billing engine of Zuplo Metering.

Enum values:

valid

detailed

split

currency

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

The currency of this line.

Example: USD

object · readOnly · required

Totals for this line.

object · required

Period of the line item applies to for revenue recognition pruposes.

Billing always treats periods as start being inclusive and end being exclusive.

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 · readOnly

Discounts detailes applied to this line.

New discounts can be added via the invoice's discounts API, to facilitate discounts that are affecting multiple lines.

object

The invoice this item belongs to.

InvoiceLineTaxItem[] · readOnly

Taxes applied to the invoice totals.

object · readOnly

External IDs of the invoice in other apps such as Stripe.

object · readOnly

Subscription are the references to the subscritpions that this line is related to.

object

The rate card that is used for this line.

category

string · enum · readOnly

Category of the flat fee.

Enum values:

regular

commitment

Default: regular

InvoiceDetailedLineCostCategory

string · enum

Enum values:

regular

commitment

InvoiceDetailedLineCostCategory determines if the flat fee is a regular fee due to use due to a commitment.

InvoiceDetailedLineRateCard

InvoiceDetailedLineRateCard represents the rate card (intent) for a flat fee line.

price

object | null · required

The price of the rate card. When null, the feature or service is free.

Example: {"type":"flat","amount":"100","paymentTerm":"in_arrears"}

object

The tax config of the rate card. When undefined, the tax config of the feature or the default tax config of the plan is used.

quantity

string · pattern: ^\-?[0-9]+(\.[0-9]+)…

Quantity of the item being sold.

Default: 1

object

The discounts that are applied to the line.

InvoiceDiscountBase

InvoiceDiscountBase represents a charge or discount that can be applied to a line or the entire invoice.

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

ID of the charge or discount.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

object · readOnly · required

Reason code.

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

description

string · readOnly

Text description as to why the discount was applied.

object · readOnly

External IDs of the invoice in other apps such as Stripe.

InvoiceDocumentRef

InvoiceDocumentRef is used to describe a reference to an existing document (invoice).

type

string · enum · readOnly · required

Type of the invoice.

Enum values:

credit_note_original_invoice

url

string · uri · readOnly · required

Link to the source document.

issuedAt

string · date-time · readOnly

IssueAt reflects the time the document was issued.

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

number

string · minLength: 1 · maxLength: 256 · readOnly

(Serial) Number of the referenced document.

Example: INV-2024-01-01-01

reason

string · readOnly

Human readable description on why this reference is here or needs to be used.

description

string · readOnly

Additional details about the document.

InvoiceDocumentRefType

string · enum

Enum values:

credit_note_original_invoice

InvoiceDocumentRefType defines the type of document that is being referenced.

InvoiceExpand

string · enum

Enum values:

lines

preceding

workflow.apps

InvoiceExpand specifies the parts of the invoice to expand in the list output.

InvoiceGenericDocumentRef

Omitted fields: period: Tax period in which the referred document had an effect required by some tax regimes and formats. stamps: Seals of approval from other organisations that may need to be listed. ext: Extensions for additional codes that may be required.

type

string · enum · readOnly · required

Type of the document referenced.

Enum values:

credit_note_original_invoice

reason

string · readOnly

Human readable description on why this reference is here or needs to be used.

description

string · readOnly

Additional details about the document.

InvoiceLine

InvoiceUsageBasedLine represents a line item that is sold to the customer based on usage.

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

id

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

ID of the line.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

managedBy

string · enum · readOnly · required

managedBy specifies if the line is manually added via the api or managed by Zuplo Metering.

Enum values:

subscription

system

manual

status

string · enum · readOnly · required

Status of the line.

External calls always create valid lines, other line types are managed by the billing engine of Zuplo Metering.

Enum values:

valid

detailed

split

currency

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

The currency of this line.

Example: USD

object · readOnly · required

Totals for this line.

object · required

Period of the line item applies to for revenue recognition pruposes.

Billing always treats periods as start being inclusive and end being exclusive.

invoiceAt

string · date-time · required

The time this line item should be invoiced.

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

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 · readOnly

Discounts detailes applied to this line.

New discounts can be added via the invoice's discounts API, to facilitate discounts that are affecting multiple lines.

object

The invoice this item belongs to.

InvoiceLineTaxItem[] · readOnly

Taxes applied to the invoice totals.

object · readOnly

External IDs of the invoice in other apps such as Stripe.

object · readOnly

Subscription are the references to the subscritpions that this line is related to.

InvoiceDetailedLine[] · readOnly

The lines detailing the item or service sold.

object

The rate card that is used for this line.

The rate card captures the intent of the price and discounts for the usage-based item.

quantity

string · readOnly · pattern: ^\-?[0-9]+(\.[0-9]+)…

The quantity of the item being sold.

Any usage discounts applied previously are deducted from this quantity.

meteredQuantity

string · readOnly · pattern: ^\-?[0-9]+(\.[0-9]+)…

The quantity of the item that has been metered for the period before any discounts were applied.

preLinePeriodQuantity

string · readOnly · pattern: ^\-?[0-9]+(\.[0-9]+)…

The quantity of the item used before this line's period.

It is non-zero in case of progressive billing, when this shows how much of the usage was already billed.

Any usage discounts applied previously are deducted from this quantity.

meteredPreLinePeriodQuantity

string · readOnly · pattern: ^\-?[0-9]+(\.[0-9]+)…

The metered quantity of the item used in before this line's period without any discounts applied.

It is non-zero in case of progressive billing, when this shows how much of the usage was already billed.

InvoiceLineAmountDiscount

InvoiceLineAmountDiscount represents an amount deducted from the line, and will be applied before taxes.

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

ID of the charge or discount.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

object · readOnly · required

Reason code.

amount

string · readOnly · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

Fixed discount amount to apply (calculated if percent present).

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

description

string · readOnly

Text description as to why the discount was applied.

object · readOnly

External IDs of the invoice in other apps such as Stripe.

InvoiceLineAppExternalIds

InvoiceLineAppExternalIds contains the external IDs of the invoice in other apps such as Stripe.

invoicing

string · readOnly

The external ID of the invoice in the invoicing app if available.

tax

string · readOnly

The external ID of the invoice in the tax app if available.

InvoiceLineBase

InvoiceLine represents a single item or service sold to the customer. This is a base class for all line types, and should not be used directly.

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

id

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

ID of the line.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

managedBy

string · enum · readOnly · required

managedBy specifies if the line is manually added via the api or managed by Zuplo Metering.

Enum values:

subscription

system

manual

status

string · enum · readOnly · required

Status of the line.

External calls always create valid lines, other line types are managed by the billing engine of Zuplo Metering.

Enum values:

valid

detailed

split

currency

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

The currency of this line.

Example: USD

object · readOnly · required

Totals for this line.

object · required

Period of the line item applies to for revenue recognition pruposes.

Billing always treats periods as start being inclusive and end being exclusive.

invoiceAt

string · date-time · required

The time this line item should be invoiced.

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

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 · readOnly

Discounts detailes applied to this line.

New discounts can be added via the invoice's discounts API, to facilitate discounts that are affecting multiple lines.

object

The invoice this item belongs to.

InvoiceLineTaxItem[] · readOnly

Taxes applied to the invoice totals.

object · readOnly

External IDs of the invoice in other apps such as Stripe.

object · readOnly

Subscription are the references to the subscritpions that this line is related to.

InvoiceLineDiscounts

InvoiceLineDiscounts represents the discounts applied to the invoice line by type.

InvoiceLineAmountDiscount[]

Amount based discounts applied to the line.

Amount based discounts are deduced from the total price of the line.

InvoiceLineUsageDiscount[]

Usage based discounts applied to the line.

Usage based discounts are deduced from the usage of the line before price calculations are applied.

InvoiceLineManagedBy

string · enum

Enum values:

subscription

system

manual

InvoiceLineManagedBy specifies who manages the line.

InvoiceLineReplaceUpdate

InvoiceLineReplaceUpdate represents the update model for an UBP invoice line. This type makes ID optional to allow for creating new lines as part of the update.

name

string · minLength: 1 · maxLength: 256 · required

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

object · required

Period of the line item applies to for revenue recognition pruposes.

Billing always treats periods as start being inclusive and end being exclusive.

invoiceAt

string · date-time · required

The time this line item should be invoiced.

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

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

The rate card that is used for this line.

The rate card captures the intent of the price and discounts for the usage-based item.

id

string · pattern: ^[0-7][0-9A-HJKMNP-T…

The ID of the line.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

InvoiceLineStatus

string · enum

Enum values:

valid

detailed

split

Line status specifies the status of the line.

InvoiceLineSubscriptionReference

InvoiceLineSubscriptionReference contains the references to the subscription that this line is related to.

object · readOnly · required

The subscription.

object · readOnly · required

The phase of the subscription.

object · readOnly · required

The item this line is related to.

object · readOnly · required

The billing period of the subscription. In case the subscription item's billing period is different from the subscription's billing period, this field will contain the billing period of the subscription itself.

For example, in case of:

A monthly billed subscription anchored to 2025-01-01
A subscription item billed daily

An example line would have the period of 2025-01-02 to 2025-01-03 as the item is billed daily, but the subscription's billing period will be 2025-01-01 to 2025-01-31.

InvoiceLineTaxBehavior

string · enum

Enum values:

inclusive

exclusive

InvoiceLineTaxBehavior details how the tax item is applied to the base amount.

Inclusive means the tax is included in the base amount. Exclusive means the tax is added to the base amount.

InvoiceLineTaxItem

TaxConfig stores the configuration for a tax line relative to an invoice line.

object · readOnly

Tax provider configuration.

percent

number · double · readOnly

Percent defines the percentage set manually or determined from the rate key (calculated if rate present). A nil percent implies that this tax combo is exempt from tax.")

Example: 50

surcharge

string · readOnly · pattern: ^\-?[0-9]+(\.[0-9]+)…

Some countries require an additional surcharge (calculated if rate present).

behavior

string · enum · readOnly

Is the tax item inclusive or exclusive of the base amount.

Enum values:

inclusive

exclusive

InvoiceLineTypes

string · enum · deprecated

Enum values:

flat_fee

usage_based

LineTypes represents the different types of lines that can be used in an invoice.

InvoiceLineUsageDiscount

InvoiceLineUsageDiscount represents an usage-based discount applied to the line. The deduction is done before the pricing algorithm is applied.

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

ID of the charge or discount.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

object · readOnly · required

Reason code.

quantity

string · readOnly · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The usage to apply.

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

description

string · readOnly

Text description as to why the discount was applied.

object · readOnly

External IDs of the invoice in other apps such as Stripe.

preLinePeriodQuantity

string · readOnly · pattern: ^\-?[0-9]+(\.[0-9]+)…

The usage discount already applied to the previous split lines.

Only set if progressive billing is enabled and the line is a split line.

InvoiceNumber

string · minLength: 1 · maxLength: 256

InvoiceNumber is a unique identifier for the invoice, generated by the invoicing app.

The uniqueness depends on a lot of factors:

app setting (unique per app or unique per customer)
multiple app scenarios (multiple apps generating invoices with the same prefix)

Example: INV-2024-01-01-01

InvoiceOrderBy

string · enum

Enum values:

customer.name

issuedAt

status

createdAt

updatedAt

periodStart

InvoiceOrderBy specifies the ordering options for invoice listing.

InvoicePaginatedResponse

Paginated response

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

Invoice[] · required

The items in the current page.

InvoicePaymentTerms

Payment contains details as to how the invoice should be paid.

The terms of payment for the invoice.

InvoicePendingLineCreate

InvoicePendingLineCreate represents the create model for an invoice line that is sold to the customer based on usage.

name

string · minLength: 1 · maxLength: 256 · required

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

object · required

Period of the line item applies to for revenue recognition pruposes.

Billing always treats periods as start being inclusive and end being exclusive.

invoiceAt

string · date-time · required

The time this line item should be invoiced.

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

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

The rate card that is used for this line.

The rate card captures the intent of the price and discounts for the usage-based item.

InvoicePendingLineCreateInput

InvoicePendingLineCreate represents the create model for a pending invoice line.

currency

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

The currency of the lines to be created.

Example: USD

InvoicePendingLineCreate[] · minItems: 1 · required

The lines to be created.

InvoicePendingLineCreateResponse

InvoicePendingLineCreateResponse represents the response from the create pending line endpoint.

InvoiceLine[] · readOnly · required

The lines that were created.

object · readOnly · required

The invoice containing the created lines.

isInvoiceNew

boolean · readOnly · required

Whether the invoice was newly created.

InvoicePendingLinesActionFiltersInput

InvoicePendingLinesActionFiltersInput specifies which lines to include in the invoice.

lineIds

string[]

The pending line items to include in the invoice, if not provided:

all line items that have invoice_at < asOf will be included
[progressive billing only] all usage based line items will be included up to asOf, new usage-based line items will be staged for the rest of the billing cycle

All lineIDs present in the list, must exists and must be invoicable as of asOf, or the action will fail.

InvoicePendingLinesActionInput

BillingInvoiceActionInput is the input for creating an invoice. Invoice creation is always based on already pending line items created by the billingCreateLineByCustomer operation. Empty invoices are not allowed.

customerId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The customer ID for which to create the invoice.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

object

Filters to apply when creating the invoice.

asOf

string · date-time

The time as of which the invoice is created.

If not provided, the current time is used.

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

progressiveBillingOverride

boolean

Override the progressive billing setting of the customer.

Can be used to disable/enable progressive billing in case the business logic requires it, if not provided the billing profile's progressive billing setting will be used.

InvoiceReference

Reference to an invoice.

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The ID of the invoice.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

number

string · minLength: 1 · maxLength: 256 · readOnly

The number of the invoice.

Example: INV-2024-01-01-01

InvoiceReplaceUpdate

InvoiceReplaceUpdate represents the update model for an invoice.

object · required

The supplier of the lines included in the invoice.

object · required

The customer the invoice is sent to.

InvoiceLineReplaceUpdate[] · required

The lines included in the invoice.

object · required

The workflow settings for the invoice.

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

InvoiceSimulationInput

InvoiceSimulationInput is the input for simulating an invoice.

currency

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

Currency for all invoice line items.

Multi currency invoices are not supported yet.

Example: USD

InvoiceSimulationLine[] · required

Lines to be included in the generated invoice.

number

string · minLength: 1 · maxLength: 256

The number of the invoice.

Example: INV-2024-01-01-01

InvoiceSimulationLine

InvoiceSimulationLine represents a usage-based line item that can be input to the simulation endpoint.

name

string · minLength: 1 · maxLength: 256 · required

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

object · required

Period of the line item applies to for revenue recognition pruposes.

Billing always treats periods as start being inclusive and end being exclusive.

invoiceAt

string · date-time · required

The time this line item should be invoiced.

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

quantity

string · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The quantity of the item being sold.

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

The rate card that is used for this line.

The rate card captures the intent of the price and discounts for the usage-based item.

preLinePeriodQuantity

string · pattern: ^\-?[0-9]+(\.[0-9]+)…

The quantity of the item used before this line's period, if the line is billed progressively.

id

string · pattern: ^[0-7][0-9A-HJKMNP-T…

ID of the line. If not specified it will be auto-generated.

When discounts are specified, this must be provided, so that the discount can reference it.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

InvoiceStatus

string · enum

Enum values:

gathering

draft

issuing

issued

payment_processing

overdue

paid

uncollectible

InvoiceStatus describes the status of an invoice.

InvoiceStatusDetails

InvoiceStatusDetails represents the details of the invoice status. API users are encouraged to rely on the immutable/failed/avaliableActions fields to determine the next steps of the invoice instead of the extendedStatus field.

immutable

boolean · readOnly · required

Is the invoice editable?

failed

boolean · readOnly · required

Is the invoice in a failed state?

extendedStatus

string · readOnly · required

Extended status information for the invoice.

object · required

The actions that can be performed on the invoice.

InvoiceTotals

Totals contains the summaries of all calculations for the invoice.

amount

string · readOnly · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The total value of the line before taxes, discounts and commitments.

chargesTotal

string · readOnly · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The amount of value of the line that are due to additional charges.

discountsTotal

string · readOnly · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The amount of value of the line that are due to discounts.

taxesInclusiveTotal

string · readOnly · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The total amount of taxes that are included in the line.

taxesExclusiveTotal

string · readOnly · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The total amount of taxes that are added on top of amount from the line.

taxesTotal

string · readOnly · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The total amount of taxes for this line.

total

string · readOnly · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The total amount value of the line after taxes, discounts and commitments.

InvoiceType

string · enum

Enum values:

standard

credit_note

InvoiceType represents the type of invoice.

The type of invoice determines the purpose of the invoice and how it should be handled.

InvoiceUsageBasedRateCard

InvoiceUsageBasedRateCard represents the rate card (intent) for an usage-based line.

object · required

The price of the rate card. When null, the feature or service is free.

featureKey

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

The feature the customer is entitled to use.

object

The tax config of the rate card. When undefined, the tax config of the feature or the default tax config of the plan is used.

object

The discounts that are applied to the line.

InvoiceWorkflowInvoicingSettingsReplaceUpdate

InvoiceWorkflowInvoicingSettingsReplaceUpdate represents the update model for the invoicing settings of an invoice workflow.

autoAdvance

boolean

Whether to automatically issue the invoice after the draftPeriod has passed.

Default: true

draftPeriod

string · ISO8601

The period for the invoice to be kept in draft status for manual reviews.

Example: P1D

Default: P0D

dueAfter

string · ISO8601

The period after which the invoice is due. With some payment solutions it's only applicable for manual collection method.

Example: P30D

Default: P30D

object

Default tax configuration to apply to the invoices.

InvoiceWorkflowReplaceUpdate

InvoiceWorkflowReplaceUpdate represents the update model for an invoice workflow. Fields that are immutable a re removed from the model. This is based on InvoiceWorkflowSettings.

object · required

The workflow used for this invoice.

InvoiceWorkflowSettings

InvoiceWorkflowSettings represents the workflow settings used by the invoice. This is a clone of the billing profile's workflow settings at the time of invoice creation with customer overrides considered.

sourceBillingProfileId

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

sourceBillingProfileID is the billing profile on which the workflow was based on.

The profile is snapshotted on invoice creation, after which it can be altered independently of the profile itself.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

object · required

The workflow details used by this invoice.

readOnly

The apps that will be used to orchestrate the invoice's workflow.

InvoiceWorkflowSettingsReplaceUpdate

Mutable workflow settings for an invoice. Other fields on the invoice's workflow are not mutable, they serve as a history of the invoice's workflow at creation time.

object · required

The invoicing settings for this workflow

object · required

The payment settings for this workflow

IssueAfterReset

Issue after reset

amount

number · double · min: 0 · required

The initial grant amount

priority

integer · uint8 · min: 1 · max: 255

The priority of the issue after reset

Default: 1

ListAppsRequest

Query params for listing installed apps

page

integer · min: 1

Page index.

Default is 1.

Example: 1

Default: 1

pageSize

integer · min: 1 · max: 1000

The maximum number of items per page.

Default is 100.

Example: 100

Default: 100

ListEntitlementsResult

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = array
	type = object · requires: totalCount, page, pageSize +1 more

Properties for Variant 1:

Entitlement[]

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · type="metered" · requires: createdAt, updatedAt, activeFrom +8 more
	type = object · type="static" · requires: config, createdAt, updatedAt +5 more
	type = object · type="boolean" · requires: createdAt, updatedAt, activeFrom +4 more

Properties for Variant 1:

Metered entitlements are useful for many different use cases, from setting up usage based access to implementing complex credit systems. Access is determined based on feature usage using a balance calculation (the "usage allowance" provided by the issued grants is "burnt down" by the usage).

EntitlementMetered

type

string · enum · required

Enum values:

metered

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

activeFrom

string · date-time · required

The cadence start of the resource.

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Readonly unique ULID identifier.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

subjectKey

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

The identifier key unique to the subject. NOTE: Subjects are being deprecated, please use the new customer APIs.

Example: customer-1

featureKey

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

The feature the subject is entitled to use.

Example: example-feature-key

featureId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The feature the subject is entitled to use.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

lastReset

string · date-time · readOnly · required

The time the last reset happened.

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

object · readOnly · required

The current usage period.

measureUsageFrom

string · date-time · readOnly · required

The time from which usage is measured. If not specified on creation, defaults to entitlement creation time.

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

isSoftLimit

boolean

If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true.

Default: false

issueAfterReset

number · double · min: 0

You can grant usage automatically alongside the entitlement, the example scenario would be creating a starting balance. If an amount is specified here, a grant will be created alongside the entitlement with the specified amount. That grant will have it's rollover settings configured in a way that after each reset operation, the balance will return the original amount specified here. Manually creating such a grant would mean having the "amount", "minRolloverAmount", and "maxRolloverAmount" fields all be the same.

issueAfterResetPriority

integer · uint8 · min: 1 · max: 255

Defines the grant priority for the default grant.

Default: 1

preserveOverageAtReset

boolean

If true, the overage is preserved at reset. If false, the usage is reset to 0.

Default: false

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

object

Additional metadata for the feature.

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

activeTo

string · date-time

The cadence end of the resource.

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

object · readOnly

The annotations of the entitlement.

Example: {"subscription.id":"sub_123"}

ListFeaturesResult

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = array
	type = object · requires: totalCount, page, pageSize +1 more

Properties for Variant 1:

Feature[]

Represents a feature that can be enabled or disabled for a plan. Used both for product catalog and entitlements.

Feature

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 key is a unique string that is used to identify a resource.

name

string · required

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Readonly unique ULID identifier.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

archivedAt

string · date-time · readOnly

Timestamp of when the resource was archived.

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

object

Set of key-value pairs. Metadata can be used to store additional information about a resource.

Example: {"key":"value"}

meterSlug

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

A key is a unique string that is used to identify a resource.

Example: tokens_total

object

Optional advanced meter group by filters. You can use this to filter for values of the meter groupBy fields.

Example: {"model":{"$in":["gpt-4","gpt-4o"]},"type":{"$eq":"input"}}

MarketplaceInstallRequestPayload

Marketplace install request payload.

name

string

Name of the application to install.

If name is not provided defaults to the marketplace listing's name.

createBillingProfile

boolean

If true, a billing profile will be created for the app. The Stripe app will be also set as the default billing profile if the current default is a Sandbox app.

Default: true

MarketplaceInstallResponse

Marketplace install response.

App · required

App. One of: stripe

defaultForCapabilityTypes

AppCapabilityType[] · required

Default for capabilities

Enum values:

reportUsage

reportEvents

calculateTax

invoiceCustomers

collectPayments

MarketplaceListing

A marketplace listing. Represent an available app in the app marketplace that can be installed to the organization. Marketplace apps only exist in config so they don't extend the Resource model.

type

string · enum · required

The app's type

Enum values:

stripe

sandbox

custom_invoicing

name

string · required

The app's name.

description

string · required

The app's description.

AppCapability[] · required

The app's capabilities.

installMethods

InstallMethod[] · required

Install methods.

List of methods to install the app.

Enum values:

with_oauth2

with_api_key

no_credentials_required

MarketplaceListingPaginatedResponse

Paginated response

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

MarketplaceListing[] · required

The items in the current page.

MeasureUsageFrom

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string

Properties for Variant 1:

MeasureUsageFromPreset · enum

Enum values:

CURRENT_PERIOD_START

NOW

Start of measurement options

MeasureUsageFromPreset

string · enum

Enum values:

CURRENT_PERIOD_START

NOW

Start of measurement options

MeasureUsageFromTime

string · date-time

RFC3339 formatted date-time string in UTC.

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

Metadata

Set of key-value pairs. Metadata can be used to store additional information about a resource.

string

Meter

A meter is a configuration that defines how to match and aggregate events.

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

A unique identifier for the resource.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

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

slug

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

A unique, human-readable identifier for the meter. Must consist only alphanumeric and underscore characters.

Example: tokens_total

aggregation

string · enum · required

The aggregation type to use for the meter.

Enum values:

SUM

COUNT

UNIQUE_COUNT

AVG

MIN

MAX

LATEST

Example: SUM

eventType

string · minLength: 1 · required

The event type to aggregate.

Example: prompt

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

name

string · minLength: 1 · maxLength: 256

Human-readable name for the resource. Between 1 and 256 characters. Defaults to the slug if not specified.

eventFrom

string · date-time

The date since the meter should include events. Useful to skip old events. If not specified, all historical events are included.

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

valueProperty

string · minLength: 1

JSONPath expression to extract the value from the ingested event's data property.

The ingested value for SUM, AVG, MIN, and MAX aggregations is a number or a string that can be parsed to a number.

For UNIQUE_COUNT aggregation, the ingested value must be a string. For COUNT aggregation the valueProperty is ignored.

Example: $.tokens

object

Named JSONPath expressions to extract the group by values from the event data.

Keys must be unique and consist only alphanumeric and underscore characters.

Example: {"type":"$.type"}

MeterAggregation

string · enum

Enum values:

SUM

COUNT

UNIQUE_COUNT

AVG

MIN

MAX

LATEST

The aggregation type to use for the meter.

MeterCreate

A meter create model.

slug

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

A unique, human-readable identifier for the meter. Must consist only alphanumeric and underscore characters.

Example: tokens_total

aggregation

string · enum · required

The aggregation type to use for the meter.

Enum values:

SUM

COUNT

UNIQUE_COUNT

AVG

MIN

MAX

LATEST

Example: SUM

eventType

string · minLength: 1 · required

The event type to aggregate.

Example: prompt

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

name

string · minLength: 1 · maxLength: 256

Human-readable name for the resource. Between 1 and 256 characters. Defaults to the slug if not specified.

eventFrom

string · date-time

The date since the meter should include events. Useful to skip old events. If not specified, all historical events are included.

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

valueProperty

string · minLength: 1

JSONPath expression to extract the value from the ingested event's data property.

The ingested value for SUM, AVG, MIN, and MAX aggregations is a number or a string that can be parsed to a number.

For UNIQUE_COUNT aggregation, the ingested value must be a string. For COUNT aggregation the valueProperty is ignored.

Example: $.tokens

object

Named JSONPath expressions to extract the group by values from the event data.

Keys must be unique and consist only alphanumeric and underscore characters.

Example: {"type":"$.type"}

MeterOrderBy

string · enum

Enum values:

key

name

aggregation

createdAt

updatedAt

Order by options for meters.

MeterQueryRequest

A meter query request.

clientId

string · minLength: 1 · maxLength: 36

Client ID Useful to track progress of a query.

Example: f74e58ed-94ce-4041-ae06-cf45420451a3

from

string · date-time

Start date-time in RFC 3339 format.

Inclusive.

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

to

string · date-time

End date-time in RFC 3339 format.

Inclusive.

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

windowSize

string · enum

If not specified, a single usage aggregate will be returned for the entirety of the specified period for each subject and group.

Enum values:

MINUTE

HOUR

DAY

MONTH

Example: DAY

windowTimeZone

string

The value is the name of the time zone as defined in the IANA Time Zone Database (http://www.iana.org/time-zones). If not specified, the UTC timezone will be used.

Example: UTC

Default: UTC

subject

string[] · maxItems: 100

Filtering by multiple subjects.

Example: {"0":"subject-1","1":"subject-2"}

filterCustomerId

string[] · maxItems: 100

Filtering by multiple customers.

Example: {"0":"id-1","1":"id-2"}

filterSubscription

string[] · maxItems: 100

Filtering by multiple subscriptions.

Example: {"0":"subscription-1","1":"subscription-2"}

object

Simple filter for group bys with exact match.

Example: {"model":["gpt-4-turbo","gpt-4o"],"type":["prompt"]}

object

Optional advanced meter group by filters. You can use this to filter for values of the meter groupBy fields.

Example: {"model":{"$in":["gpt-4","gpt-4o"]},"type":{"$eq":"input"}}

groupBy

string[] · maxItems: 100

If not specified a single aggregate will be returned for each subject and time window. subject is a reserved group by value.

Example: {"0":"model","1":"type"}

MeterQueryResult

The result of a meter query.

MeterQueryRow[] · required

The usage data. If no data is available, an empty array is returned.

from

string · date-time

The start of the period the usage is queried from. If not specified, the usage is queried from the beginning of time.

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

to

string · date-time

The end of the period the usage is queried to. If not specified, the usage is queried up to the current time.

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

windowSize

string · enum

The window size that the usage is aggregated. If not specified, the usage is aggregated over the entire period.

Enum values:

MINUTE

HOUR

DAY

MONTH

MeterQueryRow

A row in the result of a meter query.

value

number · double · required

The aggregated value.

windowStart

string · date-time · required

The start of the window the value is aggregated over.

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

windowEnd

string · date-time · required

The end of the window the value is aggregated over.

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

subject

string | null · required

The subject the value is aggregated over. If not specified, the value is aggregated over all subjects.

object · required

The group by values the value is aggregated over.

customerId

string

The customer ID the value is aggregated over.

MeterUpdate

A meter update model. Only the properties that can be updated are included. For example, the slug and aggregation cannot be updated.

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

name

string · minLength: 1 · maxLength: 256

Human-readable name for the resource. Between 1 and 256 characters. Defaults to the slug if not specified.

object

Named JSONPath expressions to extract the group by values from the event data.

Keys must be unique and consist only alphanumeric and underscore characters.

Example: {"type":"$.type"}

NotFoundProblemResponse

The origin server did not find a current representation for the target resource or is not willing to disclose that one exists.

type

string · uri · required

Type contains a URI that identifies the problem type.

Example: about:blank

Default: about:blank

title

string · required

A a short, human-readable summary of the problem type.

Example: Bad Request

detail

string · required

A human-readable explanation specific to this occurrence of the problem.

Example: The request body must be a JSON object.

instance

string · uri · required

A URI reference that identifies the specific occurrence of the problem.

Example: urn:request:local/JMOlctsKV8-000001

status

integer · int16 · min: 400 · max: 599

The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 400

object

Additional properties specific to the problem type may be present.

Example: {"validationErrors":[{"code":"validation_error","message":"Validation error"}],"otherAttribute":"otherValue"}

No data returned

NotImplementedProblemResponse

The server does not support the functionality required to fulfill the request.

type

string · uri · required

Type contains a URI that identifies the problem type.

Example: about:blank

Default: about:blank

title

string · required

A a short, human-readable summary of the problem type.

Example: Bad Request

detail

string · required

A human-readable explanation specific to this occurrence of the problem.

Example: The request body must be a JSON object.

instance

string · uri · required

A URI reference that identifies the specific occurrence of the problem.

Example: urn:request:local/JMOlctsKV8-000001

status

integer · int16 · min: 400 · max: 599

The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 400

object

Additional properties specific to the problem type may be present.

Example: {"validationErrors":[{"code":"validation_error","message":"Validation error"}],"otherAttribute":"otherValue"}

No data returned

NotificationChannel

Notification channel.

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Identifies the notification channel.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

type

string · enum · required

Notification channel type.

Enum values:

WEBHOOK

name

string · minLength: 1 · maxLength: 256 · required

User friendly name of the channel.

Example: customer-webhook

url

string · required

Webhook URL where the notification is sent.

Example: https://example.com/webhook

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

disabled

boolean

Whether the channel is disabled or not.

Example: true

Default: false

object · readOnly

Set of key-value pairs managed by the system. Cannot be modified by user.

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

object | null

Additional metadata for the resource.

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

object

Custom HTTP headers sent as part of the webhook request.

signingSecret

string · pattern: ^(whsec_)?[a-zA-Z0-9…

Signing secret used for webhook request validation on the receiving end.

Format: base64 encoded random bytes optionally prefixed with whsec_. Recommended size: 24

Example: whsec_S6g2HLnTwd9AhHwUIMFggVS9OfoPafN8

NotificationChannelCreateRequest

Union type for requests creating new notification channel with certain type.

type

string · enum · required

Notification channel type.

Enum values:

WEBHOOK

name

string · minLength: 1 · maxLength: 256 · required

User friendly name of the channel.

Example: customer-webhook

url

string · required

Webhook URL where the notification is sent.

Example: https://example.com/webhook

disabled

boolean

Whether the channel is disabled or not.

Example: true

Default: false

object | null

Additional metadata for the resource.

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

object

Custom HTTP headers sent as part of the webhook request.

signingSecret

string · pattern: ^(whsec_)?[a-zA-Z0-9…

Signing secret used for webhook request validation on the receiving end.

Format: base64 encoded random bytes optionally prefixed with whsec_. Recommended size: 24

Example: whsec_S6g2HLnTwd9AhHwUIMFggVS9OfoPafN8

NotificationChannelMeta

Metadata only fields of a notification channel.

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Identifies the notification channel.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

type

string · enum · required

Notification channel type.

Enum values:

WEBHOOK

NotificationChannelOrderBy

string · enum

Enum values:

id

type

createdAt

updatedAt

Order by options for notification channels.

NotificationChannelPaginatedResponse

Paginated response

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

NotificationChannel[] · required

The items in the current page.

NotificationChannelType

string · enum

Enum values:

WEBHOOK

Type of the notification channel.

NotificationChannelWebhook

Notification channel with webhook type.

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Identifies the notification channel.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

type

string · enum · required

Notification channel type.

Enum values:

WEBHOOK

name

string · minLength: 1 · maxLength: 256 · required

User friendly name of the channel.

Example: customer-webhook

url

string · required

Webhook URL where the notification is sent.

Example: https://example.com/webhook

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

disabled

boolean

Whether the channel is disabled or not.

Example: true

Default: false

object · readOnly

Set of key-value pairs managed by the system. Cannot be modified by user.

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

object | null

Additional metadata for the resource.

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

object

Custom HTTP headers sent as part of the webhook request.

signingSecret

string · pattern: ^(whsec_)?[a-zA-Z0-9…

Signing secret used for webhook request validation on the receiving end.

Format: base64 encoded random bytes optionally prefixed with whsec_. Recommended size: 24

Example: whsec_S6g2HLnTwd9AhHwUIMFggVS9OfoPafN8

NotificationChannelWebhookCreateRequest

Request with input parameters for creating new notification channel with webhook type.

type

string · enum · required

Notification channel type.

Enum values:

WEBHOOK

name

string · minLength: 1 · maxLength: 256 · required

User friendly name of the channel.

Example: customer-webhook

url

string · required

Webhook URL where the notification is sent.

Example: https://example.com/webhook

disabled

boolean

Whether the channel is disabled or not.

Example: true

Default: false

object | null

Additional metadata for the resource.

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

object

Custom HTTP headers sent as part of the webhook request.

signingSecret

string · pattern: ^(whsec_)?[a-zA-Z0-9…

Signing secret used for webhook request validation on the receiving end.

Format: base64 encoded random bytes optionally prefixed with whsec_. Recommended size: 24

Example: whsec_S6g2HLnTwd9AhHwUIMFggVS9OfoPafN8

NotificationEvent

Type of the notification event.

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

A unique identifier of the notification event.

Example: 01J2KNP1YTXQRXHTDJ4KPR7PZ0

type

string · enum · readOnly · required

Type of the notification event.

Enum values:

entitlements.balance.threshold

entitlements.reset

invoice.created

invoice.updated

createdAt

string · date-time · readOnly · required

Timestamp when the notification event was created in RFC 3339 format.

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

object · readOnly · required

The nnotification rule which generated this event.

NotificationEventDeliveryStatus[] · readOnly · required

The delivery status of the notification event.

object · readOnly · required

Timestamp when the notification event was created in RFC 3339 format.

object · readOnly

Set of key-value pairs managed by the system. Cannot be modified by user.

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

NotificationEventBalanceThresholdPayload

Payload for notification event with `entitlements.balance.threshold` type.

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

A unique identifier for the notification event the payload belongs to.

Example: 01J2KNP1YTXQRXHTDJ4KPR7PZ0

type

string · enum · readOnly · required

Type of the notification event.

Enum values:

entitlements.balance.threshold

timestamp

string · date-time · readOnly · required

Timestamp when the notification event was created in RFC 3339 format.

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

object · readOnly · required

The data of the payload.

NotificationEventBalanceThresholdPayloadData

Data of the payload for notification event with `entitlements.balance.threshold` type.

object · readOnly · required

Metered entitlements are useful for many different use cases, from setting up usage based access to implementing complex credit systems. Access is determined based on feature usage using a balance calculation (the "usage allowance" provided by the issued grants is "burnt down" by the usage).

object · readOnly · required

Represents a feature that can be enabled or disabled for a plan. Used both for product catalog and entitlements.

object · readOnly · required

A subject is a unique identifier for a usage attribution by its key. Subjects only exist in the concept of metering. Subjects are optional to create and work as an enrichment for the subject key like displayName, metadata, etc. Subjects are useful when you are reporting usage events with your own database ID but want to enrich the subject with a human-readable name or metadata. For most use cases, a subject is equivalent to a customer.

Example: {"createdAt":"2025-01-01T01:01:01.001Z","updatedAt":"2025-02-01T01:01:01.001Z","deletedAt":"2025-03-01T01:01:01.001Z","id":"01G65Z755AFWAKHE12NY0CQ9FH","key":"customer-id","displayName":"Customer Name","metadata":{"hubspotId":"123456"},"stripeCustomerId":"cus_JMOlctsKV8"}

object · readOnly · required

Entitlements are the core of Zuplo Metering access management. They define access to features for subjects. Entitlements can be metered, boolean, or static.

object · readOnly · required

Threshold value with multiple supported types.

object · readOnly

A customer object.

Example: {"id":"01G65Z755AFWAKHE12NY0CQ9FH","name":"ACME Inc.","usageAttribution":{"subjectKeys":["my_subject_key"]},"createdAt":"2024-01-01T01:01:01.001Z","updatedAt":"2024-01-01T01:01:01.001Z"}

NotificationEventDeliveryAttempt

The delivery attempt of the notification event.

state

string · enum · readOnly · required

State of teh delivery attempt.

Enum values:

SUCCESS

FAILED

SENDING

PENDING

RESENDING

Example: SUCCESS

object · readOnly · required

Response returned by the notification event recipient.

timestamp

string · date-time · readOnly · required

Timestamp of the delivery attempt.

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

NotificationEventDeliveryStatus

The delivery status of the notification event.

state

string · enum · readOnly · required

Delivery state of the notification event to the channel.

Enum values:

SUCCESS

FAILED

SENDING

PENDING

RESENDING

Example: SUCCESS

reason

string · readOnly · required

The reason of the last deliverry state update.

Example: Failed to dispatch event due to provider error.

updatedAt

string · date-time · readOnly · required

Timestamp of when the status was last updated in RFC 3339 format.

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

object · readOnly · required

Notification channel the delivery status associated with.

NotificationEventDeliveryAttempt[] · readOnly · required

List of delivery attempts.

object · readOnly

Set of key-value pairs managed by the system. Cannot be modified by user.

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

nextAttempt

string · date-time · readOnly

Timestamp of the next delivery attempt. If null it means there will be no more delivery attempts.

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

NotificationEventDeliveryStatusState

string · enum

Enum values:

SUCCESS

FAILED

SENDING

PENDING

RESENDING

The delivery state of the notification event to the channel.

NotificationEventEntitlementValuePayloadBase

Base data for any payload with entitlement entitlement value.

object · readOnly · required

Metered entitlements are useful for many different use cases, from setting up usage based access to implementing complex credit systems. Access is determined based on feature usage using a balance calculation (the "usage allowance" provided by the issued grants is "burnt down" by the usage).

object · readOnly · required

Represents a feature that can be enabled or disabled for a plan. Used both for product catalog and entitlements.

object · readOnly · required

A subject is a unique identifier for a usage attribution by its key. Subjects only exist in the concept of metering. Subjects are optional to create and work as an enrichment for the subject key like displayName, metadata, etc. Subjects are useful when you are reporting usage events with your own database ID but want to enrich the subject with a human-readable name or metadata. For most use cases, a subject is equivalent to a customer.

Example: {"createdAt":"2025-01-01T01:01:01.001Z","updatedAt":"2025-02-01T01:01:01.001Z","deletedAt":"2025-03-01T01:01:01.001Z","id":"01G65Z755AFWAKHE12NY0CQ9FH","key":"customer-id","displayName":"Customer Name","metadata":{"hubspotId":"123456"},"stripeCustomerId":"cus_JMOlctsKV8"}

object · readOnly · required

Entitlements are the core of Zuplo Metering access management. They define access to features for subjects. Entitlements can be metered, boolean, or static.

object · readOnly

A customer object.

Example: {"id":"01G65Z755AFWAKHE12NY0CQ9FH","name":"ACME Inc.","usageAttribution":{"subjectKeys":["my_subject_key"]},"createdAt":"2024-01-01T01:01:01.001Z","updatedAt":"2024-01-01T01:01:01.001Z"}

NotificationEventInvoiceCreatedPayload

Payload for notification event with `invoice.created` type.

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

A unique identifier for the notification event the payload belongs to.

Example: 01J2KNP1YTXQRXHTDJ4KPR7PZ0

type

string · enum · readOnly · required

Type of the notification event.

Enum values:

invoice.created

timestamp

string · date-time · readOnly · required

Timestamp when the notification event was created in RFC 3339 format.

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

object · readOnly · required

The data of the payload.

NotificationEventInvoiceUpdatedPayload

Payload for notification event with `invoice.updated` type.

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

A unique identifier for the notification event the payload belongs to.

Example: 01J2KNP1YTXQRXHTDJ4KPR7PZ0

type

string · enum · readOnly · required

Type of the notification event.

Enum values:

invoice.updated

timestamp

string · date-time · readOnly · required

Timestamp when the notification event was created in RFC 3339 format.

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

object · readOnly · required

The data of the payload.

NotificationEventOrderBy

string · enum

Enum values:

id

createdAt

Order by options for notification channels.

NotificationEventPaginatedResponse

Paginated response

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

NotificationEvent[] · required

The items in the current page.

NotificationEventPayload

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · type="entitlements.reset" · requires: id, timestamp, data
	type = object · type="entitlements.balance.threshold" · requires: id, timestamp, data
	type = object · type="invoice.created" · requires: id, timestamp, data
	type = object · type="invoice.updated" · requires: id, timestamp, data

Properties for Variant 1:

Payload for notification event with `entitlements.reset` type.

NotificationEventResetPayload

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

A unique identifier for the notification event the payload belongs to.

Example: 01J2KNP1YTXQRXHTDJ4KPR7PZ0

type

string · enum · readOnly · required

Type of the notification event.

Enum values:

entitlements.reset

timestamp

string · date-time · readOnly · required

Timestamp when the notification event was created in RFC 3339 format.

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

object · readOnly · required

The data of the payload.

NotificationEventResendRequest

A notification event that will be re-sent.

channels

string[]

Notification channels to which the event should be re-sent.

NotificationEventResetPayload

Payload for notification event with `entitlements.reset` type.

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

A unique identifier for the notification event the payload belongs to.

Example: 01J2KNP1YTXQRXHTDJ4KPR7PZ0

type

string · enum · readOnly · required

Type of the notification event.

Enum values:

entitlements.reset

timestamp

string · date-time · readOnly · required

Timestamp when the notification event was created in RFC 3339 format.

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

object · readOnly · required

The data of the payload.

NotificationEventType

string · enum

Enum values:

entitlements.balance.threshold

entitlements.reset

invoice.created

invoice.updated

Type of the notification event.

NotificationRule

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · type="entitlements.balance.threshold" · requires: createdAt, updatedAt, id +3 more
	type = object · type="entitlements.reset" · requires: createdAt, updatedAt, id +2 more
	type = object · type="invoice.created" · requires: createdAt, updatedAt, id +2 more
	type = object · type="invoice.updated" · requires: createdAt, updatedAt, id +2 more

Properties for Variant 1:

Notification rule with entitlements.balance.threshold type.

NotificationRuleBalanceThreshold

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Identifies the notification rule.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

type

string · enum · required

Notification rule type.

Enum values:

entitlements.balance.threshold

name

string · minLength: 1 · maxLength: 256 · required

The user friendly name of the notification rule.

Example: Balance threshold reached

NotificationChannelMeta[] · required

List of notification channels the rule applies to.

NotificationRuleBalanceThresholdValue[] · minItems: 1 · maxItems: 10 · required

List of thresholds the rule suppose to be triggered.

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

disabled

boolean

Whether the rule is disabled or not.

Example: true

Default: false

object · readOnly

Set of key-value pairs managed by the system. Cannot be modified by user.

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

object | null

Additional metadata for the resource.

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

FeatureMeta[] · minItems: 1

Optional field containing list of features the rule applies to.

NotificationRuleBalanceThreshold

Notification rule with entitlements.balance.threshold type.

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Identifies the notification rule.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

type

string · enum · required

Notification rule type.

Enum values:

entitlements.balance.threshold

name

string · minLength: 1 · maxLength: 256 · required

The user friendly name of the notification rule.

Example: Balance threshold reached

NotificationChannelMeta[] · required

List of notification channels the rule applies to.

NotificationRuleBalanceThresholdValue[] · minItems: 1 · maxItems: 10 · required

List of thresholds the rule suppose to be triggered.

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

disabled

boolean

Whether the rule is disabled or not.

Example: true

Default: false

object · readOnly

Set of key-value pairs managed by the system. Cannot be modified by user.

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

object | null

Additional metadata for the resource.

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

FeatureMeta[] · minItems: 1

Optional field containing list of features the rule applies to.

NotificationRuleBalanceThresholdCreateRequest

Request with input parameters for creating new notification rule with entitlements.balance.threshold type.

type

string · enum · required

Notification rule type.

Enum values:

entitlements.balance.threshold

name

string · minLength: 1 · maxLength: 256 · required

The user friendly name of the notification rule.

Example: Balance threshold reached

NotificationRuleBalanceThresholdValue[] · minItems: 1 · maxItems: 10 · required

List of thresholds the rule suppose to be triggered.

channels

string[] · minItems: 1 · required

List of notification channels the rule is applied to.

disabled

boolean

Whether the rule is disabled or not.

Example: true

Default: false

object | null

Additional metadata for the resource.

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

features

string[] · minItems: 1

Optional field for defining the scope of notification by feature. It may contain features by id or key.

NotificationRuleBalanceThresholdValue

Threshold value with multiple supported types.

value

number · double · required

Value of the threshold.

Example: 100

type

string · enum · required

Type of the threshold.

Enum values:

PERCENT

NUMBER

balance_value

usage_percentage

usage_value

Example: usage_value

NotificationRuleBalanceThresholdValueType

string · enum

Enum values:

PERCENT

NUMBER

balance_value

usage_percentage

usage_value

Type of the rule in the balance threshold specification:

balance_value: threshold defined by the remaining balance value based on usage and the total of grants in the current usage period
usage_percentage: threshold defined by the usage percentage compared to the total of grants in the current usage period
usage_value: threshold defined by the usage value in the current usage period
NUMBER (deprecated): see usage_value
PERCENT (deprecated): see usage_percentage

NotificationRuleCreateRequest

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · type="entitlements.balance.threshold" · requires: name, thresholds, channels
	type = object · type="entitlements.reset" · requires: name, channels
	type = object · type="invoice.created" · requires: name, channels
	type = object · type="invoice.updated" · requires: name, channels

Properties for Variant 1:

Request with input parameters for creating new notification rule with entitlements.balance.threshold type.

NotificationRuleBalanceThresholdCreateRequest

type

string · enum · required

Notification rule type.

Enum values:

entitlements.balance.threshold

name

string · minLength: 1 · maxLength: 256 · required

The user friendly name of the notification rule.

Example: Balance threshold reached

NotificationRuleBalanceThresholdValue[] · minItems: 1 · maxItems: 10 · required

List of thresholds the rule suppose to be triggered.

channels

string[] · minItems: 1 · required

List of notification channels the rule is applied to.

disabled

boolean

Whether the rule is disabled or not.

Example: true

Default: false

object | null

Additional metadata for the resource.

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

features

string[] · minItems: 1

Optional field for defining the scope of notification by feature. It may contain features by id or key.

NotificationRuleEntitlementReset

Notification rule with entitlements.reset type.

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Identifies the notification rule.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

type

string · enum · required

Notification rule type.

Enum values:

entitlements.reset

name

string · minLength: 1 · maxLength: 256 · required

The user friendly name of the notification rule.

Example: Balance threshold reached

NotificationChannelMeta[] · required

List of notification channels the rule applies to.

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

disabled

boolean

Whether the rule is disabled or not.

Example: true

Default: false

object · readOnly

Set of key-value pairs managed by the system. Cannot be modified by user.

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

object | null

Additional metadata for the resource.

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

FeatureMeta[] · minItems: 1

Optional field containing list of features the rule applies to.

NotificationRuleEntitlementResetCreateRequest

Request with input parameters for creating new notification rule with entitlements.reset type.

type

string · enum · required

Notification rule type.

Enum values:

entitlements.reset

name

string · minLength: 1 · maxLength: 256 · required

The user friendly name of the notification rule.

Example: Balance threshold reached

channels

string[] · minItems: 1 · required

List of notification channels the rule is applied to.

disabled

boolean

Whether the rule is disabled or not.

Example: true

Default: false

object | null

Additional metadata for the resource.

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

features

string[] · minItems: 1

Optional field for defining the scope of notification by feature. It may contain features by id or key.

NotificationRuleInvoiceCreated

Notification rule with invoice.created type.

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Identifies the notification rule.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

type

string · enum · required

Notification rule type.

Enum values:

invoice.created

name

string · minLength: 1 · maxLength: 256 · required

The user friendly name of the notification rule.

Example: Balance threshold reached

NotificationChannelMeta[] · required

List of notification channels the rule applies to.

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

disabled

boolean

Whether the rule is disabled or not.

Example: true

Default: false

object · readOnly

Set of key-value pairs managed by the system. Cannot be modified by user.

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

object | null

Additional metadata for the resource.

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

NotificationRuleInvoiceCreatedCreateRequest

Request with input parameters for creating new notification rule with invoice.created type.

type

string · enum · required

Notification rule type.

Enum values:

invoice.created

name

string · minLength: 1 · maxLength: 256 · required

The user friendly name of the notification rule.

Example: Balance threshold reached

channels

string[] · minItems: 1 · required

List of notification channels the rule is applied to.

disabled

boolean

Whether the rule is disabled or not.

Example: true

Default: false

object | null

Additional metadata for the resource.

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

NotificationRuleInvoiceUpdated

Notification rule with invoice.updated type.

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Identifies the notification rule.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

type

string · enum · required

Notification rule type.

Enum values:

invoice.updated

name

string · minLength: 1 · maxLength: 256 · required

The user friendly name of the notification rule.

Example: Balance threshold reached

NotificationChannelMeta[] · required

List of notification channels the rule applies to.

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

disabled

boolean

Whether the rule is disabled or not.

Example: true

Default: false

object · readOnly

Set of key-value pairs managed by the system. Cannot be modified by user.

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

object | null

Additional metadata for the resource.

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

NotificationRuleInvoiceUpdatedCreateRequest

Request with input parameters for creating new notification rule with invoice.updated type.

type

string · enum · required

Notification rule type.

Enum values:

invoice.updated

name

string · minLength: 1 · maxLength: 256 · required

The user friendly name of the notification rule.

Example: Balance threshold reached

channels

string[] · minItems: 1 · required

List of notification channels the rule is applied to.

disabled

boolean

Whether the rule is disabled or not.

Example: true

Default: false

object | null

Additional metadata for the resource.

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

NotificationRuleMeta

Metadata only fields of a notification channel.

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

Identifies the notification rule.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

type

string · enum · readOnly · required

Notification rule type.

Enum values:

entitlements.balance.threshold

entitlements.reset

invoice.created

invoice.updated

NotificationRuleOrderBy

string · enum

Enum values:

id

type

createdAt

updatedAt

Order by options for notification channels.

NotificationRulePaginatedResponse

Paginated response

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

NotificationRule[] · required

The items in the current page.

Numeric

string · pattern: ^\-?[0-9]+(\.[0-9]+)…

Numeric represents an arbitrary precision number.

OAuth2AuthorizationCodeGrantErrorType

string · enum

Enum values:

invalid_request

unauthorized_client

access_denied

unsupported_response_type

invalid_scope

server_error

temporarily_unavailable

OAuth2 authorization code grant error types.

PackagePrice

Package price. The item is sold in packages. Each package contains quantityPerPackage items, the price of the package is set in amount. The total price of the usage will be enough packages that can accomodate all the usage. Examples (given a package size of 20, and an amount of $10): - if the quantity is 98, the price will be 5*$10=$50. - if the quantity is zero, the price will be 0*$10=$0, as even the first package is not purchased. - if the quantity is 20, the price will be 1*$10=$10, as the usage fits into the first package. - if the quantity is 20.1, the price will be 2*$10=$20, as the additional 0.1 usage (compared to the previous example) requires a new package.

type

string · enum · required

The type of the price.

Enum values:

package

amount

string · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The price of one package.

quantityPerPackage

string · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The quantity per package.

PackagePriceWithCommitments

Package price with spend commitments.

type

string · enum · required

The type of the price.

Enum values:

package

amount

string · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The price of one package.

quantityPerPackage

string · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The quantity per package.

minimumAmount

string · pattern: ^\-?[0-9]+(\.[0-9]+)…

The customer is committed to spend at least the amount.

maximumAmount

string · pattern: ^\-?[0-9]+(\.[0-9]+)…

The customer is limited to spend at most the amount.

PaymentDueDate

PaymentDueDate contains an amount that should be paid by the given date.

dueAt

string · date-time · readOnly · required

When the payment is due.

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

amount

string · readOnly · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

How much needs to be paid by the date.

notes

string · readOnly

Other details to take into account for the due date.

percent

number · double · readOnly

Percentage of the total that should be paid by the date.

Example: 50

currency

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

If different from the parent document's base currency.

Example: USD

PaymentTermDueDate

PaymentTermDueDate defines the terms for payment on a specific date.

type

string · enum · required

Type of terms to be applied.

Enum values:

due_date

PaymentDueDate[] · minItems: 1 · readOnly · required

When the payment is due.

detail

string · readOnly

Text detail of the chosen payment terms.

notes

string · readOnly

Description of the conditions for payment.

PaymentTermInstant

PaymentTermInstant defines the terms for payment on receipt of invoice.

type

string · enum · required

Type of terms to be applied.

Enum values:

instant

detail

string · readOnly

Text detail of the chosen payment terms.

notes

string · readOnly

Description of the conditions for payment.

PaymentTermType

string · enum

Enum values:

due_date

instant

PaymentTermType defines the type of terms to be applied.

PaymentTerms

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = object · requires: type
	type = object · requires: type, dueAt

Properties for Variant 1:

PaymentTermInstant defines the terms for payment on receipt of invoice.

PaymentTermInstant

type

string · enum · required

Type of terms to be applied.

Enum values:

instant

detail

string · readOnly

Text detail of the chosen payment terms.

notes

string · readOnly

Description of the conditions for payment.

Percentage

number · double

Numeric representation of a percentage

50% is represented as 50

Example: 50

Period

A period with a start and end time.

from

string · date-time · required

Period start time.

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

to

string · date-time · required

Period end time.

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

Plan

Plans provide a template for subscriptions.

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

PlanAddon

The PlanAddon describes the association between a plan and add-on.

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

object · readOnly · required

Add-on object.

fromPlanPhase

string · required

The key of the plan phase from the add-on becomes available for purchase.

array | null · readOnly · required

List of validation errors.

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

object · readOnly

Set of key-value pairs managed by the system. Cannot be modified by user.

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

object

Additional metadata for the resource.

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

maxQuantity

integer

The maximum number of times the add-on can be purchased for the plan. It is not applicable for add-ons with single instance type.

PlanAddonCreate

A plan add-on assignment create request.

fromPlanPhase

string · required

The key of the plan phase from the add-on becomes available for purchase.

addonId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The add-on unique identifier in ULID format.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

object

Additional metadata for the resource.

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

maxQuantity

integer

The maximum number of times the add-on can be purchased for the plan. It is not applicable for add-ons with single instance type.

PlanAddonOrderBy

string · enum

Enum values:

id

key

version

created_at

updated_at

Order by options for plan add-on assignments.

PlanAddonPaginatedResponse

Paginated response

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

PlanAddon[] · required

The items in the current page.

PlanAddonReplaceUpdate

Resource update operation model.

fromPlanPhase

string · required

The key of the plan phase from the add-on becomes available for purchase.

object

Additional metadata for the resource.

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

maxQuantity

integer

The maximum number of times the add-on can be purchased for the plan. It is not applicable for add-ons with single instance type.

PlanCreate

Resource create operation model.

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

PlanOrderBy

string · enum

Enum values:

id

key

version

created_at

updated_at

Order by options for plans.

PlanPaginatedResponse

Paginated response

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.

PlanPhase

The plan phase or pricing ramp allows changing a plan's rate cards over time as a subscription progresses.

key

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

A semi-unique identifier for the resource.

name

string · minLength: 1 · maxLength: 256 · required

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

duration

string | null · duration · required

The duration of the phase.

Example: P1Y

RateCard[] · required

The rate cards of the plan.

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

PlanReference

References an exact plan.

id

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The plan ID.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

key

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

The plan key.

version

integer · required

The plan version.

PlanReferenceInput

References an exact plan defaulting to the current active version.

key

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

The plan key.

version

integer

The plan version.

PlanReplaceUpdate

Resource update operation model.

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

PlanStatus

string · enum

Enum values:

draft

active

archived

scheduled

The status of a plan.

PlanSubscriptionChange

Change subscription based on plan.

required

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

object · required

The plan reference to change to.

object

Arbitrary metadata associated with the subscription.

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

startingPhase

string · minLength: 1

The key of the phase to start the subscription in. If not provided, the subscription will start in the first phase of the plan.

name

string

The name of the Subscription. If not provided the plan name is used.

description

string

Description for the Subscription.

billingAnchor

string · date-time

The billing anchor of the subscription. The provided date will be normalized according to the billing cadence to the nearest recurrence before start time. If not provided, the previous subscription billing anchor will be used.

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

PlanSubscriptionCreate

Create subscription based on plan.

object · required

The plan reference to change to.

object

Arbitrary metadata associated with the subscription.

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

startingPhase

string · minLength: 1

The key of the phase to start the subscription in. If not provided, the subscription will start in the first phase of the plan.

name

string

The name of the Subscription. If not provided the plan name is used.

description

string

Description for the Subscription.

Timing configuration for the change, when the change should take effect. The default is immediate.

Default: immediate

customerId

string · pattern: ^[0-7][0-9A-HJKMNP-T…

The ID of the customer. Provide either the key or ID. Has presedence over the key.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

customerKey

string · minLength: 1 · maxLength: 256

The key of the customer. Provide either the key or ID.

billingAnchor

string · date-time

The billing anchor of the subscription. The provided date will be normalized according to the billing cadence to the nearest recurrence before start time. If not provided, the subscription start time will be used.

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

PortalToken

A consumer portal token. Validator doesn't obey required for readOnly properties See: https://github.com/stoplightio/spectral/issues/1274

subject

string · required

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T…

ULID (Universally Unique Lexicographically Sortable Identifier).

Example: 01G65Z755AFWAKHE12NY0CQ9FH

expiresAt

string · date-time · readOnly

RFC3339 formatted date-time string in UTC.

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

expired

boolean · readOnly

createdAt

string · date-time · readOnly

RFC3339 formatted date-time string in UTC.

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

token

string · readOnly

The token is only returned at creation.

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ6dXBsby1tZXRlcmluZyIsInN1YiI6ImN1c3RvbWVyLTEifQ.signature

allowedMeterSlugs

string[]

Optional, if defined only the specified meters will be allowed.

Example: {"0":"tokens_total"}

PreconditionFailedProblemResponse

One or more conditions given in the request header fields evaluated to false when tested on the server.

type

string · uri · required

Type contains a URI that identifies the problem type.

Example: about:blank

Default: about:blank

title

string · required

A a short, human-readable summary of the problem type.

Example: Bad Request

detail

string · required

A human-readable explanation specific to this occurrence of the problem.

Example: The request body must be a JSON object.

instance

string · uri · required

A URI reference that identifies the specific occurrence of the problem.

Example: urn:request:local/JMOlctsKV8-000001

status

integer · int16 · min: 400 · max: 599

The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 400

object

Additional properties specific to the problem type may be present.

Example: {"validationErrors":[{"code":"validation_error","message":"Validation error"}],"otherAttribute":"otherValue"}

No data returned

Price

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · type="flat" · requires: amount
	type = object · type="unit" · requires: amount
	type = object · type="tiered" · requires: mode, tiers
	type = object · type="dynamic"
	type = object · type="package" · requires: amount, quantityPerPackage

Properties for Variant 1:

Flat price.

FlatPrice

type

string · enum · required

The type of the price.

Enum values:

flat

amount

string · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The amount of the flat price.

PricePaymentTerm

string · enum

Enum values:

in_advance

in_arrears

The payment term of a flat price. One of: in_advance or in_arrears.

PriceTier

A price tier. At least one price component is required in each tier.

flatPrice

object | null · required

The flat price component of the tier.

unitPrice

object | null · required

The unit price component of the tier.

upToAmount

string · pattern: ^\-?[0-9]+(\.[0-9]+)…

Up to and including to this quantity will be contained in the tier. If null, the tier is open-ended.

PriceType

string · enum

Enum values:

flat

unit

tiered

dynamic

package

The type of the price.

ProRatingConfig

Configuration for pro-rating behavior.

enabled

boolean · required

Whether pro-rating is enabled for this plan.

Default: true

mode

string · enum · required

How to handle pro-rating for billing period changes.

Enum values:

max_consumption_based

Default: max_consumption_based

ProRatingMode

string · enum

Enum values:

max_consumption_based

Pro-rating mode options for handling billing period changes.

Progress

Progress describes a progress of a task.

success

integer · uint64 · required

Success is the number of items that succeeded

failed

integer · uint64 · required

Failed is the number of items that failed

total

integer · uint64 · required

The total number of items to process

updatedAt

string · date-time · required

The time the progress was last updated

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

RateCard

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · type="flat_fee" · requires: key, name, billingCadence +1 more
	type = object · type="usage_based" · requires: key, name, billingCadence +1 more

Properties for Variant 1:

A flat fee rate card defines a one-time purchase or a recurring fee.

RateCardFlatFee

type

string · enum · required

The type of the RateCard.

Enum values:

flat_fee

key

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

A semi-unique identifier for the resource.

name

string · minLength: 1 · maxLength: 256 · required

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

billingCadence

string | null · duration · required

The billing cadence of the rate card. When null it means it is a one time fee.

price

object | null · required

The price of the rate card. When null, the feature or service is free.

Example: {"type":"flat","amount":"100","paymentTerm":"in_arrears"}

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

featureKey

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

The feature the customer is entitled to use.

object

The entitlement of the rate card. Only available when featureKey is set.

object

The tax config of the rate card. When undefined, the tax config of the feature or the default tax config of the plan is used.

object

The discount of the rate card. For flat fee rate cards only percentage discounts are supported. Only available when price is set.

RateCardBooleanEntitlement

Entitlement template of a boolean entitlement.

type

string · enum · required

Enum values:

boolean

object

Additional metadata for the feature.

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

RateCardEntitlement

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · type="metered"
	type = object · type="static" · requires: config
	type = object · type="boolean"

Properties for Variant 1:

The entitlement template with a metered entitlement.

RateCardMeteredEntitlement

type

string · enum · required

Enum values:

metered

object

Additional metadata for the feature.

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

isSoftLimit

boolean

If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true.

Default: false

issueAfterReset

number · double · min: 0

You can grant usage automatically alongside the entitlement, the example scenario would be creating a starting balance. If an amount is specified here, a grant will be created alongside the entitlement with the specified amount. That grant will have it's rollover settings configured in a way that after each reset operation, the balance will return the original amount specified here. Manually creating such a grant would mean having the "amount", "minRolloverAmount", and "maxRolloverAmount" fields all be the same.

issueAfterResetPriority

integer · uint8 · min: 1 · max: 255

Defines the grant priority for the default grant.

Default: 1

preserveOverageAtReset

boolean

If true, the overage is preserved at reset. If false, the usage is reset to 0.

Default: false

usagePeriod

string · duration

The interval of the metered entitlement. Defaults to the billing cadence of the rate card.

RateCardFlatFee

A flat fee rate card defines a one-time purchase or a recurring fee.

type

string · enum · required

The type of the RateCard.

Enum values:

flat_fee

key

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

A semi-unique identifier for the resource.

name

string · minLength: 1 · maxLength: 256 · required

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

billingCadence

string | null · duration · required

The billing cadence of the rate card. When null it means it is a one time fee.

price

object | null · required

The price of the rate card. When null, the feature or service is free.

Example: {"type":"flat","amount":"100","paymentTerm":"in_arrears"}

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

featureKey

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

The feature the customer is entitled to use.

object

The entitlement of the rate card. Only available when featureKey is set.

object

The tax config of the rate card. When undefined, the tax config of the feature or the default tax config of the plan is used.

object

The discount of the rate card. For flat fee rate cards only percentage discounts are supported. Only available when price is set.

RateCardMeteredEntitlement

The entitlement template with a metered entitlement.

type

string · enum · required

Enum values:

metered

object

Additional metadata for the feature.

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

isSoftLimit

boolean

If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true.

Default: false

issueAfterReset

number · double · min: 0

You can grant usage automatically alongside the entitlement, the example scenario would be creating a starting balance. If an amount is specified here, a grant will be created alongside the entitlement with the specified amount. That grant will have it's rollover settings configured in a way that after each reset operation, the balance will return the original amount specified here. Manually creating such a grant would mean having the "amount", "minRolloverAmount", and "maxRolloverAmount" fields all be the same.

issueAfterResetPriority

integer · uint8 · min: 1 · max: 255

Defines the grant priority for the default grant.

Default: 1

preserveOverageAtReset

boolean

If true, the overage is preserved at reset. If false, the usage is reset to 0.

Default: false

usagePeriod

string · duration

The interval of the metered entitlement. Defaults to the billing cadence of the rate card.

RateCardStaticEntitlement

Entitlement template of a static entitlement.

type

string · enum · required

Enum values:

static

config

string · json · required

The JSON parsable config of the entitlement. This value is also returned when checking entitlement access and it is useful for configuring fine-grained access settings to the feature, implemented in your own system. Has to be an object.

Example: { "integrations": ["github"] }

object

Additional metadata for the feature.

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

RateCardType

string · enum

Enum values:

flat_fee

usage_based

The type of the rate card.

RateCardUsageBased

A usage-based rate card defines a price based on usage.

type

string · enum · required

The type of the RateCard.

Enum values:

usage_based

key

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

A semi-unique identifier for the resource.

name

string · minLength: 1 · maxLength: 256 · required

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

billingCadence

string · duration · required

The billing cadence of the rate card.

object · required

The price of the rate card. When null, the feature or service is free.

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

featureKey

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

The feature the customer is entitled to use.

object

The entitlement of the rate card. Only available when featureKey is set.

object

The tax config of the rate card. When undefined, the tax config of the feature or the default tax config of the plan is used.

object

The discounts of the rate card.

Flat fee rate cards only support percentage discounts.

RateCardUsageBasedPrice

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · type="flat" · requires: amount
	type = object · type="unit" · requires: amount
	type = object · type="tiered" · requires: mode, tiers
	type = object · type="dynamic"
	type = object · type="package" · requires: amount, quantityPerPackage

Properties for Variant 1:

Flat price with payment term.

FlatPriceWithPaymentTerm

type

string · enum · required

The type of the price.

Enum values:

flat

amount

string · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The amount of the flat price.

paymentTerm

string · enum

The payment term of the flat price. Defaults to in advance.

Enum values:

in_advance

in_arrears

Default: in_advance

RecurringPeriod

Recurring period with an interval and an anchor.

required

The unit of time for the interval. Heuristically maps ISO duraitons to enum values or returns the ISO duration.

anchor

string · date-time · required

A date-time anchor to base the recurring period on.

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

intervalISO

string · duration · required

The unit of time for the interval in ISO8601 format.

RecurringPeriodCreateInput

Recurring period with an interval and an anchor.

required

The unit of time for the interval.

anchor

string · date-time

A date-time anchor to base the recurring period on.

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

RecurringPeriodInterval

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = string
	type = string

Properties for Variant 1:

string · pattern: ^P(?:\d+(?:\.\d+)?Y)…

RecurringPeriodIntervalEnum

string · enum

Enum values:

DAY

WEEK

MONTH

YEAR

The unit of time for the interval. One of: day, week, month, or year.

RecurringPeriodV2

Recurring period with an interval and an anchor.

required

The unit of time for the interval. Heuristically maps ISO duraitons to enum values or returns the ISO duration.

anchor

string · date-time · required

A date-time anchor to base the recurring period on.

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

RemovePhaseShifting

string · enum

Enum values:

The direction of the phase shift when a phase is removed.

ResetEntitlementUsageInput

Reset parameters

effectiveAt

string · date-time

The time at which the reset takes effect, defaults to now. The reset cannot be in the future. The provided value is truncated to the minute due to how historical meter data is stored.

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

retainAnchor

boolean

Determines whether the usage period anchor is retained or reset to the effectiveAt time.

If true, the usage period anchor is retained.
If false, the usage period anchor is reset to the effectiveAt time.

preserveOverage

boolean

Determines whether the overage is preserved or forgiven, overriding the entitlement's default behavior.

If true, the overage is preserved.
If false, the overage is forgiven.

SandboxApp

Sandbox app can be used for testing Zuplo Metering features. The app is not creating anything in external systems, thus it is safe to use for verifying Zuplo Metering features.

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

object · readOnly · required

The marketplace listing that this installed app is based on.

Example: {"type":"stripe","name":"Stripe","description":"Stripe interation allows you to collect payments with Stripe.","capabilities":[{"type":"calculateTax","key":"stripe_calculate_tax","name":"Calculate Tax","description":"Stripe Tax calculates tax portion of the invoices."},{"type":"invoiceCustomers","key":"stripe_invoice_customers","name":"Invoice Customers","description":"Stripe invoices customers with due amount."},{"type":"collectPayments","key":"stripe_collect_payments","name":"Collect Payments","description":"Stripe payments collects outstanding revenue with Stripe customer's default payment method."}],"installMethods":["with_oauth2","with_api_key"]}

status

string · enum · readOnly · required

Status of the app connection.

Enum values:

ready

unauthorized

type

string · enum · required

The app's type is Sandbox.

Enum values:

sandbox

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

SandboxAppReplaceUpdate

Resource update operation model.

name

string · minLength: 1 · maxLength: 256 · required

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

type

string · enum · required

The app's type is Sandbox.

Enum values:

sandbox

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

SandboxCustomerAppData

Sandbox Customer App Data.

type

string · enum · required

The app name.

Enum values:

sandbox

object · readOnly

The installed sandbox app this data belongs to.

id

string · pattern: ^[0-7][0-9A-HJKMNP-T…

The app ID. If not provided, it will use the global default for the app type.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

ServiceUnavailableProblemResponse

The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.

type

string · uri · required

Type contains a URI that identifies the problem type.

Example: about:blank

Default: about:blank

title

string · required

A a short, human-readable summary of the problem type.

Example: Bad Request

detail

string · required

A human-readable explanation specific to this occurrence of the problem.

Example: The request body must be a JSON object.

instance

string · uri · required

A URI reference that identifies the specific occurrence of the problem.

Example: urn:request:local/JMOlctsKV8-000001

status

integer · int16 · min: 400 · max: 599

The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 400

object

Additional properties specific to the problem type may be present.

Example: {"validationErrors":[{"code":"validation_error","message":"Validation error"}],"otherAttribute":"otherValue"}

No data returned

SortOrder

string · enum

Enum values:

ASC

DESC

The order direction.

SpendCommitments

Spending commitments. The customer is committed to spend at least the minimum amount and at most the maximum amount.

minimumAmount

string · pattern: ^\-?[0-9]+(\.[0-9]+)…

The customer is committed to spend at least the amount.

maximumAmount

string · pattern: ^\-?[0-9]+(\.[0-9]+)…

The customer is limited to spend at most the amount.

StripeAPIKeyInput

The Stripe API key input. Used to authenticate with the Stripe API.

secretAPIKey

string · required

StripeApp

A installed Stripe app object.

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

object · readOnly · required

The marketplace listing that this installed app is based on.

Example: {"type":"stripe","name":"Stripe","description":"Stripe interation allows you to collect payments with Stripe.","capabilities":[{"type":"calculateTax","key":"stripe_calculate_tax","name":"Calculate Tax","description":"Stripe Tax calculates tax portion of the invoices."},{"type":"invoiceCustomers","key":"stripe_invoice_customers","name":"Invoice Customers","description":"Stripe invoices customers with due amount."},{"type":"collectPayments","key":"stripe_collect_payments","name":"Collect Payments","description":"Stripe payments collects outstanding revenue with Stripe customer's default payment method."}],"installMethods":["with_oauth2","with_api_key"]}

status

string · enum · readOnly · required

Status of the app connection.

Enum values:

ready

unauthorized

type

string · enum · required

The app's type is Stripe.

Enum values:

stripe

stripeAccountId

string · readOnly · required

The Stripe account ID.

livemode

boolean · readOnly · required

Livemode, true if the app is in production mode.

maskedAPIKey

string · readOnly · required

The masked API key. Only shows the first 8 and last 3 characters.

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

StripeAppReadOrCreateOrUpdateOrDeleteOrQuery

A installed Stripe app object.

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

object · readOnly · required

The marketplace listing that this installed app is based on.

Example: {"type":"stripe","name":"Stripe","description":"Stripe interation allows you to collect payments with Stripe.","capabilities":[{"type":"calculateTax","key":"stripe_calculate_tax","name":"Calculate Tax","description":"Stripe Tax calculates tax portion of the invoices."},{"type":"invoiceCustomers","key":"stripe_invoice_customers","name":"Invoice Customers","description":"Stripe invoices customers with due amount."},{"type":"collectPayments","key":"stripe_collect_payments","name":"Collect Payments","description":"Stripe payments collects outstanding revenue with Stripe customer's default payment method."}],"installMethods":["with_oauth2","with_api_key"]}

status

string · enum · readOnly · required

Status of the app connection.

Enum values:

ready

unauthorized

type

string · enum · required

The app's type is Stripe.

Enum values:

stripe

stripeAccountId

string · readOnly · required

The Stripe account ID.

livemode

boolean · readOnly · required

Livemode, true if the app is in production mode.

maskedAPIKey

string · readOnly · required

The masked API key. Only shows the first 8 and last 3 characters.

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

secretAPIKey

string · password

The Stripe API key.

StripeAppReplaceUpdate

Resource update operation model.

name

string · minLength: 1 · maxLength: 256 · required

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

type

string · enum · required

The app's type is Stripe.

Enum values:

stripe

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

secretAPIKey

string · password

The Stripe API key.

StripeCheckoutSessionMode

string · enum

Enum values:

setup

Stripe CheckoutSession.mode

StripeCustomerAppData

Stripe Customer App Data.

type

string · enum · required

The app name.

Enum values:

stripe

stripeCustomerId

string · required

The Stripe customer ID.

id

string · pattern: ^[0-7][0-9A-HJKMNP-T…

The app ID. If not provided, it will use the global default for the app type.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

stripeDefaultPaymentMethodId

string

The Stripe default payment method ID.

object · readOnly

The installed stripe app this data belongs to.

Example: {"id":"01G65Z755AFWAKHE12NY0CQ9FH","type":"stripe","name":"Stripe","status":"ready","listing":{"type":"stripe","name":"Stripe","description":"Stripe interation allows you to collect payments with Stripe.","capabilities":[{"type":"calculateTax","key":"stripe_calculate_tax","name":"Calculate Tax","description":"Stripe Tax calculates tax portion of the invoices."},{"type":"invoiceCustomers","key":"stripe_invoice_customers","name":"Invoice Customers","description":"Stripe invoices customers with due amount."},{"type":"collectPayments","key":"stripe_collect_payments","name":"Collect Payments","description":"Stripe payments collects outstanding revenue with Stripe customer's default payment method."}],"installMethods":["with_oauth2","with_api_key"]},"createdAt":"2024-01-01T01:01:01.001Z","updatedAt":"2024-01-01T01:01:01.001Z","stripeAccountId":"acct_123456789","livemode":true,"maskedAPIKey":"sk_live_************abc"}

StripeCustomerAppDataBase

Stripe Customer App Data Base.

stripeCustomerId

string · required

The Stripe customer ID.

stripeDefaultPaymentMethodId

string

The Stripe default payment method ID.

StripeCustomerAppDataCreateOrUpdateItem

Stripe Customer App Data.

type

string · enum · required

The app name.

Enum values:

stripe

stripeCustomerId

string · required

The Stripe customer ID.

id

string · pattern: ^[0-7][0-9A-HJKMNP-T…

The app ID. If not provided, it will use the global default for the app type.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

stripeDefaultPaymentMethodId

string

The Stripe default payment method ID.

StripeCustomerPortalSession

Stripe customer portal session. See: https://docs.stripe.com/api/customer_portal/sessions/object

id

string · required

The ID of the customer portal session.

See: https://docs.stripe.com/api/customer_portal/sessions/object#portal_session_object-id

stripeCustomerId

string · required

The ID of the stripe customer.

configurationId

string · required

Configuration used to customize the customer portal.

See: https://docs.stripe.com/api/customer_portal/sessions/object#portal_session_object-configuration

livemode

boolean · required

Livemode.

See: https://docs.stripe.com/api/customer_portal/sessions/object#portal_session_object-livemode

createdAt

string · date-time · required

Created at.

See: https://docs.stripe.com/api/customer_portal/sessions/object#portal_session_object-created

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

returnUrl

string · required

Return URL.

See: https://docs.stripe.com/api/customer_portal/sessions/object#portal_session_object-return_url

locale

string · required

Status. /** The IETF language tag of the locale customer portal is displayed in.

See: https://docs.stripe.com/api/customer_portal/sessions/object#portal_session_object-locale

url

string · required

/** The ID of the customer.The URL to redirect the customer to after they have completed their requested actions.

StripeTaxConfig

The tax config for Stripe.

code

string · pattern: ^txcd_\d{8}$ · required

Product tax code.

See: https://docs.stripe.com/tax/tax-codes

Example: txcd_10000000

StripeWebhookEvent

Stripe webhook event.

id

string · required

The event ID.

type

string · required

The event type.

livemode

boolean · required

Live mode.

created

integer · int32 · required

The event created timestamp.

object · required

The event data.

StripeWebhookResponse

Stripe webhook response.

namespaceId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

ULID (Universally Unique Lexicographically Sortable Identifier).

Example: 01G65Z755AFWAKHE12NY0CQ9FH

appId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

ULID (Universally Unique Lexicographically Sortable Identifier).

Example: 01G65Z755AFWAKHE12NY0CQ9FH

customerId

string · pattern: ^[0-7][0-9A-HJKMNP-T…

ULID (Universally Unique Lexicographically Sortable Identifier).

Example: 01G65Z755AFWAKHE12NY0CQ9FH

message

string

Subject

A subject is a unique identifier for a usage attribution by its key. Subjects only exist in the concept of metering. Subjects are optional to create and work as an enrichment for the subject key like displayName, metadata, etc. Subjects are useful when you are reporting usage events with your own database ID but want to enrich the subject with a human-readable name or metadata. For most use cases, a subject is equivalent to a customer.

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

A unique identifier for the subject.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

key

string · required

A unique, human-readable identifier for the subject. This is typically a database ID or a customer key.

Example: customer-db-id-123

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

displayName

string | null

A human-readable display name for the subject.

Example: Customer Name

object | null

Metadata for the subject.

Example: {"hubspotId":"123456"}

SubjectUpsert

A subject is a unique identifier for a user or entity.

key

string · required

A unique, human-readable identifier for the subject. This is typically a database ID or a customer key.

Example: customer-db-id-123

displayName

string | null

A human-readable display name for the subject.

Example: Customer Name

object | null

Metadata for the subject.

Example: {"hubspotId":"123456"}

Subscription

Subscription is an exact subscription instance.

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

activeFrom

string · date-time · required

The cadence start of the resource.

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

status

string · enum · readOnly · required

The status of the subscription.

Enum values:

active

inactive

canceled

scheduled

customerId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The customer ID of the subscription.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

currency

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

The currency code of the subscription. Will be revised once we add multi currency support.

Example: USD

Default: USD

billingCadence

string · duration · readOnly · required

The billing cadence for the subscriptions. Defines how often customers are billed using ISO8601 duration format. Examples: "P1M" (monthly), "P3M" (quarterly), "P1Y" (annually).

Example: P1M

billingAnchor

string · date-time · readOnly · required

The normalizedbilling anchor of the subscription.

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

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

activeTo

string · date-time

The cadence end of the resource.

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

object · readOnly

Set of key-value pairs managed by the system. Cannot be modified by user.

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

object

The plan of the subscription.

object · readOnly

The pro-rating configuration for the subscriptions.

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

SubscriptionAccess

Access information for a specific subscription including entitlements and usage.

subscriptionId

string · readOnly · required

The subscription ID this access is for.

customerId

string · readOnly · required

The customer ID that owns this subscription.

object · required

Map of feature keys to entitlement values for this subscription.

planKey

string · readOnly

The plan key of the subscription.

object

The payment status of the current subscription phase.

accessBlocked

boolean · readOnly

If true, end-user API requests for this subscription are denied by the monetization policy. Toggled via the block-access and unblock-access endpoints.

SubscriptionAddon

A subscription add-on, represents concrete instances of an add-on for a given subscription.

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

activeFrom

string · date-time · readOnly · required

The cadence start of the resource.

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

object · required

Partially populated add-on properties.

quantityAt

string · date-time · readOnly · required

For which point in time the quantity was resolved to.

Example: 2025-01-05T00:00:00Z

quantity

integer · min: 0 · required

The quantity of the add-on. Always 1 for single instance add-ons.

Example: 1

SubscriptionAddonTimelineSegment[] · readOnly · required

The timeline of the add-on. The returned periods are sorted and continuous.

Example: {"0":{"quantity":1,"activeFrom":"2025-01-01T00:00:00Z","activeTo":"2025-01-02T00:00:00Z"},"1":{"quantity":0,"activeFrom":"2025-01-02T00:00:00Z","activeTo":"2025-01-03T00:00:00Z"},"2":{"quantity":1,"activeFrom":"2025-01-03T00:00:00Z"}}

subscriptionId

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The ID of the subscription.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

SubscriptionAddonRateCard[] · readOnly · required

The rate cards of the add-on.

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

activeTo

string · date-time · readOnly

The cadence end of the resource.

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

SubscriptionAddonCreate

A subscription add-on create body.

name

string · minLength: 1 · maxLength: 256 · required

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

quantity

integer · min: 0 · required

The quantity of the add-on. Always 1 for single instance add-ons.

Example: 1

required

The timing of the operation. After the create or update, a new entry will be created in the timeline.

object · required

The add-on to create.

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

SubscriptionAddonRateCard

A rate card for a subscription add-on.

object · required

The rate card.

affectedSubscriptionItemIds

string[] · readOnly · required

The IDs of the subscription items that this rate card belongs to.

SubscriptionAddonTimelineSegment

A subscription add-on event.

activeFrom

string · date-time · required

The cadence start of the resource.

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

quantity

integer · min: 0 · readOnly · required

The quantity of the add-on for the given period.

Example: 1

activeTo

string · date-time

The cadence end of the resource.

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

SubscriptionAddonUpdate

Resource create or update operation model.

name

string · minLength: 1 · maxLength: 256

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

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

quantity

integer · min: 0

The quantity of the add-on. Always 1 for single instance add-ons.

Example: 1

The timing of the operation. After the create or update, a new entry will be created in the timeline.

SubscriptionAlignment

Alignment details enriched with the current billing period.

object

The current billing period. Only has value if the subscription is aligned and active.

SubscriptionBadRequestErrorResponse

The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). Variants with ErrorExtensions specific to subscriptions.

type

string · uri · required

Type contains a URI that identifies the problem type.

Example: about:blank

Default: about:blank

title

string · required

A a short, human-readable summary of the problem type.

Example: Bad Request

detail

string · required

A human-readable explanation specific to this occurrence of the problem.

Example: The request body must be a JSON object.

instance

string · uri · required

A URI reference that identifies the specific occurrence of the problem.

Example: urn:request:local/JMOlctsKV8-000001

status

integer · int16 · min: 400 · max: 599

The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 400

object

Additional properties specific to the problem type may be present.

SubscriptionChange

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: timing, plan
	type = object · requires: timing, customPlan

Properties for Variant 1:

Change subscription based on plan.

PlanSubscriptionChange

required

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

object · required

The plan reference to change to.

object

Arbitrary metadata associated with the subscription.

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

startingPhase

string · minLength: 1

The key of the phase to start the subscription in. If not provided, the subscription will start in the first phase of the plan.

name

string

The name of the Subscription. If not provided the plan name is used.

description

string

Description for the Subscription.

billingAnchor

string · date-time

The billing anchor of the subscription. The provided date will be normalized according to the billing cadence to the nearest recurrence before start time. If not provided, the previous subscription billing anchor will be used.

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

SubscriptionChangeCreditEstimate

Estimated proration credit for a subscription change.

creditAmount

string · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The total estimated credit amount.

currency

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

The currency of the credit.

Example: USD

maxPercentage

string · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The max(time%, consumption%) used in the calculation (as a ratio, e.g. 0.35 = 35%).

timePercentage

string · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The time-based percentage consumed in the current billing period (as a ratio).

consumptionPercentage

string · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The max entitlement consumption percentage across metered items (as a ratio).

upfrontCost

string · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The total upfront cost of the subscription used as the base for the credit.

overflowCredit

string · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The overflow credit from previous subscription changes (multi-hop A→B→C).

SubscriptionChangeResponseBody

Response body for subscription change.

object · required

The current subscription before the change.

object · required

The new state of the subscription after the change.

SubscriptionConflictErrorResponse

The request could not be completed due to a conflict with the current state of the target resource. Variants with ErrorExtensions specific to subscriptions.

type

string · uri · required

Type contains a URI that identifies the problem type.

Example: about:blank

Default: about:blank

title

string · required

A a short, human-readable summary of the problem type.

Example: Bad Request

detail

string · required

A human-readable explanation specific to this occurrence of the problem.

Example: The request body must be a JSON object.

instance

string · uri · required

A URI reference that identifies the specific occurrence of the problem.

Example: urn:request:local/JMOlctsKV8-000001

status

integer · int16 · min: 400 · max: 599

The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 400

object

Additional properties specific to the problem type may be present.

SubscriptionCreate

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: plan
	type = object · requires: customPlan

Properties for Create from plan:

Create subscription based on plan.

PlanSubscriptionCreate

object · required

The plan reference to change to.

object

Arbitrary metadata associated with the subscription.

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

startingPhase

string · minLength: 1

The key of the phase to start the subscription in. If not provided, the subscription will start in the first phase of the plan.

name

string

The name of the Subscription. If not provided the plan name is used.

description

string

Description for the Subscription.

Timing configuration for the change, when the change should take effect. The default is immediate.

Default: immediate

customerId

string · pattern: ^[0-7][0-9A-HJKMNP-T…

The ID of the customer. Provide either the key or ID. Has presedence over the key.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

customerKey

string · minLength: 1 · maxLength: 256

The key of the customer. Provide either the key or ID.

billingAnchor

string · date-time

The billing anchor of the subscription. The provided date will be normalized according to the billing cadence to the nearest recurrence before start time. If not provided, the subscription start time will be used.

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

SubscriptionEdit

Subscription edit input.

SubscriptionEditOperation[] · maxItems: 100 · required

Batch processing commands for manipulating running subscriptions. The key format is /phases/{phaseKey} or /phases/{phaseKey}/items/{itemKey}.

Whether the billing period should be restarted.Timing configuration to allow for the changes to take effect at different times.

SubscriptionEditOperation

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · op="add_item" · requires: phaseKey, rateCard
	type = object · op="remove_item" · requires: phaseKey, itemKey
	type = object · op="add_phase" · requires: phase
	type = object · op="remove_phase" · requires: phaseKey, shift
	type = object · op="stretch_phase" · requires: phaseKey, extendBy
	type = object · op="unschedule_edit"

Properties for Variant 1:

Add a new item to a phase.

EditSubscriptionAddItem

op

string · enum · required

Enum values:

add_item

phaseKey

string · required

RateCard · required

A rate card defines the pricing and entitlement of a feature or service.

SubscriptionEntitlements

SubscriptionEntitlements describes entitlements for a specific subscription.

subscriptionId

string · readOnly · required

The subscription ID these entitlements belong to.

object · readOnly · required

Map of entitlements for this subscription. The key is the feature key, the value is the entitlement value.

object · readOnly

Payment status details for the subscription's current phase. Use this to determine if access should be granted based on payment state.

SubscriptionErrorExtensions

Error extensions for the Subscription Errors.

ErrorExtension[] · required

SubscriptionExpanded

Expanded subscription

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

activeFrom

string · date-time · required

The cadence start of the resource.

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

status

string · enum · readOnly · required

The status of the subscription.

Enum values:

active

inactive

canceled

scheduled

customerId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The customer ID of the subscription.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

currency

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

The currency code of the subscription. Will be revised once we add multi currency support.

Example: USD

Default: USD

billingCadence

string · duration · readOnly · required

The billing cadence for the subscriptions. Defines how often customers are billed using ISO8601 duration format. Examples: "P1M" (monthly), "P3M" (quarterly), "P1Y" (annually).

Example: P1M

billingAnchor

string · date-time · readOnly · required

The normalizedbilling anchor of the subscription.

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

SubscriptionPhaseExpanded[] · required

The phases of the subscription.

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

activeTo

string · date-time

The cadence end of the resource.

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

object · readOnly

Set of key-value pairs managed by the system. Cannot be modified by user.

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

object

The plan of the subscription.

object · readOnly

The pro-rating configuration for the subscriptions.

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

object

Alignment details enriched with the current billing period.

SubscriptionItem

The actual contents of the Subscription, what the user gets, what they pay, etc...

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

activeFrom

string · date-time · required

The cadence start of the resource.

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

key

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

The identifier of the RateCard. SubscriptionItem/RateCard can be identified, it has a reference:

If a Feature is associated with the SubscriptionItem, it is identified by the Feature 1.1 It can be an ID reference, for an exact version of the Feature (Features can change across versions) 1.2 It can be a Key reference, which always refers to the latest (active or inactive) version of a Feature
If a Feature is not associated with the SubscriptionItem, it is referenced by the Price

We say "referenced by the Price" regardless of how a price itself is referenced, it colloquially makes sense to say "paying the same price for the same thing". In practice this should be derived from what's printed on the invoice line-item.

billingCadence

string | null · duration · required

The billing cadence of the rate card. When null, the rate card is a one-time purchase.

object · required

The price of the rate card. When null, the feature or service is free.

Example: {"type":"flat","amount":"100","paymentTerm":"in_arrears"}

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

activeTo

string · date-time

The cadence end of the resource.

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

featureKey

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

The feature's key (if present).

object

The discounts applied to the rate card.

object

Describes what access is gained via the SubscriptionItem

object

The tax config of the Subscription Item. When undefined, the tax config of the feature or the default tax config of the plan is used.

SubscriptionItemIncluded

Included contents like Entitlement, or the Feature.

object · required

The feature the customer is entitled to use.

object

The entitlement of the Subscription Item.

SubscriptionPaginatedResponse

Paginated response

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

Subscription[] · required

The items in the current page.

SubscriptionPaymentStatus

Payment status details for a subscription phase. Provides status, timestamps, and whether this is the subscription's first payment.

status

string · enum · readOnly · required

The current payment status.

Enum values:

paid

not_required

pending

failed

uncollectible

isFirstPayment

boolean · readOnly · required

True if this subscription has never had a successful payment. Useful for distinguishing "first payment pending" from "renewal payment failed".

maxPaymentOverdueDays

integer · readOnly · required

Number of days after lastPaymentFailedAt before access is revoked. Default is 3. Applies only to renewal payment failures (isFirstPayment: false). For first payment failures, access is blocked immediately regardless of this value.

Example: 3

lastPaymentSucceededAt

string · date-time · readOnly

Timestamp when payment was last successfully collected.

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

lastPaymentFailedAt

string · date-time · readOnly

Timestamp when payment last failed (for implementing grace periods).

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

SubscriptionPaymentStatusType

string · enum

Enum values:

paid

not_required

pending

failed

uncollectible

Payment status values for a subscription phase.

SubscriptionPhase

Subscription phase, analogous to plan phases.

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 locally unique identifier for the resource.

activeFrom

string · date-time · required

The time from which the phase is active.

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

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

The discounts on the plan.

activeTo

string · date-time

The until which the Phase is active.

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

SubscriptionPhaseCreate

Subscription phase create input.

startAfter

string | null · duration · required

Interval after the subscription starts to transition to the phase. When null, the phase starts immediately after the subscription starts.

Example: P1Y

key

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

A locally unique identifier for the phase.

name

string · required

The name of the phase.

duration

string · duration

The intended duration of the new phase. Duration is required when the phase will not be the last phase.

Example: P1M

object

The discounts on the plan.

description

string

The description of the phase.

SubscriptionPhaseExpanded

Expanded subscription phase

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 locally unique identifier for the resource.

activeFrom

string · date-time · required

The time from which the phase is active.

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

SubscriptionItem[] · required

The items of the phase. The structure is flattened to better conform to the Plan API. The timelines are flattened according to the following rules:

for the current phase, the items contains only the active item for each key
for past phases, the items contains only the last item for each key
for future phases, the items contains only the first version of the item for each key

object · required

Includes all versions of the items on each key, including all edits, scheduled changes, etc...

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

The discounts on the plan.

activeTo

string · date-time

The until which the Phase is active.

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

SubscriptionStatus

string · enum

Enum values:

active

inactive

canceled

scheduled

Subscription status.

SubscriptionTiming

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string

Properties for Variant 1:

SubscriptionTimingEnum · enum

Enum values:

immediate

next_billing_cycle

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

SubscriptionTimingEnum

string · enum

Enum values:

immediate

next_billing_cycle

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

TaxBehavior

string · enum

Enum values:

inclusive

exclusive

Tax behavior.

This enum is used to specify whether tax is included in the price or excluded from the price.

TaxCalculationItem

TaxCalculationItem represents a single line item for tax calculation.

amount

integer · min: 0 · required

The amount in the smallest currency unit (e.g. cents for USD).

TaxCalculationItemResult

TaxCalculationItemResult contains the tax calculation result for a single line item.

amount

integer · required

The original amount before tax in the smallest currency unit.

taxAmount

integer · required

The tax amount for this item in the smallest currency unit.

TaxConfig

Set of provider specific tax configs.

behavior

string · enum

Tax behavior.

If not specified the billing profile is used to determine the tax behavior. If not specified in the billing profile, the provider's default behavior is used.

Enum values:

inclusive

exclusive

object

Stripe tax config.

object

Custom invoicing tax config.

TaxItem

TaxItem represents a single jurisdiction's tax in the breakdown.

jurisdiction

string · required

Two-letter country code (ISO 3166-1 alpha-2) of the jurisdiction imposing the tax (e.g. "GB").

rate

string · required

The tax rate as a percentage string (e.g. "20.0").

amount

integer · required

The tax amount for this jurisdiction in the smallest currency unit.

taxType

string · required

The type of tax (e.g. "vat", "sales_tax", "gst").

TieredPrice

Tiered price.

type

string · enum · required

The type of the price.

One of: flat, unit, or tiered.

Enum values:

tiered

mode

string · enum · required

Defines if the tiering mode is volume-based or graduated:

In volume-based tiering, the maximum quantity within a period determines the per unit price.
In graduated tiering, pricing can change as the quantity grows.

Enum values:

volume

graduated

PriceTier[] · minItems: 1 · required

The tiers of the tiered price. At least one price component is required in each tier.

TieredPriceMode

string · enum

Enum values:

volume

graduated

The mode of the tiered price.

TieredPriceWithCommitments

Tiered price with spend commitments.

type

string · enum · required

The type of the price.

One of: flat, unit, or tiered.

Enum values:

tiered

mode

string · enum · required

Defines if the tiering mode is volume-based or graduated:

In volume-based tiering, the maximum quantity within a period determines the per unit price.
In graduated tiering, pricing can change as the quantity grows.

Enum values:

volume

graduated

PriceTier[] · minItems: 1 · required

The tiers of the tiered price. At least one price component is required in each tier.

minimumAmount

string · pattern: ^\-?[0-9]+(\.[0-9]+)…

The customer is committed to spend at least the amount.

maximumAmount

string · pattern: ^\-?[0-9]+(\.[0-9]+)…

The customer is limited to spend at most the amount.

ULIDOrExternalKey

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = string
	type = string

Properties for Variant 1:

string · pattern: ^[0-7][0-9A-HJKMNP-T…

ULID (Universally Unique Lexicographically Sortable Identifier).

Example: 01G65Z755AFWAKHE12NY0CQ9FH

UnauthorizedProblemResponse

The request has not been applied because it lacks valid authentication credentials for the target resource.

type

string · uri · required

Type contains a URI that identifies the problem type.

Example: about:blank

Default: about:blank

title

string · required

A a short, human-readable summary of the problem type.

Example: Bad Request

detail

string · required

A human-readable explanation specific to this occurrence of the problem.

Example: The request body must be a JSON object.

instance

string · uri · required

A URI reference that identifies the specific occurrence of the problem.

Example: urn:request:local/JMOlctsKV8-000001

status

integer · int16 · min: 400 · max: 599

The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 400

object

Additional properties specific to the problem type may be present.

Example: {"validationErrors":[{"code":"validation_error","message":"Validation error"}],"otherAttribute":"otherValue"}

No data returned

UnexpectedProblemResponse

A Problem Details object (RFC 7807). Additional properties specific to the problem type may be present.

type

string · uri · required

Type contains a URI that identifies the problem type.

Example: about:blank

Default: about:blank

title

string · required

A a short, human-readable summary of the problem type.

Example: Bad Request

detail

string · required

A human-readable explanation specific to this occurrence of the problem.

Example: The request body must be a JSON object.

instance

string · uri · required

A URI reference that identifies the specific occurrence of the problem.

Example: urn:request:local/JMOlctsKV8-000001

status

integer · int16 · min: 400 · max: 599

The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 400

object

Additional properties specific to the problem type may be present.

Example: {"validationErrors":[{"code":"validation_error","message":"Validation error"}],"otherAttribute":"otherValue"}

No data returned

UnitPrice

Unit price.

type

string · enum · required

The type of the price.

Enum values:

unit

amount

string · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The amount of the unit price.

UnitPriceWithCommitments

Unit price with spend commitments.

type

string · enum · required

The type of the price.

Enum values:

unit

amount

string · pattern: ^\-?[0-9]+(\.[0-9]+)… · required

The amount of the unit price.

minimumAmount

string · pattern: ^\-?[0-9]+(\.[0-9]+)…

The customer is committed to spend at least the amount.

maximumAmount

string · pattern: ^\-?[0-9]+(\.[0-9]+)…

The customer is limited to spend at most the amount.

ValidationError

Validation errors providing detailed description of the issue.

field

string · readOnly · required

The path to the field.

Example: addons/pro/ratecards/token/featureKey

code

string · readOnly · required

The machine readable description of the error.

Example: invalid_feature_key

message

string · readOnly · required

The human readable description of the error.

Example: not found feature by key

object · readOnly

Additional attributes.

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

ValidationErrorProblemResponse

A BadRequestError with a validationErrors extension.

type

string · uri · required

Type contains a URI that identifies the problem type.

Example: about:blank

Default: about:blank

title

string · required

A a short, human-readable summary of the problem type.

Example: Bad Request

detail

string · required

A human-readable explanation specific to this occurrence of the problem.

Example: The request body must be a JSON object.

instance

string · uri · required

A URI reference that identifies the specific occurrence of the problem.

Example: urn:request:local/JMOlctsKV8-000001

status

integer · int16 · min: 400 · max: 599

The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 400

object · readOnly

Validation issues.

ValidationIssue

ValidationIssue captures any validation issues related to the invoice. Issues with severity "critical" will prevent the invoice from being issued.

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

id

string · readOnly · pattern: ^[0-7][0-9A-HJKMNP-T… · required

ID of the charge or discount.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

severity

string · enum · readOnly · required

The severity of the issue.

Enum values:

critical

warning

component

string · readOnly · required

Component reporting the issue.

message

string · readOnly · required

A human-readable description of the issue.

deletedAt

string · date-time · readOnly

Timestamp of when the resource was permanently deleted.

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

field

string · readOnly

The field that the issue is related to, if available in JSON path format.

code

string · readOnly

Machine indentifiable code for the issue, if available.

object · readOnly

Additional context for the issue.

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

ValidationIssueSeverity

string · enum

Enum values:

critical

warning

ValidationIssueSeverity describes the severity of a validation issue.

Issues with severity "critical" will prevent the invoice from being issued.

VoidInvoiceActionCreate

InvoiceVoidAction describes how to handle the voided line items.

percentage

number · double · required

How much of the total line items to be voided? (e.g. 100% means all charges are voided)

Example: 50

object · required

The action to take on the line items.

VoidInvoiceActionCreateItem

InvoiceVoidAction describes how to handle the voided line items.

percentage

number · double · required

How much of the total line items to be voided? (e.g. 100% means all charges are voided)

Example: 50

object · required

The action to take on the line items.

VoidInvoiceActionInput

Request to void an invoice

object · required

The action to take on the voided line items.

reason

string · required

The reason for voiding the invoice.

array | null

Per line item overrides for the action.

If not specified, the action will be applied to all line items.

VoidInvoiceActionLineOverride

VoidInvoiceLineOverride describes how to handle a specific line item in the invoice when voiding.

lineId

string · pattern: ^[0-7][0-9A-HJKMNP-T… · required

The line item ID to override.

Example: 01G65Z755AFWAKHE12NY0CQ9FH

object · required

The action to take on the line item.

VoidInvoiceLineActionCreate

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · type="discard"
	type = object · type="pending"

Properties for Variant 1:

VoidInvoiceLineDiscardAction describes how to handle the voidied line item in the invoice.

VoidInvoiceLineDiscardAction

type

string · enum · required

The action to take on the line item.

Enum values:

discard

VoidInvoiceLineActionCreateItem

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · type="discard"
	type = object · type="pending"

Properties for Variant 1:

VoidInvoiceLineDiscardAction describes how to handle the voidied line item in the invoice.

VoidInvoiceLineDiscardAction

type

string · enum · required

The action to take on the line item.

Enum values:

discard

VoidInvoiceLineActionType

string · enum

Enum values:

discard

pending

VoidInvoiceLineActionType describes how to handle the voidied line item in the invoice.

VoidInvoiceLineDiscardAction

VoidInvoiceLineDiscardAction describes how to handle the voidied line item in the invoice.

type

string · enum · required

The action to take on the line item.

Enum values:

discard

VoidInvoiceLinePendingActionCreate

VoidInvoiceLinePendingAction describes how to handle the voidied line item in the invoice.

type

string · enum · required

The action to take on the line item.

Enum values:

pending

nextInvoiceAt

string · date-time

The time at which the line item should be invoiced again.

If not provided, the line item will be re-invoiced now.

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

VoidInvoiceLinePendingActionCreateItem

VoidInvoiceLinePendingAction describes how to handle the voidied line item in the invoice.

type

string · enum · required

The action to take on the line item.

Enum values:

pending

nextInvoiceAt

string · date-time

The time at which the line item should be invoiced again.

If not provided, the line item will be re-invoiced now.

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

WindowSize

string · enum

Enum values:

MINUTE

HOUR

DAY

MONTH

Aggregation window size.

WindowedBalanceHistory

The windowed balance history.

BalanceHistoryWindow[] · required

The windowed balance history.

It only returns rows for windows where there was usage.
The windows are inclusive at their start and exclusive at their end.
The last window may be smaller than the window size and is inclusive at both ends.

GrantBurnDownHistorySegment[] · required

Grant burndown history.

SubscriptionAccessUpdate

Response payload returned by the block-access and unblock-access endpoints.

subscriptionId

string · readOnly · required

The subscription ID whose access state was updated.

accessBlocked

boolean · readOnly · required

The new access-blocked state.