---
title: "Update subscription tier or start a Stripe Checkout session"
method: POST
path: "/api/credits/subscription"
tags: ["v1", "credits"]
---

# Update subscription tier or start a Stripe Checkout session

`POST /api/credits/subscription`

## Request body

- SubscriptionTierRequest
  - `tier` 'NO_TIER' | 'BASIC' | 'PRO' | 'MAX' | 'BUSINESS', required
  - `success_url` string
  - `cancel_url` string
  - `billing_cycle` 'monthly' | 'yearly'

## Response `200`

Successful Response

- SubscriptionStatusResponse
  - `tier` 'NO_TIER' | 'BASIC' | 'PRO' | 'MAX' | 'BUSINESS' | 'ENTERPRISE', required
  - `monthly_cost` integer, required
  - `tier_costs` object, required
  - `tier_costs_yearly` object — Tier → yearly amount in cents. Populated only for tiers with a yearly Stripe price configured in LaunchDarkly. Empty for monthly-only configurations.
  - `billing_cycle` 'monthly' | 'yearly' — Billing cycle of the user's active Stripe subscription. Defaults to ``monthly`` for users without an active sub. ``monthly_cost`` above reflects this cycle's actual price (so a yearly subscriber sees their yearly amount, not the monthly equivalent).
  - `tier_multipliers` object — Tier → rate-limit multiplier. Covers the same tiers listed in ``tier_costs`` so the frontend can render rate-limit badges relative to the lowest visible tier without knowing backend defaults.
  - `proration_credit_cents` integer, required
  - `has_active_stripe_subscription` boolean — True when the user has an active/trialing Stripe subscription. The frontend uses this to branch upgrade UX: modify-in-place + saved-card auto-charge when True, redirect to Stripe Checkout when False.
  - `current_period_end` integer, nullable — Unix timestamp of the active subscription's current_period_end. Used to show the date Stripe will issue the next invoice (with prorated upgrade charges, if any). None when no active sub.
  - `pending_tier` 'NO_TIER' | 'BASIC' | 'PRO' | 'MAX' | 'BUSINESS', nullable
  - `pending_tier_effective_at` string, date-time, nullable
  - `pending_billing_cycle` 'monthly' | 'yearly', nullable — Billing cycle of the queued change, when resolvable. Set alongside ``pending_tier`` for tier downgrades and same-tier cycle switches (yearly→monthly). The frontend uses this to differentiate a cycle-only schedule (``pending_tier == current tier``) from a real tier downgrade so the UI copy can describe the actual change. ``None`` for cancellations and unconfigured legacy prices.
  - `url` string — Populated only when POST /credits/subscription starts a Stripe Checkout Session (BASIC → paid upgrade). Empty string in all other branches — the client redirects to this URL when non-empty.

## Other responses

- `401` — Authentication required
- `422` — Validation Error

---

[API](https://skmtc.net/significant-gravitas/apis/autogpt-agent-server.md) · [All operations](https://skmtc.net/significant-gravitas/apis/autogpt-agent-server/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/significant-gravitas/autogpt-agent-server/versions/382041c7ecb2/schema)