---
title: "Create Subscription"
method: POST
path: "/subscriptions"
tags: ["Subscriptions"]
---

# Create Subscription

`POST /subscriptions`

## Request

- Base URL: `https://api.purplegrain.com/api/v1`
- URL: `https://api.purplegrain.com/api/v1/subscriptions`
- Auth: HTTP bearer

## Query parameters

- `include` string

## Request body

- SubscriptionCreateModelAttributes: Flat attributes-adapter request body (Content-Type application/json). Attribute fields and relationships live directly under `data` (no nested `attributes` / `relationships` envelopes). Each relationship is a resource identifier object ({ id, type }). Equivalent JSON:API (nested) shape: `SubscriptionCreateModel` sent as application/vnd.api+json.
  - `data` object, required
    - `plan` 'provider', nullable
    - `status` 'trialing' | 'active' | 'cancelled', nullable
    - `subscribable` object, nullable, required
      - `id` string, nullable
      - `type` 'user' | 'organization', nullable

## Response `201`

Created. The first subscription for an owner that has not used its free trial starts in `trialing`; otherwise it starts `active`.

- SubscriptionsShowResponseAttributes: Single subscription response for Accept application/json (attributes adapter).
  - `data` SubscriptionModelAttributes: Single subscription in attributes-adapter shape (Accept application/json). id, type, and attribute fields at top level; no nested attributes/relationships. The subscribable relationship key may appear when include is used.
    - `id` string
    - `type` string
    - `plan` 'provider'
    - `status` 'trialing' | 'active' | 'cancelled'
    - `services_limit` integer
    - `price_cents` integer
    - `interval` string
    - `payment_provider` 'mock' | 'stripe'
    - `current_period_start` string, date-time
    - `current_period_end` string, date-time
    - `trial_ends_at` string, date-time, nullable
    - `started_at` string, date-time, nullable
    - `cancelled_at` string, date-time, nullable
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `subscribable` object: Present when include=subscribable
  - `meta` PaginationMeta
    - `current_page` number
    - `next_page` number, nullable
    - `prev_page` number, nullable

## Other responses

- `401`: Unauthorized
- `403`: Forbidden — first-party only; refused to an API key or an assistant's token.
- `422`: Unprocessable Entity

---

[API](https://skmtc.dev/purplegrain/apis/purple-grain-api.md) · [All operations](https://skmtc.dev/purplegrain/apis/purple-grain-api/llms.txt) · [OpenAPI document](https://skmtc.dev/purplegrain/apis/purple-grain-api/revisions/4bedbc1c784c?raw)