Subscription Plans API

REST API endpoints for managing recurring purchase plans.

Subscription plans let customers buy products on a recurring schedule at a discount. A plan's billing frequency is cadence (month or week) multiplied by interval (e.g. cadence month × interval 3 = every quarter). discountPercent is the discount applied versus a one-time purchase. Each plan can be assigned to a set of products that customers may subscribe to.

List Subscription Plans

GET /api/v1/subscription-plans

Returns subscription plans ordered by position. Each plan includes the IDs of products it's assigned to.

Query Parameters

Parameter	Type	Default	Description
`limit`	`number`	50	Plans per page (1-100)
`offset`	`number`	0	Plans to skip
`query`	`string`	—	Search term for plan name
`active`	`boolean`	—	Filter by active status

curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/subscription-plans

Response (200)

{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "name": "Monthly delivery",
      "cadence": "month",
      "interval": 1,
      "discountPercent": 10,
      "description": "Delivered every month",
      "benefits": "Free shipping, cancel anytime",
      "position": 0,
      "active": true,
      "productIds": ["0191abc0-0000-7000-8000-000000000200"],
      "createdAt": "2024-06-15T10:30:00.000Z",
      "updatedAt": "2024-06-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "count": 1,
    "offset": 0,
    "limit": 50
  }
}

Get Subscription Plan

GET /api/v1/subscription-plans/{id}

Returns a single subscription plan by UUID, including assigned product IDs.

curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/subscription-plans/0191abc0-1234-7def-8000-000000000001

Response (200)

{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "name": "Monthly delivery",
  "cadence": "month",
  "interval": 1,
  "discountPercent": 10,
  "description": "Delivered every month",
  "benefits": "Free shipping, cancel anytime",
  "position": 0,
  "active": true,
  "productIds": ["0191abc0-0000-7000-8000-000000000200"],
  "createdAt": "2024-06-15T10:30:00.000Z",
  "updatedAt": "2024-06-15T10:30:00.000Z"
}

Create Subscription Plan

POST /api/v1/subscription-plans

Creates a recurring purchase plan. Assign products by passing their UUIDs in products.

Request Body

Field	Type	Required	Description
`name`	`string`	Yes	Plan display name, e.g. "Monthly delivery"
`cadence`	`string`	Yes	Billing cadence unit: `month` or `week`
`interval`	`number`	No	Number of cadence units between charges (default: 1)
`discountPercent`	`number`	No	Percentage discount vs. one-time purchase (0-100)
`description`	`string`	No	Optional plan description
`benefits`	`string`	No	Optional plan benefits text
`position`	`number`	No	Sort order (lower shows first)
`active`	`boolean`	No	Whether the plan is selectable (default: `true`)
`products`	`string[]`	No	Product UUIDs offered on this plan (replaces the existing set)

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly delivery",
    "cadence": "month",
    "interval": 1,
    "discountPercent": 10,
    "products": ["0191abc0-0000-7000-8000-000000000200"]
  }' \
  https://your-store.yns.store/api/v1/subscription-plans

Response (201)

Returns the created subscription plan (same shape as Get Subscription Plan).

Update Subscription Plan

PATCH /api/v1/subscription-plans/{id}

Partially updates a subscription plan. Only provided fields change. Passing products replaces the entire assigned product set.

Request Body

All fields from Create Subscription Plan are accepted and optional.

curl -X PATCH \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"discountPercent": 15, "active": false}' \
  https://your-store.yns.store/api/v1/subscription-plans/0191abc0-1234-7def-8000-000000000001

Response (200)

Returns the updated subscription plan.

Delete Subscription Plan

DELETE /api/v1/subscription-plans/{id}

Hard-deletes the subscription plan by UUID.

curl -X DELETE \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/subscription-plans/0191abc0-1234-7def-8000-000000000001

Response (200)

{
  "ok": true,
  "deleted": 1
}

PreviousPromotionsAPI Reference NextLoyaltyAPI Reference