Engramma

Billing

beginner

Plans, subscriptions, invoices, upgrades, downgrades, and payment management endpoints.

List plans

GET/v1/billing/plans

List all available plans with features and pricing.

200Response
[
  {
    "id": "free",
    "name": "Free",
    "price_monthly": 0,
    "price_yearly": 0,
    "price_monthly_cents": 0,
    "price_annual_cents": 0,
    "max_patterns": 5000,
    "max_queries_day": 1000,
    "compose_per_day": 100,
    "max_api_keys": 2,
    "max_members": 1,
    "retention_days": 30,
    "features": [
      "text_api",
      "vector_api",
      "causal",
      "consolidation"
    ]
  },
  {
    "id": "starter",
    "name": "Starter",
    "price_monthly": 29,
    "price_yearly": 278.4,
    "price_monthly_cents": 2900,
    "price_annual_cents": 27840,
    "max_patterns": 10000,
    "max_queries_day": 10000,
    "compose_per_day": 500,
    "max_api_keys": 5,
    "max_members": 3,
    "retention_days": 90,
    "features": [
      "text_api",
      "vector_api",
      "causal",
      "consolidation",
      "webhooks",
      "hdc"
    ]
  },
  {
    "id": "pro",
    "name": "Pro",
    "price_monthly": 79,
    "price_yearly": 758.4,
    "price_monthly_cents": 7900,
    "price_annual_cents": 75840,
    "max_patterns": 100000,
    "max_queries_day": -1,
    "compose_per_day": -1,
    "max_api_keys": 20,
    "max_members": 10,
    "retention_days": 365,
    "features": [
      "text_api",
      "vector_api",
      "causal",
      "consolidation",
      "webhooks",
      "hdc",
      "xai",
      "tiered_storage"
    ]
  },
  {
    "id": "scale",
    "name": "Scale",
    "price_monthly": 249,
    "price_yearly": 2390.4,
    "price_monthly_cents": 24900,
    "price_annual_cents": 239040,
    "max_patterns": 1000000,
    "max_queries_day": -1,
    "compose_per_day": -1,
    "max_api_keys": 100,
    "max_members": 50,
    "retention_days": -1,
    "features": [
      "text_api",
      "vector_api",
      "causal",
      "consolidation",
      "webhooks",
      "hdc",
      "xai",
      "tiered_storage",
      "priority_support"
    ]
  }
]
Info

A max_queries_day of -1 means unlimited. Prices in EUR.

Get subscription

GET/v1/billing/subscription

Get current subscription details for your organization (resolved from JWT/API key).

200Response
{
  "subscription_id": "sub_abc123",
  "plan_id": "pro",
  "status": "active",
  "current_period_start": "2026-01-15T00:00:00Z",
  "current_period_end": "2026-02-15T00:00:00Z",
  "cancel_at": null,
  "trial_end": null,
  "dunning_state": null
}

Create checkout session

POST/v1/billing/checkout

Create a Stripe checkout session to subscribe or change plan.

plan_idstringrequired

Plan to subscribe to: starter, pro, scale.

intervalstringDefault: month

Billing interval: month or year.

200Response
{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_...",
  "session_id": "cs_abc123"
}

Customer portal

POST/v1/billing/portal

Create a Stripe customer portal session for managing payment methods and invoices.

200Response
{
  "portal_url": "https://billing.stripe.com/p/session/..."
}

Upgrade plan

POST/v1/billing/upgrade

Upgrade to a higher plan. Takes effect immediately with prorated charge.

plan_idstringrequired

Target plan (must be higher than current).

intervalstringDefault: month

Billing interval: month or year.

200Response
{
  "subscription_id": "sub_abc123",
  "plan_id": "scale",
  "status": "active",
  "current_period_start": "2026-01-15T00:00:00Z",
  "current_period_end": "2026-02-15T00:00:00Z",
  "cancel_at": null,
  "trial_end": null,
  "dunning_state": null
}

Downgrade plan

POST/v1/billing/downgrade

Downgrade to a lower plan. Takes effect at the end of the current billing period.

plan_idstringrequired

Target plan (must be lower than current).

200Response
{
  "subscription_id": "sub_abc123",
  "plan_id": "starter",
  "status": "active",
  "current_period_start": "2026-01-15T00:00:00Z",
  "current_period_end": "2026-02-15T00:00:00Z",
  "cancel_at": null,
  "trial_end": null,
  "dunning_state": null
}
Warning

If your current usage exceeds the new plan's limits, you won't lose data but new stores will be blocked until you reduce pattern count.

Cancel subscription

POST/v1/billing/cancel

Cancel the subscription.

reasonstring | null

Optional cancellation reason.

immediatebooleanDefault: false

If true, cancel immediately instead of at period end.

200Response
{
  "status": "cancelling",
  "cancel_at": "2026-02-15T00:00:00Z",
  "message": "Subscription will end at the current period end"
}

Reactivate subscription

POST/v1/billing/reactivate

Reactivate a cancelled subscription before it expires.

200Response
{
  "subscription_id": "sub_abc123",
  "plan_id": "pro",
  "status": "active",
  "cancel_at": null
}

List invoices

GET/v1/billing/invoices

List all invoices.

200Response
[
  {
    "invoice_id": "inv_abc123",
    "amount_due": 7900,
    "amount_paid": 7900,
    "currency": "eur",
    "status": "paid",
    "period_start": "2026-01-15T00:00:00Z",
    "period_end": "2026-02-15T00:00:00Z",
    "pdf_url": "https://pay.stripe.com/invoice/...",
    "hosted_invoice_url": "https://invoice.stripe.com/i/..."
  }
]

Upcoming invoice

GET/v1/billing/upcoming-invoice

Preview the next invoice.

200Response
{
  "amount_due": 7900,
  "currency": "eur",
  "period_start": "2026-02-15T00:00:00Z",
  "period_end": "2026-03-15T00:00:00Z",
  "lines": []
}

Retry payment

POST/v1/billing/retry-payment

Retry a failed payment.

200Response
{
  "message": "Payment retry initiated"
}

Next steps

OrganizationsWebhooks