Billing and overage

See the plan, start checkout, open the billing portal, and set an overage ceiling. Changing any of those needs the owner, signed in.

Billing is at /settings/billing. It shows the plan in force, usage against the inclusion, checkout for a paid plan, the billing portal, and the overage switch.

Overage is off until an owner turns it on. While overage is off, sending pauses at the inclusion. The ceiling is at most 10 times that inclusion. An admin cannot turn it on.

What the screen calls

GET /billing and GET /billing/subscription are how the screen reads the plan. A management key can read them.

curl -sS -X GET https://api.agentisend.com/billing \
  -H "Authorization: Bearer $AGENTISEND_API_KEY"

200
{
  "currency": "example",
  "limits": [],
  "next_tier": {
    "id": "example",
    "included_emails_per_month": -9007199254740991,
    "max_domains": -9007199254740991,
    "max_seats": -9007199254740991,
    "monthly_price_minor": -9007199254740991,
    "name": "example",
    "overage_minor_per_1000_emails": -9007199254740991,
    "retention_days": -9007199254740991
  },
  "overage": {
    "auto_charges": false,
    "available": false,
    "cap_emails": -9007199254740991,
    "consumed_this_period": -9007199254740991,
    "enabled": false,
    "policy": "pause",
    "rate_minor_per_1000": -9007199254740991,
    "text": "example"
  },
  "payment": {
    "text": "example",
    "writes_enabled": false
  },
  "period": {
    "days": -9007199254740991,
    "resets_at": "2026-09-04T09:14:00.000Z",
    "started_at": "2026-09-04T09:14:00.000Z"
  },
  "plan": {
    "id": "example",
    "included_emails_per_month": -9007199254740991,
    "max_domains": -9007199254740991,
    "max_seats": -9007199254740991,
    "monthly_price_minor": -9007199254740991,
    "name": "example",
    "overage_minor_per_1000_emails": -9007199254740991,
    "retention_days": -9007199254740991
  },
  "pricing_document_version": -9007199254740991
}

Response

curl -sS -X GET https://api.agentisend.com/billing/subscription \
  -H "Authorization: Bearer $AGENTISEND_API_KEY"

200
{
  "billing_configured": false,
  "billing_term": "month",
  "entitlements": {
    "included_emails_per_month": -9007199254740991,
    "max_domains": -9007199254740991,
    "max_seats": -9007199254740991,
    "overage_minor_per_1000_emails": -9007199254740991,
    "retention_days": -9007199254740991,
    "tier": "free"
  },
  "needs_plan_selection": false,
  "plan_source": "free",
  "plan_status": "none",
  "plans": [],
  "purchasable": [],
  "subscription": {
    "cancel_at_period_end": false,
    "current_period_end": "2026-09-04T09:14:00.000Z",
    "price_lookup_key": "example",
    "status": "example"
  },
  "terms_on_sale": [],
  "tier": "free",
  "viewer": {
    "can_purchase": false,
    "role": "owner"
  }
}

Response

Changing money needs the owner, signed in to the console. An API key is refused, and so is an admin:

PUT /billing/overage turns the ceiling on or off.
POST /billing/checkout starts a paid plan.
POST /billing/portal opens the billing portal.

curl -sS -X PUT https://api.agentisend.com/billing/overage \
  -H "Authorization: Bearer $AGENTISEND_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

200
{
  "auto_charges": false,
  "available": false,
  "cap_emails": -9007199254740991,
  "consumed_this_period": -9007199254740991,
  "enabled": false,
  "policy": "pause",
  "rate_minor_per_1000": -9007199254740991,
  "text": "example"
}

Response

curl -sS -X POST https://api.agentisend.com/billing/checkout \
  -H "Authorization: Bearer $AGENTISEND_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"tier":"starter"}'

201
{
  "checkout_session_id": "example",
  "url": "https://yourapp.com/hooks/agentisend"
}

Response

curl -sS -X POST https://api.agentisend.com/billing/portal \
  -H "Authorization: Bearer $AGENTISEND_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

201
{
  "url": "https://yourapp.com/hooks/agentisend"
}

Response

A key on those three:

{
  "error": {
    "code": "session_required",
    "message": "You are signed out.",
    "fix": "Sign in to the console, then retry. API keys cannot call this route.",
    "docs_url": "https://agentisend.com/docs/errors#session_required",
    "retryable": false
  }
}

An admin, or a viewer, on those three:

{
  "error": {
    "code": "insufficient_role",
    "message": "Your role on this account cannot make this change.",
    "fix": "Ask an owner to make the change, or to raise your role with PATCH /team/members/:id.",
    "docs_url": "https://agentisend.com/docs/errors#insufficient_role",
    "retryable": false
  }
}

Overage on the Free plan:

{
  "error": {
    "code": "overage_not_on_plan",
    "message": "Overage is available on Starter, Pro and Scale. This account is on Free, which pauses at its inclusion.",
    "fix": "Choose a paid plan in Settings → Billing, then turn overage on.",
    "docs_url": "https://agentisend.com/docs/errors#overage_not_on_plan",
    "retryable": false
  }
}

The inclusion and the ceiling both used up:

{
  "error": {
    "code": "overage_cap_reached",
    "message": "This account has used every email in its plan and every extra email its owner allowed this period.",
    "fix": "Raise the overage ceiling or move up a plan in Settings → Billing, or wait until the reset date in this error.",
    "docs_url": "https://agentisend.com/docs/errors#overage_cap_reached",
    "retryable": false
  }
}

Checkout for a tier that cannot be bought, or while a subscription is already active:

{
  "error": {
    "code": "plan_not_purchasable",
    "message": "This tier cannot be bought through checkout.",
    "fix": "Pass one of the tier ids listed under `plans` by GET /billing/plan (starter, pro, scale) to POST /billing/checkout.",
    "docs_url": "https://agentisend.com/docs/errors#plan_not_purchasable",
    "retryable": false
  }
}

{
  "error": {
    "code": "subscription_active",
    "message": "This account already has a live subscription.",
    "fix": "Change plans with POST /billing/portal. The billing portal prorates the change and shows the amount before it is confirmed. Checkout is only for an account with no subscription.",
    "docs_url": "https://agentisend.com/docs/errors#subscription_active",
    "retryable": false
  }
}

Purchases unavailable, or no billing customer yet:

{
  "error": {
    "code": "billing_not_configured",
    "message": "Purchases are unavailable right now.",
    "fix": "GET /billing/plan still works, and the account stays on Free.",
    "docs_url": "https://agentisend.com/docs/errors#billing_not_configured",
    "retryable": false
  }
}

{
  "error": {
    "code": "billing_customer_missing",
    "message": "This account has no billing customer yet.",
    "fix": "Start a subscription with POST /billing/checkout first; the customer portal only exists once a checkout has run.",
    "docs_url": "https://agentisend.com/docs/errors#billing_customer_missing",
    "retryable": false
  }
}

PreviousSecurity NextNotifications