Create a subscription product

POSThttps://<your-url>/api/v2/subscription-products

MCP id subscription-products.storeAlso on this path: GET List subscription products

Creates a product and returns it in the detail view with a Location header.

Token scope: api:write:subscription_products
Without it: 403 insufficient-token-scope.
Permission: subscription_products::create
Without it: 403 insufficient-permission.
Feature: Needs the billing feature on your organisation.
Without it: 404 endpoint-not-found.
Rate cost: 1 unit, write bucket. A write costs the same whatever view you ask for.
Also: Accepts Idempotency-Key. Never cached: private, no-store. Unknown body keys are refused, never dropped.

Both are checked, scope first. A token never does more than its user. How access is checked

Request

Example: A monthly hosting product

curl -X POST \
  'https://<your-url>/api/v2/subscription-products' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <key>' \
  -d '{
    "name": "Managed hosting, small",
    "description": "Managed hosting for {{$site}} over {{$period}}.",
    "price_interval": "monthly",
    "is_hosting": true,
    "sales_price": "49.50",
    "vat_rate": 21
  }'

const response = await fetch('https://<your-url>/api/v2/subscription-products', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Idempotency-Key': '<key>',
  },
  body: JSON.stringify({
    "name": "Managed hosting, small",
    "description": "Managed hosting for {{$site}} over {{$period}}.",
    "price_interval": "monthly",
    "is_hosting": true,
    "sales_price": "49.50",
    "vat_rate": 21
  }),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('Idempotency-Key', '<key>')
    ->post('https://<your-url>/api/v2/subscription-products', [
        'name' => 'Managed hosting, small',
        'description' => 'Managed hosting for {{$site}} over {{$period}}.',
        'price_interval' => 'monthly',
        'is_hosting' => true,
        'sales_price' => '49.50',
        'vat_rate' => 21,
    ]);

import requests
response = requests.request(
    'POST',
    'https://<your-url>/api/v2/subscription-products',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'Idempotency-Key': '<key>'},
    json={'name': 'Managed hosting, small', 'description': 'Managed hosting for {{$site}} over {{$period}}.', 'price_interval': 'monthly', 'is_hosting': True, 'sales_price': '49.50', 'vat_rate': 21},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "name": "Managed hosting, small",
    "description": "Managed hosting for {{$site}} over {{$period}}.",
    "purchase_price": "1250.00",
    "sales_price": "49.50",
    "price_interval": "monthly",
    "is_hosting": true,
    "vat_rate": 21,
    "exact_item_id": "…",
    "exact_vat_code": "…",
    "exact_cost_center": "…",
    "created_at": "2026-03-04T09:15:00Z"
  }
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/idempotency-key-in-flight",
  "title": "Idempotency key in flight",
  "status": 409,
  "detail": "The original request for this Idempotency-Key is still being processed. Retry shortly.",
  "instance": "/api/v2/worklogs",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S"
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "3 fields failed validation.",
  "instance": "/api/v2/worklogs",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S",
  "errors": [
    {
      "pointer": "/date",
      "code": "date_format",
      "detail": "The date does not match the format Y-m-d."
    },
    {
      "pointer": "/minutes",
      "code": "min",
      "detail": "The minutes must be at least 1."
    },
    {
      "pointer": "/description",
      "code": "required",
      "detail": "The description field is required."
    }
  ]
}

3 more fields, listed under Response

Names are unique and deleted products count, so a name that matches a soft-deleted product is a 422 validation-failed with code unique; restore that product with POST subscription-products/{subscription_product}/actions/restore rather than retrying under a different name. price_interval is required: it has no default, and the monthly pre-selection in plnnrly's form is a convenience only.

Query parameters

Unknown parameters are refused with 400, naming the parameter.

viewstring

Which field set to render.

summarydetaildefault

Request headers

X-Request-Idstringpattern

A correlation id of your own. It is recorded in our logs next to the server's request id but never returned: the response header always carries the server's id. A value that does not match the pattern is discarded silently, never rejected.

Idempotency-Keystring≤ 255

A caller-chosen key that makes this POST safe to retry. Replaying it returns the original response with Idempotency-Replayed: true.

Request body

Unknown keys are refused with 422, naming the key.

namestring≤ 255UniqueRequired

Product name as shown in the UI and on the subscription line.

Must be unique across SubscriptionProduct.

price_intervalstringRequired

Interval the sales price is charged per.

yearly: Billed once a year.
monthly: Billed every month.
one-time: Charged once, on the invoice the product is first put on, and never renewed.

New values may be added.

descriptionstring or null

Invoice-line template for subscription lines built from this product. Supports the placeholder tokens {{$domain}}, {{$site}}, {{$server}}, {{$period}}, {{$product}} and {{$customer}}, which are filled in when the line is invoiced; the template itself is kept verbatim.

is_hostingboolean

Whether this is a hosting product: one sold against a concrete site or server, which is what lets a subscription line name the infrastructure it covers.

purchase_pricedecimal (2 dp) or null≥ 0

What the product costs us, as a decimal string. Null when unknown.

2 decimal places, not negative

At least 0.

sales_pricedecimal (2 dp) or null≥ 0

What the customer is billed per interval, as a decimal string. Null when the line carries its own price.

2 decimal places, not negative

At least 0.

vat_rateinteger or null0 to 100

VAT rate as a whole percentage: 21 means 21%, not 0.21. Null when the rate is decided at invoicing time.

exact_item_idstring or null≤ 255

Exact Online article this product maps to, by Exact's own external identifier (exact_items.exact_id), not by a local id.

exact_vat_codestring or null≤ 255

Exact Online VAT code, by code (exact_vat_codes.code), not by id.

exact_cost_centerstring or null≤ 255

Exact Online cost centre, by code (exact_cost_centers.code), not by id.

Response 201

Returns a SubscriptionProduct in the detail view.

Headers

ETag: A strong validator of exactly this representation.
Idempotency-Replayed: true when this response was replayed from a stored Idempotency-Key rather than produced by a new write.
Location: The absolute URL of the created or queued resource.
RateLimit: The IETF httpapi-ratelimit-headers form of your remaining allowance on the tightest bucket this request touched.
RateLimit-Policy: The ceiling and window of that bucket, as <limit>;w=<seconds>.
X-Request-Id: The server-generated ULID correlating this response with our logs.

Every response also carries Cache-Control, Vary, X-Content-Type-Options, X-Plnnrly-Api-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Headers and versioning