Create Product

Creates a new product with pricing plans and feature configurations.

Request Body

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

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

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

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

Overview

Core Endpoints

Customers

Products

Features

Invoices

Events

Create Product

Request Body

Response

Build docs developers (and LLMs) love

Overview

Core Endpoints

Customers

Products

Features

Invoices

Events

​Request Body

​Response

Build docs developers (and LLMs) love

Request Body

Response