Create a subscription type

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

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

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

Token scope: api:write:subscription_types
Without it: 403 insufficient-token-scope.
Permission: subscription_types::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 retainer type

curl -X POST \
  'https://<your-url>/api/v2/subscription-types' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <key>' \
  -d '{
    "name": "Hosting retainer",
    "description": "Managed hosting and monitoring, billed monthly.",
    "default_billing_interval": "monthly",
    "auto_renew": true,
    "active": true
  }'

const response = await fetch('https://<your-url>/api/v2/subscription-types', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Idempotency-Key': '<key>',
  },
  body: JSON.stringify({
    "name": "Hosting retainer",
    "description": "Managed hosting and monitoring, billed monthly.",
    "default_billing_interval": "monthly",
    "auto_renew": true,
    "active": true
  }),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('Idempotency-Key', '<key>')
    ->post('https://<your-url>/api/v2/subscription-types', [
        'name' => 'Hosting retainer',
        'description' => 'Managed hosting and monitoring, billed monthly.',
        'default_billing_interval' => 'monthly',
        'auto_renew' => true,
        'active' => true,
    ]);

import requests
response = requests.request(
    'POST',
    'https://<your-url>/api/v2/subscription-types',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'Idempotency-Key': '<key>'},
    json={'name': 'Hosting retainer', 'description': 'Managed hosting and monitoring, billed monthly.', 'default_billing_interval': 'monthly', 'auto_renew': True, 'active': True},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "name": "Hosting retainer",
    "description": "Managed hosting and monitoring, billed monthly.",
    "default_billing_interval": "monthly",
    "auto_renew": true,
    "active": true,
    "sort_order": 1,
    "created_at": "2026-03-04T09:15:00Z",
    "updated_at": "2026-03-04T09:15:00Z",
    "deleted_at": "2026-03-04T09:15:00Z",
    "items_count": 1,
    "links": {
      "self": "https://<your-url>/api/v2/work-items/1",
      "items": "https://<your-url>/api/v2/work-items/1"
    }
  }
}

{
  "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."
    }
  ]
}

sort_order is assigned by the server as one past the highest existing position and cannot be sent. Names are not unique, so two types may share one. Template lines are not accepted here: create them one request each through POST subscription-types/{subscription_type}/items, so sending items is a 422 validation-failed for an unknown key.

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≤ 255Required

Subscription type name. It is also the name every customer subscription of this type is displayed under, so renaming a type renames what its existing subscriptions read as. Names are not unique.

descriptionstring or null

What subscriptions of this type cover, as free text.

default_billing_intervalstring

Interval a new subscription of this type is billed at by default. Omitting it on create yields yearly, the stored default, not the monthly that plnnrly's form pre-selects, which is a form convenience the API deliberately does not reproduce.

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.

auto_renewboolean

Whether subscriptions created from this type renew automatically by default. The value is stored exactly as sent; nothing forces it to false.

activeboolean

Whether the type is offered in the catalogue. It is a catalogue flag only: nothing in the application filters on it, so deactivating a type does not stop existing subscriptions of that type from being renewed or invoiced.

Response 201

Returns a SubscriptionType 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