> ## Documentation Index > Fetch the complete documentation index at: https://docs.modelslab.com/llms.txt > Use this file to discover all available pages before exploring further. # Subscriptions > Create and manage plan subscriptions from the Agents control plane. ## Endpoints | Method | Endpoint | Auth | Purpose | | ------ | ----------------------------------------------- | ------------ | ---------------------------------------------------------------------------- | | `GET` | `/api/agents/v1/subscriptions/plans` | Bearer token | List available subscription plans and pay-as-you-go options | | `GET` | `/api/agents/v1/subscriptions` | Bearer token | List user subscriptions (addon, enterprise, normal) | | `POST` | `/api/agents/v1/subscriptions` | Bearer token | Create subscription — headless with `payment_method_id` or Checkout redirect | | `POST` | `/api/agents/v1/subscriptions/confirm-checkout` | Bearer token | Confirm a Stripe Checkout subscription session | | `GET` | `/api/agents/v1/subscriptions/{id}/status` | Bearer token | Check subscription status | | `PUT` | `/api/agents/v1/subscriptions/{id}` | Bearer token | Change subscription plan | | `POST` | `/api/agents/v1/subscriptions/{id}/pause` | Bearer token | Pause subscription | | `POST` | `/api/agents/v1/subscriptions/{id}/resume` | Bearer token | Resume subscription | | `POST` | `/api/agents/v1/subscriptions/{id}/reset-cycle` | Bearer token | Reset billing cycle anchor | ### Discover available plans Use this endpoint to list all subscription plans and learn about pay-as-you-go options before creating a subscription. ```bash theme={null} curl --request GET 'https://modelslab.com/api/agents/v1/subscriptions/plans' \ --header 'Authorization: Bearer ' \ --header 'Accept: application/json' ``` **Response structure:** ```json theme={null} { "data": { "subscription_plans": [ { "id": 10, "name": "Basic Enterprise", "category": "enterprise", "period": "monthly", "type": "basic", "price": 249.0, "api_call_limit": 0, "rate_limit": 0, "features": ["Unlimited Images", "No Rate Limiter", "..."] } ], "pay_as_you_go": { "available": true, "description": "Pay only for what you use with wallet-based billing. No subscription required.", "minimum_topup_usd": 10.00, "currency": "USD", "auto_payments": { "supported": true, "description": "Automatically top up your wallet when balance drops below a threshold.", "configure_endpoint": "PUT /api/agents/v1/wallet/auto-funding", "disable_endpoint": "DELETE /api/agents/v1/wallet/auto-funding" }, "fund_endpoint": "POST /api/agents/v1/wallet/fund" }, "count": 37 } } ``` Use the `id` from a plan in `subscription_plans` as the `plan_id` when creating a subscription. Alternatively, use the pay-as-you-go option by funding your wallet directly. ### Create subscription (Headless — Recommended for Agents) Create a subscription using a `payment_method_id` obtained from the Stripe API. No browser redirect needed. First, fetch the publishable key via `GET /billing/stripe-config`, then create a PaymentMethod via the Stripe API (see [Headless Agent Flow](/agents-api/headless-flow) for details): ```bash theme={null} # Step 1: Fetch Stripe publishable key STRIPE_PK=$(curl -s 'https://modelslab.com/api/agents/v1/billing/stripe-config' \ -H 'Authorization: Bearer ' | jq -r '.publishable_key') # Step 2: Create PM via Stripe (card data stays with Stripe) curl --request POST 'https://api.stripe.com/v1/payment_methods' \ --user "$STRIPE_PK:" \ --data 'type=card' \ --data 'card[number]=4242424242424242' \ --data 'card[exp_month]=12' \ --data 'card[exp_year]=2027' \ --data 'card[cvc]=123' # Step 3: Subscribe with the pm_id curl --request POST 'https://modelslab.com/api/agents/v1/subscriptions' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: sub-plan10-20260220' \ --data '{ "plan_id": 10, "payment_method_id": "pm_1Xyz..." }' ``` Parameters: * `plan_id` (required, integer): The plan ID from the `/subscriptions/plans` endpoint * `payment_method_id` (optional, string): Stripe PM ID from the Stripe API. If omitted, falls back to Stripe Checkout redirect. * `success_url` / `cancel_url` (optional): Only used when `payment_method_id` is omitted (Checkout redirect flow). Example response (headless): ```json theme={null} { "data": { "message": "Subscription created.", "subscription": { "id": 45, "plan_id": 10, "feature": "enterprise", "status": "active" }, "stripe_subscription_id": "sub_xxx", "status": "active" }, "error": null, "meta": { "request_id": "..." } } ``` If the card requires 3D Secure, the response returns HTTP 402 with `decline_code` details. Cards requiring authentication should be handled via `modelslab.com/pricing` instead. ### Confirm subscription checkout (Human-Assisted flow) After a human completes a subscription payment via a Stripe Checkout URL (created with `POST /billing/payment-link` with `purpose: "subscribe"`), the agent confirms the session to activate the subscription. The human is redirected to ModelsLab's success page after payment, where the `session_id` is displayed for them to copy and relay back to the agent. ```bash theme={null} curl --request POST 'https://modelslab.com/api/agents/v1/subscriptions/confirm-checkout' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "session_id": "cs_live_..." }' ``` Parameters: * `session_id` (required, string): The Stripe Checkout session ID from `POST /billing/payment-link` response or copied by the human from the success page If the payment hasn't completed yet (human hasn't finished checkout), poll this endpoint with a short delay. Once the session is confirmed, the subscription becomes active immediately. ### Check subscription status ```bash theme={null} curl --request GET 'https://modelslab.com/api/agents/v1/subscriptions/45/status' \ --header 'Authorization: Bearer ' ``` Example response: ```json theme={null} { "data": { "id": 45, "plan_id": 10, "status": "active", "stripe_subscription_id": "sub_xxx", "current_period_start": "2026-02-20T00:00:00Z", "current_period_end": "2026-03-20T00:00:00Z" }, "error": null, "meta": { "request_id": "..." } } ``` Possible `status` values: `active`, `past_due`, `canceled`, `paused`, `trialing`. ### Update subscription plan example ```bash theme={null} curl --request PUT 'https://modelslab.com/api/agents/v1/subscriptions/45' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{"new_plan_id": 456}' ```