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

# Subscription Product Endpoints

> Create and manage subscription products and product groups

Subscription products support recurring billing with configurable billing periods and multi-currency pricing. Products can be organized into groups for shared trial management and tiered pricing plans.

## Billing Periods

| Period      | Frequency            |
| ----------- | -------------------- |
| `weekly`    | Every 7 days         |
| `monthly`   | Every calendar month |
| `quarterly` | Every 3 months       |
| `yearly`    | Every 12 months      |

## Group Object

Product groups organize related subscription products (e.g., Free, Pro, Enterprise plans) and enable shared trial management across products within a group. Each group exists per environment -- one row for test and one for production.

```json theme={"system"}
{
  "id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a",
  "storeId": "STO_2D5F8G3H1K4M6N9P",
  "name": "Pricing Plans",
  "description": "Free, Pro, and Enterprise tiers",
  "rules": { "sharedTrial": true },
  "productIds": [
    "PROD_3F7H2J5L8N1Q4S6U",
    "PROD_8B4D6F9H2K5M7P1R",
    "PROD_1C3E5G7J0L2N4Q6S"
  ],
  "environment": "test",
  "createdAt": "2026-03-30T10:30:00.000Z",
  "updatedAt": "2026-03-30T10:30:00.000Z"
}
```

<Note>
  Group IDs are in **UUID format**, not Short ID format. This is the only entity in the API that uses raw UUIDs.
</Note>

| Field         | Type           | Description                                 |
| ------------- | -------------- | ------------------------------------------- |
| `id`          | string         | Group ID (UUID format)                      |
| `storeId`     | string         | Store ID (`STO_xxx` format)                 |
| `name`        | string         | Group name (unique per store + environment) |
| `description` | string \| null | Group description                           |
| `rules`       | object         | Group rules (see below)                     |
| `productIds`  | string\[]      | List of product IDs (`PROD_xxx` format)     |
| `environment` | string         | `test` or `prod`                            |
| `createdAt`   | string         | ISO 8601 timestamp                          |
| `updatedAt`   | string         | ISO 8601 timestamp                          |

### Rules

| Field         | Type    | Default | Description                                                                                                                                                                       |
| ------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sharedTrial` | boolean | `false` | When `true`, trial usage is shared across all products in the group. Prevents customers from signing up for repeated free trials by switching between products in the same group. |

## Endpoints

<CardGroup cols={2}>
  <Card title="Create Product" icon="plus" href="/api-reference/endpoints/subscription-products/create-product">
    Create a subscription product with billing period and multi-currency pricing.
  </Card>

  <Card title="Update Product" icon="pen" href="/api-reference/endpoints/subscription-products/update-product">
    Update a subscription product's content. Creates a new immutable version if content changed.
  </Card>

  <Card title="Publish Product" icon="rocket" href="/api-reference/endpoints/subscription-products/publish-product">
    Publish a subscription product from test to production (first-publish only).
  </Card>

  <Card title="Update Status" icon="toggle-on" href="/api-reference/endpoints/subscription-products/update-status">
    Activate or deactivate a subscription product.
  </Card>

  <Card title="Create Group" icon="layer-group" href="/api-reference/endpoints/subscription-products/create-group">
    Create a product group to organize related subscription products.
  </Card>

  <Card title="Update Group" icon="pen-to-square" href="/api-reference/endpoints/subscription-products/update-group">
    Update a product group's name, description, rules, or product list.
  </Card>

  <Card title="Delete Group" icon="trash" href="/api-reference/endpoints/subscription-products/delete-group">
    Permanently delete a product group.
  </Card>

  <Card title="Publish Group" icon="rocket" href="/api-reference/endpoints/subscription-products/publish-group">
    Publish a product group from test to production (supports repeated UPSERT).
  </Card>
</CardGroup>