Create Subscription
{
"accountId": "cus_0000000000000000000000",
"name": "Waystar Royco - 2024",
"description": "Initial contract for Waystar Royco",
"purchaseOrderNumber": "WRO-2024-001",
"contractStartDate": "2024-02-01T00:00:00Z",
"currency": "USD",
"activationMode": "manual",
"initialVersion": {
"items": [
{
"priceId": "price_0000000000000000000000",
"correlationId": "first-item"
},
{
"price": {
"productId": "prod_0000000000000000000000",
"type": "unit",
"unitAmount": "99.99"
},
"correlationId": "second-item"
},
{
"price": {
"productId": "prod_0000000000000000000000",
"type": "tiered",
"tiers": [
{
"minUnits": 1,
"maxUnits": 100,
"unitAmount": "0.10",
"fixedAmount": "0.00"
},
{
"minUnits": 100,
"maxUnits": 200,
"unitAmount": "0.09",
"fixedAmount": "0.00"
},
{
"minUnits": 200,
"maxUnits": 300,
"unitAmount": "0.08",
"fixedAmount": "0.00"
},
{
"minUnits": 300,
"maxUnits": null,
"unitAmount": "0.07",
"fixedAmount": "0.00"
}
]
}
},
{
"price": {
"productId": "prod_0000000000000000000000",
"type": "fixed",
"unitAmount": "24.99",
"quantity": "2"
}
},
{
"bundle": {
"name": "Transactions Bundle",
"correlationId": "transactions-bundle",
"prices": [
{
"priceId": "price_0000000000000000000000"
},
{
"priceId": "price_0000000000000000000000"
}
]
}
}
],
"thresholds": [
{
"type": "max",
"value": "10000.00",
"interval": "month",
"scope": {
"type": "global"
}
},
{
"type": "min",
"value": "1000.00",
"interval": "month",
"scope": {
"type": "items",
"correlationIds": ["transactions-bundle"]
}
}
],
"discounts": [
{
"type": "percentage",
"value": "10",
"scope": {
"type": "items",
"correlationIds": ["first-item", "second-item"]
}
}
]
},
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z",
"canceledAt": null,
"completedAt": null
}
{
"id": "sub_8Np7AWxL4QvkprmjmloXuT",
"customerId": "cus_0000000000000000000000",
"name": "Waystar Royco - 2024",
"description": "Initial contract for Waystar Royco",
"purchaseOrderNumber": "WRO-2024-001",
"contractStartDate": "2024-02-01T00:00:00Z",
"currency": "USD",
"status": "draft",
"activationMode": "manual",
"currentVersion": {
"id": "subv_9Ak3BwqR7TzvlsqnkmpYvU",
"effectiveStartDate": "2024-02-01T00:00:00Z",
"effectiveEndDate": null,
"status": "draft",
"items": [
{
"priceId": "price_0000000000000000000000",
"type": "unit",
"unitAmount": "199.99"
},
{
"priceId": "price_0000000000000001111111",
"type": "unit",
"unitAmount": "99.99"
},
{
"priceId": "price_0000000000000002222222",
"type": "tiered",
"tiers": [
{
"minUnits": 1,
"maxUnits": 100,
"unitAmount": "0.10",
"fixedAmount": "0.00"
},
{
"minUnits": 100,
"maxUnits": 200,
"unitAmount": "0.09",
"fixedAmount": "0.00"
},
{
"minUnits": 200,
"maxUnits": 300,
"unitAmount": "0.08",
"fixedAmount": "0.00"
},
{
"minUnits": 300,
"maxUnits": null,
"unitAmount": "0.07",
"fixedAmount": "0.00"
}
]
},
{
"priceId": "price_0000000000000003333333",
"type": "fixed",
"unitAmount": "24.99",
"quantity": "2"
},
{
"bundleId": "bundle_0000000000000001111111",
"prices": [
{
"priceId": "price_0000000000000004444444",
"type": "unit",
"unitAmount": "49.99"
},
{
"priceId": "price_0000000000000005555555",
"type": "unit",
"unitAmount": "29.99"
}
]
}
],
"thresholds": [
{
"id": "subt_0000000000000001111111",
"type": "max",
"value": "10000.00",
"interval": "month",
"scope": {
"type": "global"
}
},
{
"id": "subt_0000000000000002222222",
"type": "min",
"value": "1000.00",
"interval": "month",
"scope": {
"type": "items",
"ids": ["bundle_0000000000000001111111"]
}
}
],
"discounts": [
{
"id": "subd_0000000000000001111111",
"type": "percentage",
"value": "10",
"scope": {
"type": "items",
"ids": ["price_0000000000000000000000", "price_0000000000000001111111"]
}
}
]
},
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z",
"canceledAt": null,
"completedAt": null
}
Using this endpoint, you create both the core subscription object and the initial version, this is equivalent to making two calls to create the subscription, then add a new version.
A subscription consists of the core subscription data, along with one to many versions. For a simple subscription it’s possible you may only ever have one version, but often you will end up having multiple versions.
- Renewals: each renewal will be a separate phase to the subscription
- Upgrades/downgrades: each time a change is made to the subscription this will create a new version
Request
{
"accountId": "cus_0000000000000000000000",
"name": "Waystar Royco - 2024",
"description": "Initial contract for Waystar Royco",
"purchaseOrderNumber": "WRO-2024-001",
"contractStartDate": "2024-02-01T00:00:00Z",
"currency": "USD",
"activationMode": "manual",
"initialVersion": {
"items": [
{
"priceId": "price_0000000000000000000000",
"correlationId": "first-item"
},
{
"price": {
"productId": "prod_0000000000000000000000",
"type": "unit",
"unitAmount": "99.99"
},
"correlationId": "second-item"
},
{
"price": {
"productId": "prod_0000000000000000000000",
"type": "tiered",
"tiers": [
{
"minUnits": 1,
"maxUnits": 100,
"unitAmount": "0.10",
"fixedAmount": "0.00"
},
{
"minUnits": 100,
"maxUnits": 200,
"unitAmount": "0.09",
"fixedAmount": "0.00"
},
{
"minUnits": 200,
"maxUnits": 300,
"unitAmount": "0.08",
"fixedAmount": "0.00"
},
{
"minUnits": 300,
"maxUnits": null,
"unitAmount": "0.07",
"fixedAmount": "0.00"
}
]
}
},
{
"price": {
"productId": "prod_0000000000000000000000",
"type": "fixed",
"unitAmount": "24.99",
"quantity": "2"
}
},
{
"bundle": {
"name": "Transactions Bundle",
"correlationId": "transactions-bundle",
"prices": [
{
"priceId": "price_0000000000000000000000"
},
{
"priceId": "price_0000000000000000000000"
}
]
}
}
],
"thresholds": [
{
"type": "max",
"value": "10000.00",
"interval": "month",
"scope": {
"type": "global"
}
},
{
"type": "min",
"value": "1000.00",
"interval": "month",
"scope": {
"type": "items",
"correlationIds": ["transactions-bundle"]
}
}
],
"discounts": [
{
"type": "percentage",
"value": "10",
"scope": {
"type": "items",
"correlationIds": ["first-item", "second-item"]
}
}
]
},
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z",
"canceledAt": null,
"completedAt": null
}
The unique identifier for the customer. This is typically an Alguna customer ID.
The name of the subscription, e.g., “Waystar Royco - 2024”.
A brief description of the subscription. For example, “Initial contract for Waystar Royco”.
The purchase order number associated with this subscription.
The start date and time of the contract in ISO 8601 format. This is when the subscription becomes effective.
The currency used for billing, e.g., “USD”.
The mode of activation for the subscription. Valid values might include “manual” or “automatic”.
Contains the details of the initial version of the subscription, including pricing items, thresholds, and discounts.
An array of pricing items for this subscription version. Each item can reference an existing price via priceId, define a new price using the price key, or group prices as a bundle.
The identifier of an existing price. Use this field if the price has been created beforehand.
The pricing details used to create a new price on the fly.
The product identifier associated with the price.
The pricing model type. Valid values include unit, tiered, and fixed.
The amount charged per unit. Required for unit and fixed pricing.
The tier definitions for tiered pricing.
The minimum number of units for this tier.
The maximum number of units for this tier. A value of null indicates no upper limit.
The price per unit within this tier.
A fixed charge applied in addition to the unit amount, if applicable.
The quantity to be billed for fixed pricing models.
A bundle grouping multiple pricing items. Bundles allow logical grouping of prices.
An ephemeral identifier for the item, used to correlate it with thresholds or discounts.
An array of pricing thresholds applied to the subscription version.
The threshold type. Valid values include max and min.
The threshold value.
The time interval for the threshold, such as month.
An array of discounts applied to the subscription version.
The discount type, such as percentage.
The discount value.
The timestamp when the subscription was created.
The timestamp when the subscription was last updated.
The timestamp when the subscription was canceled. If the subscription is active, this field is null.
The timestamp when the subscription was completed. If the subscription is still in progress, this field is null.
Response
{
"id": "sub_8Np7AWxL4QvkprmjmloXuT",
"customerId": "cus_0000000000000000000000",
"name": "Waystar Royco - 2024",
"description": "Initial contract for Waystar Royco",
"purchaseOrderNumber": "WRO-2024-001",
"contractStartDate": "2024-02-01T00:00:00Z",
"currency": "USD",
"status": "draft",
"activationMode": "manual",
"currentVersion": {
"id": "subv_9Ak3BwqR7TzvlsqnkmpYvU",
"effectiveStartDate": "2024-02-01T00:00:00Z",
"effectiveEndDate": null,
"status": "draft",
"items": [
{
"priceId": "price_0000000000000000000000",
"type": "unit",
"unitAmount": "199.99"
},
{
"priceId": "price_0000000000000001111111",
"type": "unit",
"unitAmount": "99.99"
},
{
"priceId": "price_0000000000000002222222",
"type": "tiered",
"tiers": [
{
"minUnits": 1,
"maxUnits": 100,
"unitAmount": "0.10",
"fixedAmount": "0.00"
},
{
"minUnits": 100,
"maxUnits": 200,
"unitAmount": "0.09",
"fixedAmount": "0.00"
},
{
"minUnits": 200,
"maxUnits": 300,
"unitAmount": "0.08",
"fixedAmount": "0.00"
},
{
"minUnits": 300,
"maxUnits": null,
"unitAmount": "0.07",
"fixedAmount": "0.00"
}
]
},
{
"priceId": "price_0000000000000003333333",
"type": "fixed",
"unitAmount": "24.99",
"quantity": "2"
},
{
"bundleId": "bundle_0000000000000001111111",
"prices": [
{
"priceId": "price_0000000000000004444444",
"type": "unit",
"unitAmount": "49.99"
},
{
"priceId": "price_0000000000000005555555",
"type": "unit",
"unitAmount": "29.99"
}
]
}
],
"thresholds": [
{
"id": "subt_0000000000000001111111",
"type": "max",
"value": "10000.00",
"interval": "month",
"scope": {
"type": "global"
}
},
{
"id": "subt_0000000000000002222222",
"type": "min",
"value": "1000.00",
"interval": "month",
"scope": {
"type": "items",
"ids": ["bundle_0000000000000001111111"]
}
}
],
"discounts": [
{
"id": "subd_0000000000000001111111",
"type": "percentage",
"value": "10",
"scope": {
"type": "items",
"ids": ["price_0000000000000000000000", "price_0000000000000001111111"]
}
}
]
},
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z",
"canceledAt": null,
"completedAt": null
}
The unique identifier for the subscription.
The identifier of the customer associated with the subscription.
The name of the subscription, e.g., "Waystar Royco - 2024".
A brief description of the subscription, such as "Initial contract for Waystar Royco".
The purchase order number associated with this subscription.
The effective start date and time of the contract in ISO 8601 format.
The currency used for billing, e.g., "USD".
The current status of the subscription (e.g., draft, active).
The activation mode for the subscription, such as manual or automatic.
Details regarding the current version of the subscription.
The unique identifier for the current version.
The start date and time when the current version becomes effective.
The end date and time when the current version expires, if applicable.
The status of the current version (e.g., draft, active).
An array of pricing items included in the current version.
The identifier of the price for the item. Present for standard pricing items.
The pricing model type. Valid values include unit, tiered, and fixed.
The unit amount charged. Applicable to unit and fixed pricing models.
The tiered pricing structure for the item. This field is used only for tiered pricing.
The quantity to be billed for fixed pricing models.
The identifier for the bundle if this item represents a bundle of prices.
An array of thresholds applied to the subscription version.
The unique identifier for the threshold.
The threshold type, such as max or min.
The threshold value.
The time interval for the threshold, for example, month.
An array of discounts applied to the subscription version.
The unique identifier for the discount.
The discount type, e.g., percentage.
The discount value.
The timestamp when the subscription was created.
The timestamp when the subscription was last updated.
The timestamp when the subscription was canceled. If the subscription is active, this field is null.
The timestamp when the subscription was completed. If the subscription is still in progress, this field is null.
{
"accountId": "cus_0000000000000000000000",
"name": "Waystar Royco - 2024",
"description": "Initial contract for Waystar Royco",
"purchaseOrderNumber": "WRO-2024-001",
"contractStartDate": "2024-02-01T00:00:00Z",
"currency": "USD",
"activationMode": "manual",
"initialVersion": {
"items": [
{
"priceId": "price_0000000000000000000000",
"correlationId": "first-item"
},
{
"price": {
"productId": "prod_0000000000000000000000",
"type": "unit",
"unitAmount": "99.99"
},
"correlationId": "second-item"
},
{
"price": {
"productId": "prod_0000000000000000000000",
"type": "tiered",
"tiers": [
{
"minUnits": 1,
"maxUnits": 100,
"unitAmount": "0.10",
"fixedAmount": "0.00"
},
{
"minUnits": 100,
"maxUnits": 200,
"unitAmount": "0.09",
"fixedAmount": "0.00"
},
{
"minUnits": 200,
"maxUnits": 300,
"unitAmount": "0.08",
"fixedAmount": "0.00"
},
{
"minUnits": 300,
"maxUnits": null,
"unitAmount": "0.07",
"fixedAmount": "0.00"
}
]
}
},
{
"price": {
"productId": "prod_0000000000000000000000",
"type": "fixed",
"unitAmount": "24.99",
"quantity": "2"
}
},
{
"bundle": {
"name": "Transactions Bundle",
"correlationId": "transactions-bundle",
"prices": [
{
"priceId": "price_0000000000000000000000"
},
{
"priceId": "price_0000000000000000000000"
}
]
}
}
],
"thresholds": [
{
"type": "max",
"value": "10000.00",
"interval": "month",
"scope": {
"type": "global"
}
},
{
"type": "min",
"value": "1000.00",
"interval": "month",
"scope": {
"type": "items",
"correlationIds": ["transactions-bundle"]
}
}
],
"discounts": [
{
"type": "percentage",
"value": "10",
"scope": {
"type": "items",
"correlationIds": ["first-item", "second-item"]
}
}
]
},
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z",
"canceledAt": null,
"completedAt": null
}
{
"id": "sub_8Np7AWxL4QvkprmjmloXuT",
"customerId": "cus_0000000000000000000000",
"name": "Waystar Royco - 2024",
"description": "Initial contract for Waystar Royco",
"purchaseOrderNumber": "WRO-2024-001",
"contractStartDate": "2024-02-01T00:00:00Z",
"currency": "USD",
"status": "draft",
"activationMode": "manual",
"currentVersion": {
"id": "subv_9Ak3BwqR7TzvlsqnkmpYvU",
"effectiveStartDate": "2024-02-01T00:00:00Z",
"effectiveEndDate": null,
"status": "draft",
"items": [
{
"priceId": "price_0000000000000000000000",
"type": "unit",
"unitAmount": "199.99"
},
{
"priceId": "price_0000000000000001111111",
"type": "unit",
"unitAmount": "99.99"
},
{
"priceId": "price_0000000000000002222222",
"type": "tiered",
"tiers": [
{
"minUnits": 1,
"maxUnits": 100,
"unitAmount": "0.10",
"fixedAmount": "0.00"
},
{
"minUnits": 100,
"maxUnits": 200,
"unitAmount": "0.09",
"fixedAmount": "0.00"
},
{
"minUnits": 200,
"maxUnits": 300,
"unitAmount": "0.08",
"fixedAmount": "0.00"
},
{
"minUnits": 300,
"maxUnits": null,
"unitAmount": "0.07",
"fixedAmount": "0.00"
}
]
},
{
"priceId": "price_0000000000000003333333",
"type": "fixed",
"unitAmount": "24.99",
"quantity": "2"
},
{
"bundleId": "bundle_0000000000000001111111",
"prices": [
{
"priceId": "price_0000000000000004444444",
"type": "unit",
"unitAmount": "49.99"
},
{
"priceId": "price_0000000000000005555555",
"type": "unit",
"unitAmount": "29.99"
}
]
}
],
"thresholds": [
{
"id": "subt_0000000000000001111111",
"type": "max",
"value": "10000.00",
"interval": "month",
"scope": {
"type": "global"
}
},
{
"id": "subt_0000000000000002222222",
"type": "min",
"value": "1000.00",
"interval": "month",
"scope": {
"type": "items",
"ids": ["bundle_0000000000000001111111"]
}
}
],
"discounts": [
{
"id": "subd_0000000000000001111111",
"type": "percentage",
"value": "10",
"scope": {
"type": "items",
"ids": ["price_0000000000000000000000", "price_0000000000000001111111"]
}
}
]
},
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z",
"canceledAt": null,
"completedAt": null
}