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. A plan can step that discount as a subscriber keeps renewing: each entry of discountSteps replaces the discount before it from order afterCycle + 1 on, counting the checkout order as order 1 (e.g. discountPercent 10 with steps [{ "afterCycle": 1, "percent": 15 }, { "afterCycle": 2, "percent": 20 }] = 10% on the first order, 15% on the second, 20% from the third). recurringDiscountPercent and recurringDiscountAfterCycle are the older single-step form and mirror the first step. A plan can also add a free product variant (giftVariantId) to one renewal order (giftOnOrder, 2 = the first renewal) at no charge. With giftHidden set, shoppers see "Surprise gift with order N" instead of the product's name until the order that carries the gift. 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,
      "recurringDiscountPercent": null,
      "recurringDiscountAfterCycle": 1,
      "discountSteps": [],
      "giftVariantId": null,
      "giftOnOrder": null,
      "giftHidden": false,
      "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). With a second step set, it covers only the first `recurringDiscountAfterCycle` orders
`recurringDiscountPercent`	`number \| null`	No	Optional second discount step (0-100) used from order `recurringDiscountAfterCycle + 1` on. `null` removes the step
`recurringDiscountAfterCycle`	`number`	No	Orders, counting the checkout order, that get `discountPercent` before the second step applies (default: 1)
`discountSteps`	`{ afterCycle, percent }[] \| null`	No	Every discount step after `discountPercent`, up to 10. Each `percent` (0-100) applies from order `afterCycle + 1` (`afterCycle` 1-100). Replaces the two fields above, which then mirror the first step. `null` or `[]` removes every step
`giftVariantId`	`string \| null`	No	Product variant UUID added free to renewal order `giftOnOrder`. `null` removes the gift
`giftOnOrder`	`number \| null`	No	The order that carries the gift, counting the checkout order as 1 (2-100; 2 = the first renewal)
`giftHidden`	`boolean`	No	Keep the gift a surprise: the product page, checkout, the confirmation email and the customer account show "Surprise gift with order N" instead of the product. The renewal order that carries the gift lists it as a normal line. Removing the gift turns it off
`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 NextSubscription CyclesAPI Reference