Subscriptions - ModelsLab

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.

curl --request GET 'https://modelslab.com/api/agents/v1/subscriptions/plans' \
  --header 'Authorization: Bearer <agent_access_token>' \
  --header 'Accept: application/json'

Response structure:

{
  "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 for details):

# Step 1: Fetch Stripe publishable key
STRIPE_PK=$(curl -s 'https://modelslab.com/api/agents/v1/billing/stripe-config' \
  -H 'Authorization: Bearer <agent_access_token>' | 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 <agent_access_token>' \
  --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):

{
  "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.

curl --request POST 'https://modelslab.com/api/agents/v1/subscriptions/confirm-checkout' \
  --header 'Authorization: Bearer <agent_access_token>' \
  --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

curl --request GET 'https://modelslab.com/api/agents/v1/subscriptions/45/status' \
  --header 'Authorization: Bearer <agent_access_token>'

Example response:

{
  "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

curl --request PUT 'https://modelslab.com/api/agents/v1/subscriptions/45' \
  --header 'Authorization: Bearer <agent_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{"new_plan_id": 456}'

​Endpoints

​Discover available plans

​Create subscription (Headless — Recommended for Agents)

​Confirm subscription checkout (Human-Assisted flow)

​Check subscription status

​Update subscription plan example

Endpoints

Discover available plans

Create subscription (Headless — Recommended for Agents)

Confirm subscription checkout (Human-Assisted flow)

Check subscription status

Update subscription plan example