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

# Subscription Plans

> Endpoints for creating, updating, deleting recurring-billing plans and attaching **one or many plans** to a product.  When a shopper visits Checkout for a product, every attached plan is shown alongside the one-time price. 

All endpoints require:

* `Authorization: Bearer <merchant_api_token>`
* `Content-Type: application/json`
* `Idempotency-Key` on mutating calls

Customer-level subscription lifecycle (pause, cancel, etc.) is managed in the
merchant dashboard and is **not** part of this public API.

***

## Create Plan

```http theme={null}
POST /v1/plans
Idempotency-Key: <uuid-v4>
```

**Body**

```json theme={null}
{
  "name": "Monthly Lens Supply",
  "interval": "monthly",          // monthly · quarterly · yearly
  "price_cents": 2500,
  "currency": "usd",
  "trial_days": 14
}
```

**Success 201**

```json theme={null}
{
  "plan_id": "plan_123",
  "name": "Monthly Lens Supply",
  "interval": "monthly",
  "price_cents": 2500,
  "currency": "usd",
  "trial_days": 14,
  "status": "ACTIVE",
  "created_at": "2025-06-05T12:00:00Z"
}
```

***

## List Plans

```http theme={null}
GET /v1/plans
Authorization: Bearer <merchant_api_token>
```

Optional query: `status=ACTIVE|ARCHIVED`.

***

## Retrieve a Plan

```http theme={null}
GET /v1/plans/{plan_id}
Authorization: Bearer <merchant_api_token>
```

***

## Update Plan

```http theme={null}
PUT /v1/plans/{plan_id}
Idempotency-Key: <uuid-v4>
```

Send only the fields you’re changing.

***

## Archive Plan

```http theme={null}
DELETE /v1/plans/{plan_id}
Authorization: Bearer <merchant_api_token>
```

Returns **204 No Content**.  Archiving blocks new checkouts but leaves existing subscribers intact.

***

## Attach Plan(s) to a Product

Attach **one or many** plans in a single call.

```http theme={null}
POST /v1/products/{product_id}/attach-plans
Idempotency-Key: <uuid-v4>
```

**Body**

```json theme={null}
{
  "plan_ids": ["plan_123", "plan_456"]
}
```

**Success 200**

```json theme={null}
{
  "product_id": "prod_abc123",
  "attached_plan_ids": ["plan_123", "plan_456"]
}
```

***

## Detach Plan(s) from a Product

Remove one or more plans without affecting the rest.

```http theme={null}
POST /v1/products/{product_id}/detach-plans
Idempotency-Key: <uuid-v4>
```

**Body**

```json theme={null}
{
  "plan_ids": ["plan_123"]
}
```

**Success 200**

```json theme={null}
{
  "product_id": "prod_abc123",
  "attached_plan_ids": ["plan_456"]
}
```

***

## Plan Status Values

| Status | Meaning |
| - | - |
| `ACTIVE` | Plan is available for new sign-ups |
| `ARCHIVED` | Hidden from checkout; active subscribers unaffected |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.