Billing#

Billing state and entitlement decisions

Get billing state#

GET/organizations/{org_id}/billing/state

Get normalized billing state, including plan, limits, and entitlement decisions.

Parameters#

Name	Type	Location	Required	Description
`org_id`	string	path	Yes	Organization ID

Code Examples#

curl -X GET "https://platform.antfly.io/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/billing/state" \
-H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("https://platform.antfly.io/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/billing/state", {
method: "GET",
headers: {
  Authorization: "Bearer YOUR_TOKEN"
}
});

const data = await response.json();

Responses#

{
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "plan": "free",
  "has_active_plan": true,
  "has_paid_plan": true,
  "has_stripe_customer": true,
  "has_default_payment_method": true,
  "has_stripe_subscription": true,
  "payment_health": "none",
  "subscription": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": "550e8400-e29b-41d4-a716-446655440000",
    "plan_type": "free",
    "status": "active",
    "billing_cycle_start": "2025-10-02T15:30:00Z",
    "billing_cycle_end": "2025-10-02T15:30:00Z",
    "has_stripe_customer": true,
    "has_default_payment_method": true,
    "has_stripe_subscription": true,
    "payment_method": {
      "type": "card",
      "brand": "visa",
      "last4": "4242",
      "exp_month": 12,
      "exp_year": 2028
    },
    "payment_health": "none"
  },
  "entitlements": {},
  "credit_balances": [
    {
      "product_family": "ai",
      "balance": 2500,
      "updated_at": "2025-10-02T15:30:00Z"
    }
  ],
  "spend_limits": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organization_id": "550e8400-e29b-41d4-a716-446655440000",
      "product_family": "cloud",
      "period": "monthly",
      "limit_cents": 0,
      "alert_threshold_cents": 0,
      "enforcement_enabled": true,
      "created_at": "2025-10-02T15:30:00Z",
      "updated_at": "2025-10-02T15:30:00Z"
    }
  ],
  "spend_limit_statuses": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organization_id": "550e8400-e29b-41d4-a716-446655440000",
      "product_family": "cloud",
      "period": "monthly",
      "period_start": "2025-10-02T15:30:00Z",
      "limit_cents": 0,
      "current_spend_cents": 0,
      "remaining_cents": 0,
      "alert_threshold_cents": 0,
      "alert_threshold_met": true,
      "over_limit": true,
      "enforcement_enabled": true,
      "allowed": true,
      "reason": "spend_limit_exceeded",
      "created_at": "2025-10-02T15:30:00Z",
      "updated_at": "2025-10-02T15:30:00Z"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

List credit ledger entries#

GET/organizations/{org_id}/billing/credit-ledger

Get credit ledger entries for an organization, newest first.

Parameters#

Name	Type	Location	Required	Description
`org_id`	string	path	Yes	Organization ID
`product_family`	string	query	No	Optional product-family filter, for example `ai`
`offset`	integer	query	No	Number of items to skip
`limit`	integer	query	No	Maximum number of items to return

Code Examples#

curl -X GET "https://platform.antfly.io/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/billing/credit-ledger?product_family=string&offset=0&limit=20" \
-H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("https://platform.antfly.io/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/billing/credit-ledger?product_family=string&offset=0&limit=20", {
method: "GET",
headers: {
  Authorization: "Bearer YOUR_TOKEN"
}
});

const data = await response.json();

Responses#

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "account_id": "550e8400-e29b-41d4-a716-446655440000",
      "organization_id": "550e8400-e29b-41d4-a716-446655440000",
      "product_family": "ai",
      "entry_type": "grant",
      "amount_delta": 0,
      "balance_after": 0,
      "idempotency_key": "string",
      "source_type": "string",
      "source_id": "string",
      "expires_at": "2025-10-02T15:30:00Z",
      "created_at": "2025-10-02T15:30:00Z"
    }
  ],
  "meta": {
    "offset": 0,
    "limit": 1,
    "total": 0
  }
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

List spend limits#

GET/organizations/{org_id}/billing/spend-limits

Get configured spend limits for an organization.

Parameters#

Name	Type	Location	Required	Description
`org_id`	string	path	Yes	Organization ID

Code Examples#

curl -X GET "https://platform.antfly.io/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/billing/spend-limits" \
-H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("https://platform.antfly.io/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/billing/spend-limits", {
method: "GET",
headers: {
  Authorization: "Bearer YOUR_TOKEN"
}
});

const data = await response.json();

Responses#

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organization_id": "550e8400-e29b-41d4-a716-446655440000",
      "product_family": "cloud",
      "period": "monthly",
      "limit_cents": 0,
      "alert_threshold_cents": 0,
      "enforcement_enabled": true,
      "created_at": "2025-10-02T15:30:00Z",
      "updated_at": "2025-10-02T15:30:00Z"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

Upsert spend limit#

PUT/organizations/{org_id}/billing/spend-limits

Create or update a spend limit for an organization. Requires owner or admin role.

Parameters#

Name	Type	Location	Required	Description
`org_id`	string	path	Yes	Organization ID

Request Body#

{
  "product_family": "cloud",
  "period": "monthly",
  "limit_cents": 0,
  "alert_threshold_cents": 0,
  "enforcement_enabled": true
}

Code Examples#

curl -X PUT "https://platform.antfly.io/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/billing/spend-limits" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"product_family": "cloud",
"period": "monthly",
"limit_cents": 0,
"alert_threshold_cents": 0,
"enforcement_enabled": true
}'

const response = await fetch("https://platform.antfly.io/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/billing/spend-limits", {
method: "PUT",
headers: {
  Authorization: "Bearer YOUR_TOKEN",
  "Content-Type": "application/json"
},
body: JSON.stringify({
  "product_family": "cloud",
  "period": "monthly",
  "limit_cents": 0,
  "alert_threshold_cents": 0,
  "enforcement_enabled": true
})
});

const data = await response.json();

Responses#

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "product_family": "cloud",
  "period": "monthly",
  "limit_cents": 0,
  "alert_threshold_cents": 0,
  "enforcement_enabled": true,
  "created_at": "2025-10-02T15:30:00Z",
  "updated_at": "2025-10-02T15:30:00Z"
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

List spend records#

GET/organizations/{org_id}/billing/spend-records

Get monetary spend records for an organization, newest first.

Parameters#

Name	Type	Location	Required	Description
`org_id`	string	path	Yes	Organization ID
`product_family`	string	query	No	Optional product-family filter, for example `cloud` or `ai`
`offset`	integer	query	No	Number of items to skip
`limit`	integer	query	No	Maximum number of items to return

Code Examples#

curl -X GET "https://platform.antfly.io/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/billing/spend-records?product_family=string&offset=0&limit=20" \
-H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("https://platform.antfly.io/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/billing/spend-records?product_family=string&offset=0&limit=20", {
method: "GET",
headers: {
  Authorization: "Bearer YOUR_TOKEN"
}
});

const data = await response.json();

Responses#

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organization_id": "550e8400-e29b-41d4-a716-446655440000",
      "product_family": "cloud",
      "amount_cents": 0,
      "period_start": "2025-10-02T15:30:00Z",
      "source_type": "string",
      "source_id": "string",
      "idempotency_key": "string",
      "recorded_at": "2025-10-02T15:30:00Z"
    }
  ],
  "meta": {
    "offset": 0,
    "limit": 1,
    "total": 0
  }
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}