Subscription

A Subscription represents a recurring payment agreement between a payer and a service provider. It links a payer to a specific plan defined in a ServiceManifest and tracks the lifecycle — from activation through renewals, pause periods, and eventual cancellation or expiry.

Subscriptions are the backbone of recurring revenue for AI agents. A subscription entitles the payer to a defined quota of service consumption per billing period, with automatic renewal unless explicitly cancelled.

---

Fields

Field	Type	Description
id	string (UUIDv7)	Globally unique subscription identifier
service_id	string	The ServiceManifest id this subscription applies to
plan_id	string	The SubscriptionPlan id within the manifest
payer	Party	Identity of the paying agent / human
status	Status	Current state in the subscription lifecycle
current_period_start	string (ISO 8601)	Start of the current billing period
current_period_end	string (ISO 8601)	End of the current billing period
quota	QuotaUsage	Quota consumption within the current period
auto_renew	boolean	Whether the subscription renews automatically at period end
cancelled_at	string (ISO 8601)	Timestamp of cancellation (if cancelled)
created_at	string (ISO 8601)	Timestamp of subscription creation
updated_at	string (ISO 8601)	Timestamp of last status change

Party

Field	Type	Description
agent_id	string	Unique ID of the paying agent
human_id	string	Optional — ID of the human user on whose behalf the subscription is held

QuotaUsage

Field	Type	Description
total	number	Total quota allocated for this period (from the plan)
used	number	Quota consumed so far in the current period
remaining	number	Quota still available

Status

Status	Description
pending	Subscription created but not yet activated (awaiting first payment)
active	Subscription is active and quota is usable
past_due	Payment for the next period has failed; service may be degraded
cancelled	Subscription was cancelled by the payer or provider (end of current period still honoured)
expired	Subscription has ended (period finished and not renewed)

---

JSON Example

{
  "id": "sub_01J7YA3B4C5D6E7F8G9H0I1J2",
  "service_id": "01J7XYKZ1A2B3C4D5E6F7G8H9I",
  "plan_id": "plan_pro",
  "payer": {
    "agent_id": "agent_cli_a1b2c3d4",
    "human_id": "user_abc_789"
  },
  "status": "active",
  "current_period_start": "2026-05-01T00:00:00Z",
  "current_period_end": "2026-06-01T00:00:00Z",
  "quota": {
    "total": 500,
    "used": 143,
    "remaining": 357
  },
  "auto_renew": true,
  "cancelled_at": null,
  "created_at": "2026-04-28T12:30:00Z",
  "updated_at": "2026-05-27T08:15:00Z"
}

---

State Machine

             ┌──────────┐
             │ pending  │
             └─────┬────┘
                   │ first payment succeeds
                   ▼
            ┌───────────┐
            │  active   │
            └──┬────┬───┘
          auto │    │ payment  │ cancel
        renewal │    │ fails    │ requested
           OK   │    ▼         │
                │ ┌─────────┐  │
                │ │past_due │  │
                │ └────┬────┘  │
                │ retry│       │
                │ OK   │       │
                └──────┘       │
                               ▼
                        ┌───────────┐
                        │ cancelled │
                        └─────┬─────┘
                              │ period ends
                              ▼
                       ┌───────────┐
                       │ expired   │
                       └───────────┘

    active ──period ends, auto_renew=false ──▶ expired
    active ──period ends, auto_renew=true ────▶ active (new period, payment succeeds)
    past_due ──grace period exhausted ────────▶ expired

Transitions

From	To	Trigger
pending	active	First payment intent for the subscription succeeds
active	cancelled	Payer or provider requests cancellation
active	past_due	Renewal payment intent fails or is declined
active	expired	Period ends and auto_renew is false
past_due	active	Retry payment succeeds within the grace period
past_due	expired	Grace period ends without successful payment
cancelled	expired	Current billing period reaches current_period_end

---

Key Behaviors

• Quota resets every period: When a new billing period begins, quota.used resets to 0 and quota.total is refilled according to the plan.
• Auto-renewal: When auto_renew is true, the protocol automatically creates a new PaymentIntent at the end of the current period. If the payment fails, the subscription enters past_due.
• Grace period: Subscriptions in past_due state get a configurable grace period (default: 3 days). During this time, the payer may still access the service, but the provider may apply rate limits or degradation.
• Cancellation is end-of-period: Cancelling a subscription does not immediately revoke access. The subscription transitions to expired at the end of the current billing period.
• Over-quota handling: Once quota.used exceeds quota.total, the provider may either block further requests, apply overage charges (via cumulative billing), or downgrade service quality. The policy is specified in the ServiceManifest's pricing section.