---
title: "Create Subscription"
method: POST
path: "/payments/subscribe"
tags: ["payments"]
---

# Create Subscription

`POST /payments/subscribe`

## Request

- Base URL: `https://api.oxlo.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.oxlo.ai/payments/subscribe`
- Auth: HTTP bearer

Create or update subscription with bonus days logic.

Business Rules:
- First subscription gets bonus days (Pro: +15, Premium: +30)
- Subsequent renewals are standard 30-day cycles
- Upgrades allowed mid-cycle (immediate effect)
- Downgrades NOT allowed mid-cycle (must wait for next billing)

## Request body

- SubscribeRequest
  - `plan` string, required
  - `payment_method_id` string, required
  - `auto_renew` boolean
  - `idempotency_key` string, required

## Response `200`

Successful Response

- SubscriptionResponse
  - `id` string, required
  - `plan` string, required
  - `status` string, required
  - `current_period_end` string, date-time, required
  - `effective_end_date` string, date-time, nullable
  - `bonus_days` integer
  - `auto_renew` boolean, required
  - `client_secret` string, nullable
  - `requires_action` boolean
  - `payment_status` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/oxlo/apis/oxlo-backend.md) - [All operations](https://skmtc.dev/oxlo/apis/oxlo-backend/llms.txt) - [OpenAPI document](https://skmtc.dev/oxlo/apis/oxlo-backend/revisions/bc2ecdc94f31?raw)