Create Product

POST /products

cURL

curl -X POST https://api.autumnai.com/products \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "Pro Product",
    "name": "Pro Plan",
    "is_add_on": false,
    "is_default": false,
    "items": [
      {
        "price": 20,
        "interval": "month"
      },
      {
        "feature_id": "messages",
        "included_usage": 1000,
        "price": 0.5,
        "interval": "month",
        "usage_model": "pay_per_use"
      }
    ],
    "free_trial": {
      "duration": "day",
      "length": 7,
      "unique_fingerprint": false,
      "card_required": true
    }
  }'

import { Autumn } from '@autumnai/node-sdk';

const autumn = new Autumn({
  apiKey: process.env.AUTUMN_API_KEY,
});

const product = await autumn.products.create({
  id: 'Pro Product',
  name: 'Pro Plan',
  is_add_on: false,
  is_default: false,
  items: [
    {
      price: 20,
      interval: 'month',
    },
    {
      feature_id: 'messages',
      included_usage: 1000,
      price: 0.5,
      interval: 'month',
      usage_model: 'pay_per_use',
    },
  ],
  free_trial: {
    duration: 'day',
    length: 7,
    unique_fingerprint: false,
    card_required: true,
  },
});

from autumn import Autumn

autumn = Autumn(api_key="YOUR_API_KEY")

product = autumn.products.create(
    id="Pro Product",
    name="Pro Plan",
    is_add_on=False,
    is_default=False,
    items=[
        {
            "price": 20,
            "interval": "month",
        },
        {
            "feature_id": "messages",
            "included_usage": 1000,
            "price": 0.5,
            "interval": "month",
            "usage_model": "pay_per_use",
        },
    ],
    free_trial={
        "duration": "day",
        "length": 7,
        "unique_fingerprint": False,
        "card_required": True,
    },
)

200

{
  "id": "Pro Product",
  "name": "Pro Plan",
  "group": null,
  "env": "sandbox",
  "is_add_on": false,
  "is_default": false,
  "archived": false,
  "version": 1,
  "created_at": 1761296829908,
  "items": [
    {
      "type": "price",
      "feature_id": null,
      "interval": "month",
      "interval_count": 1,
      "price": 20,
      "display": {
        "primary_text": "$20",
        "secondary_text": "per month"
      }
    },
    {
      "type": "priced_feature",
      "feature_id": "messages",
      "included_usage": 1000,
      "interval": "month",
      "interval_count": 1,
      "price": 0.5,
      "usage_model": "pay_per_use",
      "billing_units": 1000,
      "reset_usage_when_enabled": true,
      "entity_feature_id": null,
      "display": {
        "primary_text": "1,000 Messages",
        "secondary_text": "then $0.5 per 1,000 Messages"
      }
    }
  ],
  "free_trial": {
    "duration": "day",
    "length": 7,
    "unique_fingerprint": false,
    "card_required": true
  },
  "base_variant_id": null,
  "scenario": "new"
}

Creates a new product with pricing plans and feature configurations.

Request Body

id · string · required

The ID of the product. Used to identify the product in other API calls like checkout or update product.

Must match the pattern: ^[a-zA-Z0-9_-]+$

name · string · required

The name of the product.

description · string

The description of the product.

is_add_on · boolean · default: false

Whether the product is an add-on. Add-on products can be attached multiple times and don’t go through upgrade/downgrade flows.

is_default · boolean · default: false

Whether the product is the default product. Default products are enabled by default for new customers.

group · string

Product group which this product belongs to. Products within a group have upgrade/downgrade logic when the customer moves between them.

items · array

Array of product items that define the product’s features and pricing.

Show Product Item Object

type · enum

The type of the product item.

• price - Fixed price item
• priced_feature - Feature with pricing
• feature - Feature without pricing

feature_id · string

The feature ID of the product item. Should be null for fixed price items.

included_usage · number | 'inf'

The amount of usage included for this feature (per interval).

interval · enum

The reset or billing interval of the product item. If null, feature will have no reset date, and if there’s a price, it will be billed one-off.

• day
• week
• month
• year

interval_count · number

Interval count of the feature (e.g., 3 for every 3 months).

price · number

The price of the product item. Should be null if tiered pricing is set.

usage_model · enum

Whether the feature should be prepaid upfront or billed for how much they use at the end of billing period.

• prepaid - Customer pays upfront for a set quantity
• pay_per_use - Customer pays based on actual usage

billing_units · number

The billing units of the product item (e.g., $1 for 30 credits).

tiers · array

Tiered pricing for the product item. Not applicable for fixed price items.

Show Tier Object

to · number | 'inf' · required

The maximum amount of usage for this tier.

amount · number · required

The price of the product item for this tier.

flat_amount · number

A flat fee charged for this tier, in addition to the per-unit amount.

tier_behavior · enum

The type of tiered pricing: graduated or volume-based.

• graduated - Split across bands
• volume - Flat rate for the matched tier

reset_usage_when_enabled · boolean

Whether the usage should be reset when the product is enabled.

entity_feature_id · string

The feature ID of the entity (like seats) to track sub-balances for.

config · object

Configuration for rollover and proration behavior.

Show Config Object

rollover · object

Rollover configuration.

Show Rollover Object

max · number

Maximum amount that can be rolled over.

duration · enum · default: "month"

Duration type for rollover expiry.

• day
• week
• month
• year

length · number · required

Length of the duration.

on_increase · enum

Behavior when quantity increases.

• prorate
• no_prorate

on_decrease · enum

Behavior when quantity decreases.

• prorate
• no_prorate

free_trial · object

Free trial configuration for this product.

Show Free Trial Object

duration · enum · default: "day" · required

The duration type of the free trial.

• day
• month
• year

length · number · required

The length of the duration type specified (e.g., 7 for 7 days).

