> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stellartools.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Products

> Create and manage products

A product defines what you're selling — a one-time item, a recurring subscription, or a metered usage plan. Products are referenced when creating checkouts.

## The product object

<ResponseField name="id" type="string">
  Unique identifier. Prefixed with `prod_`.
</ResponseField>

<ResponseField name="object" type="string">
  Always `"product"`.
</ResponseField>

<ResponseField name="name" type="string">
  Display name of the product.
</ResponseField>

<ResponseField name="description" type="string">
  Optional description.
</ResponseField>

<ResponseField name="images" type="array">
  Array of image URLs.
</ResponseField>

<ResponseField name="type" type="string">
  Billing type. One of `one_time`, `subscription`, or `metered`.
</ResponseField>

<ResponseField name="status" type="string">
  `active` or `archived`.
</ResponseField>

<ResponseField name="asset_id" type="string">
  The asset this product is priced in.
</ResponseField>

<ResponseField name="currency_code" type="string">
  The currency code this product is priced in, e.g "NGN"
</ResponseField>

<ResponseField name="price_amount" type="number">
  Price in the product's asset.
</ResponseField>

<ResponseField name="recurring_period" type="string">
  For `subscription` products. One of `day`, `week`, `month`, or `year`.
</ResponseField>

<ResponseField name="unit" type="string">
  For `metered` products. The unit being measured (e.g. `"token"`, `"request"`).
</ResponseField>

<ResponseField name="units_per_credit" type="number">
  Units consumed per credit.
</ResponseField>

<ResponseField name="total_credits" type="number">
  Total credits granted to the customer when this product is purchased.
</ResponseField>

<ResponseField name="metadata" type="object">
  Arbitrary key-value data.
</ResponseField>

<ResponseField name="environment" type="string">
  `testnet` or `mainnet`.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

***

## Create a product

`POST /product`

```bash theme={null}
curl https://api.stellartools.dev/product \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Plan",
    "type": "subscription",
    "asset_id": "ast_01jx...",
    "price_amount": 10,
    "recurring_period": "month"
  }'
```

### Body

<ParamField body="name" type="string" required>
  Product name.
</ParamField>

<ParamField body="type" type="string" required>
  `one_time`, `subscription`, or `metered`.
</ParamField>

<ParamField body="currency_code" type="string" required>
  Currency code to charge in, e.g "NGN".
</ParamField>

<ParamField body="price_amount" type="number" required>
  Price amount in the asset.
</ParamField>

<ParamField body="recurring_period" type="string">
  Required for `subscription` type. One of `day`, `week`, `month`, `year`.
</ParamField>

<ParamField body="description" type="string">
  Product description.
</ParamField>

<ParamField body="images" type="array">
  Array of image URLs.
</ParamField>

<ParamField body="unit" type="string">
  For `metered` products. The unit label.
</ParamField>

<ParamField body="units_per_credit" type="number">
  Units consumed per credit.
</ParamField>

<ParamField body="total_credits" type="number">
  Total credits granted on purchase.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value data.
</ParamField>

***

## Update a product

`PUT /product/{id}`

```bash theme={null}
curl -X PUT https://api.stellartools.dev/product/prod_01jx... \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Pro Plan v2", "price_amount": 12 }'
```

### Body

<ParamField body="name" type="string">
  New name.
</ParamField>

<ParamField body="description" type="string">
  New description.
</ParamField>

<ParamField body="price_amount" type="number">
  New price amount.
</ParamField>

<ParamField body="recurring_period" type="string">
  New billing interval.
</ParamField>

<ParamField body="images" type="array">
  New image URLs.
</ParamField>

<ParamField body="metadata" type="object">
  Merged with existing metadata.
</ParamField>

***

## Delete a product

`DELETE /product/{id}`

```bash theme={null}
curl -X DELETE https://api.stellartools.dev/product/prod_01jx... \
  -H "x-api-key: YOUR_API_KEY"
```