Bolt has moved to boltapp.com. Stores still using bolt.com hosts must update now: see the migration guide.

Skip to content

Create a product

View As MarkdownMCP
POST
/v2/subscriptions/products

Creates a product and its plans in one call. A product created here is the same product the v1 endpoints read, update and delete.

Authorization

X-API-Key<token>

Admins and Developers can obtain their Bolt API key from the Bolt Merchant Dashboard. Send it together with X-Publishable-Key.

In: header

Header Parameters

X-Bolt-Connect-Seller-Id?string

Seller ID for Connect marketplace operations. Allows creating products on behalf of a seller.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Send exactly one of product or product_reference. A body with both, or with neither, is rejected. Which one you send depends on your division's subscription type, which Bolt sets for your account:

  • Bolt Cart: send product. Bolt creates the product in your Bolt Cart catalog. product_reference is rejected.
  • Physical and payment-only: send product_reference, which points at a product in your own catalog. product is rejected. v2 does not create global products, so product_reference.product_id is required.
  • Digital goods and subscriptions (DGAS): not supported. Use POST /v1/subscriptions/products.

A Bolt Cart product is always created active. Three keys that POST /v1/subscriptions/products accepts are rejected here with a 400:

  • status and product.status: a v2 product is always created active.
  • promotions: create promotions through the product promotions endpoint after the product exists.

Plan rules also depend on the division:

  • Bolt Cart: plans may be empty. Every plan needs a sku. A plan may have a trial. initial_period and the one_time frequency unit are rejected. A plan's currency, when sent, must be the product's currency.
  • Physical and payment-only: at least one plan is required. A plan may have an initial_period. trial is rejected.

metadata is accepted only with product. A non-empty metadata sent with product_reference is rejected.

The product and all of its plans are written together. If any plan is rejected, nothing is created. A duplicate returns 409: on a Bolt Cart division when a live product already has the same sku, and on other divisions when a product already exists for the same product_reference.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v2/subscriptions/products" \  -H "Content-Type: application/json" \  -d '{    "product": {      "name": "Canvas AI Pro",      "description": "Professional plan for Canvas AI.",      "sku": "CANVAS-AI-PRO",      "brand": "Canvas",      "images": [        "https://example.com/canvas-ai-pro.png"      ],      "unit_price": 2900,      "currency": "USD",      "taxable": true,      "tax_behavior": "exclusive"    },    "plans": [      {        "name": "Monthly",        "sku": "CANVAS-AI-PRO-MONTHLY",        "frequency": 1,        "frequency_unit": "month",        "trial": {          "trial_days": 14        }      },      {        "name": "Yearly",        "sku": "CANVAS-AI-PRO-YEARLY",        "frequency": 1,        "frequency_unit": "year"      }    ]  }'
{  "id": "sp_Tlj0Osm0N76T",  "status": "active",  "created_at": "2023-10-01T12:00:00Z",  "updated_at": "2023-10-01T12:00:00Z",  "activated_at": "2023-10-01T12:00:00Z",  "archived_at": "2024-02-01T12:00:00Z",  "product": {    "name": "Canvas AI Pro",    "description": "Professional plan for Canvas AI.",    "sku": "CANVAS-AI-PRO",    "brand": "Canvas",    "images": [      "https://example.com/canvas-ai-pro.png"    ],    "marketing_features": [      "Unlimited projects",      "Priority support"    ],    "unit_price": 2900,    "currency": "USD",    "taxable": true,    "tax_behavior": "exclusive",    "tax_code": "31000",    "family": "Canvas AI",    "unit_label": "seat"  },  "product_reference": {    "product_id": "37",    "variant_id": "67"  },  "plans": [    {      "id": "spl_ba_PpkW16oIW",      "name": "Monthly",      "sku": "CANVAS-AI-PRO-MONTHLY",      "created_at": "2023-10-01T12:00:00Z",      "updated_at": "2023-10-01T12:00:00Z",      "frequency": 1,      "frequency_unit": "month",      "base_price": 0,      "product_id": "sp_Tlj0Osm0N76T",      "status": "active",      "currency": "USD",      "initial_period": {        "frequency": 2,        "frequency_unit": "week"      },      "trial": {        "trial_days": 14      }    }  ],  "metadata": {    "team": "growth"  },  "name": "string"}