cred.diy/ docs
    Sign inGet an API key
    All documentation

    Subscriptions - cred.diy API documentation

    Subscriptions

    Charge customers monthly and add credits after every paid invoice. A checkout becomes recurring only when the request explicitly sends billing: "recurring".

    POSThttps://eutdgemlrpvnxfkkpvlu.supabase.co/functions/v1/hosted-checkout

    Start a monthly subscription. The pricing tier must support recurring billing. Omitting billing always creates a one-time checkout.

    Body parameters

    • user_idstringrequiredYour unique identifier for the customer
    • pricing_tier_idstringrequiredA pricing tier with recurring or both billing enabled
    • billingstringrequiredSet to "recurring"
    • user_emailstringCustomer email
    • success_urlstringHTTPS redirect after checkout
    • cancel_urlstringHTTPS redirect when checkout is canceled

    Example request

    curl -X POST "https://eutdgemlrpvnxfkkpvlu.supabase.co/functions/v1/hosted-checkout" \
  -H "x-api-key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "user_email": "user@example.com",
    "pricing_tier_id": "tier_monthly",
    "billing": "recurring"
  }'

    Response

    {
  "url": "https://checkout.stripe.com/...",
  "session_id": "cs_...",
  "purchase_id": "purchase_..."
}
    GET/subscriptions

    List subscriptions by customer or status. status=active includes active, trialing, and past_due subscriptions.

    Query parameters

    • user_idstringFilter by external user ID
    • emailstringFilter by customer email
    • statusstringactive or an exact Stripe subscription status

    Example request

    curl -X GET "https://eutdgemlrpvnxfkkpvlu.supabase.co/functions/v1/credits-api/subscriptions?email=user@example.com&status=active" \
  -H "x-api-key: sk_live_your_api_key"

    Response

    {
  "subscriptions": [{
    "id": "subscription_...",
    "stripe_subscription_id": "sub_...",
    "user_id": "user_123",
    "user_email": "user@example.com",
    "credits_per_period": 1000,
    "price": "10.00",
    "currency": "USD",
    "interval": "month",
    "status": "active",
    "current_period_end": "2026-11-02T19:00:00Z",
    "cancel_at_period_end": false
  }]
}
    POST/subscriptions/cancel

    Cancel one subscription by ID, or every live subscription for a customer by user ID or email. Cancellation defaults to the end of the paid period and is idempotent.

    Body parameters

    • subscription_idstringCred subscription ID or Stripe sub_ ID
    • user_idstringCancel all live subscriptions for this user
    • emailstringCancel all live subscriptions for this email
    • at_period_endbooleanDefault true; false stops immediately without a refund

    Example request

    curl -X POST "https://eutdgemlrpvnxfkkpvlu.supabase.co/functions/v1/credits-api/subscriptions/cancel" \
  -H "x-api-key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "subscription_id": "sub_123", "at_period_end": true }'

    Response

    {
  "success": true,
  "at_period_end": true,
  "subscriptions": [{ "id": "subscription_...", "status": "active", "cancel_at_period_end": true }]
}
    POST/subscriptions/portal

    Create a short-lived Stripe-hosted link for updating a payment method or viewing invoices. Create it when the customer clicks; do not store it. Plan changes and cancellation are disabled.

    Body parameters

    • subscription_idstringCred subscription ID or Stripe sub_ ID
    • user_idstringUse this customer's most recent subscription
    • emailstringUse this customer's most recent subscription
    • return_urlstringHTTPS page to return to
    • flowstring"payment_method_update" (default) or "overview"

    Example request

    curl -X POST "https://eutdgemlrpvnxfkkpvlu.supabase.co/functions/v1/credits-api/subscriptions/portal" \
  -H "x-api-key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@example.com", "flow": "payment_method_update" }'

    Response

    {
  "url": "https://billing.stripe.com/p/session/...",
  "subscription": { "id": "subscription_...", "status": "past_due" }
}

    Renewals and lifecycle events

    Credits are issued once per paid invoice, including the first invoice and every renewal. Own-keys renewals and cancellations can take up to about ten minutes to appear; Stripe Connect events arrive immediately.

    • subscription.created — first checkout completed
    • subscription.renewed — invoice paid and credits added
    • subscription.cancel_scheduled — cancellation set for period end
    • subscription.canceled — subscription ended
    • subscription.payment_failed — payment failed; create a portal link when the customer chooses to fix it

    Your first credit is one request away.

    Create a project, copy an API key, and issue a credit from your server.

    Get an API keyOpen the dashboard