unique_fingerprint · boolean · default: false

Whether the free trial is limited to one per customer fingerprint.

card_required · boolean · default: true

Whether the free trial requires a card. If false, the customer can attach the product without going through a checkout flow or having a card on file.

Response

id · string

The ID of the product you set when creating the product.

name · string

The name of the product.

group · string

Product group which this product belongs to.

env · string

The environment of the product (sandbox or production).

is_add_on · boolean

Whether the product is an add-on and can be purchased alongside other products.

is_default · boolean

Whether the product is the default product.

archived · boolean

Whether this product has been archived and is no longer available.

version · number

The current version of the product.

created_at · number

The timestamp of when the product was created in milliseconds since epoch.

items · array

Array of product items that define the product’s features and pricing.

Show Product Item Object

type · enum

The type of the product item (price, priced_feature, or feature).

feature_id · string

The feature ID of the product item. If the item is a fixed price, will be null.

feature_type · enum

Single use features are used once and then depleted, like API calls or credits. Continuous use features are those being used on an ongoing basis, like storage or seats.

• single_use
• continuous_use
• boolean
• static

included_usage · number | 'inf'

The amount of usage included for this feature.

interval · enum

The reset or billing interval of the product item.

interval_count · number

The interval count of the product item.

price · number

The price of the product item.

tiers · array

Tiered pricing for the product item.

tier_behavior · enum

How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).

usage_model · enum

Whether the feature should be prepaid upfront or billed based on usage.

billing_units · number

The amount per billing unit (e.g., $9 / 250 units).

reset_usage_when_enabled · boolean

Whether the usage should be reset when the product is enabled.

entity_feature_id · string

The entity feature ID of the product item if applicable.

display · object

Display configuration for the product item.

Show Display Object

primary_text · string

Primary display text (e.g., “$20”, “1,000 Words”).

secondary_text · string

Secondary display text (e.g., “per month”, “then $0.5 per 1,000 Words”).

config · object

Configuration for rollover and proration behavior of the feature.

free_trial · object

Free trial configuration for this product, if available.

Show Free Trial Object

duration · enum

The duration type of the free trial.

length · number

The length of the duration type specified.

unique_fingerprint · boolean

Whether the free trial is limited to one per customer fingerprint.

card_required · boolean

Whether the free trial requires a card.

base_variant_id · string

ID of the base variant this product is derived from.

scenario · enum

Scenario for when this product is used in attach flows.

• new
• upgrade
• downgrade
• crossgrade

properties · object

Additional product properties.

Show Properties Object

is_free · boolean

True if the product has no base price or usage prices.

is_one_off · boolean

True if the product only contains a one-time price.

interval_group · string

The billing interval group for recurring products (e.g., ‘monthly’, ‘yearly’).

has_trial · boolean

True if the product includes a free trial.

updateable · boolean

True if the product can be updated after creation.

cURL

curl -X POST https://api.autumnai.com/products \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "Pro Product",
    "name": "Pro Plan",
    "is_add_on": false,
    "is_default": false,
    "items": [
      {
        "price": 20,
        "interval": "month"
      },
      {
        "feature_id": "messages",
        "included_usage": 1000,
        "price": 0.5,
        "interval": "month",
        "usage_model": "pay_per_use"
      }
    ],
    "free_trial": {
      "duration": "day",
      "length": 7,
      "unique_fingerprint": false,
      "card_required": true
    }
  }'

import { Autumn } from '@autumnai/node-sdk';

const autumn = new Autumn({
  apiKey: process.env.AUTUMN_API_KEY,
});

const product = await autumn.products.create({
  id: 'Pro Product',
  name: 'Pro Plan',
  is_add_on: false,
  is_default: false,
  items: [
    {
      price: 20,
      interval: 'month',
    },
    {
      feature_id: 'messages',
      included_usage: 1000,
      price: 0.5,
      interval: 'month',
      usage_model: 'pay_per_use',
    },
  ],
  free_trial: {
    duration: 'day',
    length: 7,
    unique_fingerprint: false,
    card_required: true,
  },
});

from autumn import Autumn

autumn = Autumn(api_key="YOUR_API_KEY")

product = autumn.products.create(
    id="Pro Product",
    name="Pro Plan",
    is_add_on=False,
    is_default=False,
    items=[
        {
            "price": 20,
            "interval": "month",
        },
        {
            "feature_id": "messages",
            "included_usage": 1000,
            "price": 0.5,
            "interval": "month",
            "usage_model": "pay_per_use",
        },
    ],
    free_trial={
        "duration": "day",
        "length": 7,
        "unique_fingerprint": False,
        "card_required": True,
    },
)

200

{
  "id": "Pro Product",
  "name": "Pro Plan",
  "group": null,
  "env": "sandbox",
  "is_add_on": false,
  "is_default": false,
  "archived": false,
  "version": 1,
  "created_at": 1761296829908,
  "items": [
    {
      "type": "price",
      "feature_id": null,
      "interval": "month",
      "interval_count": 1,
      "price": 20,
      "display": {
        "primary_text": "$20",
        "secondary_text": "per month"
      }
    },
    {
      "type": "priced_feature",
      "feature_id": "messages",
      "included_usage": 1000,
      "interval": "month",
      "interval_count": 1,
      "price": 0.5,
      "usage_model": "pay_per_use",
      "billing_units": 1000,
      "reset_usage_when_enabled": true,
      "entity_feature_id": null,
      "display": {
        "primary_text": "1,000 Messages",
        "secondary_text": "then $0.5 per 1,000 Messages"
      }
    }
  ],
  "free_trial": {
    "duration": "day",
    "length": 7,
    "unique_fingerprint": false,
    "card_required": true
  },
  "base_variant_id": null,
  "scenario": "new"
}