---
title: "Apply a subscription plan change"
method: POST
path: "/billing/me/subscription/change"
tags: ["Billing"]
---

# Apply a subscription plan change

`POST /billing/me/subscription/change`

## Request

- Base URL: `https://api.crawlora.net/api/v1`
- URL: `https://api.crawlora.net/api/v1/billing/me/subscription/change`
- Auth: API key in header `x-api-key`

Applies an immediate, prorated upgrade after Stripe payment succeeds, or schedules a downgrade for the next renewal. The unused legacy metered item is removed as part of an immediate upgrade.

## Request body

- BillingStripeSubscriptionChangeRequestDoc
  - `idempotency_key` string
  - `plan` string
  - `previewed_at` string
  - `proration_date` integer

## Response `200`

Subscription change result

- BillingStripeSubscriptionChangeResultResponseDoc
  - `code` integer
  - `data` BillingStripeSubscriptionChangeResult
    - `action` string
    - `amount_due_cents` integer
    - `currency` string
    - `current_plan` string
    - `effective_at` string
    - `hosted_invoice_url` string
    - `invoice_id` string
    - `local_sync_pending` boolean
    - `payment_action_required` boolean
    - `payment_client_secret` string
    - `payment_status` string
    - `target_plan` string
  - `msg` string

## Other responses

- `400`: Invalid plan, stale preview, or idempotency key
- `401`: Authentication required
- `500`: Internal server error

---

[API](https://skmtc.dev/crawlora/apis/crawlora-api.md) · [All operations](https://skmtc.dev/crawlora/apis/crawlora-api/llms.txt) · [OpenAPI document](https://skmtc.dev/crawlora/apis/crawlora-api/revisions/0497899e2016?raw)