BillingEntitlementChangedPayload billing.entitlement.changed@1

Generated at from openvibe-contracts v0.114.0 and openvibe-sdk v0.35.1.

Version
1.0.0
Owner
billing
Visibility
first-party
Status
active
Compatibility
backward
Decision
ADR-012
Schema
https://openvibe.network/contracts/events/payloads/billing.entitlement.changed.v1.json

billing.entitlement.changed v1 (OpenVibe.Billing server/ops/subscriptions.js pay, setStatus, revokeForTxn; entitlement()). A subscriber's channel-subscription entitlement to a streamer changed: a period was granted or renewed, the subscription ended or expired, or a reversed payment revoked a period. The payload is the entitlement as of now. Envelope: subject { type: entitlement, id: <subscriber usr_…>:channel_subscription:<streamer usr_…> }, visibility internal, priority important, actor service:billing.

Fields

FieldTypeRequiredDescriptionConstraints
subjectidentity.subject-refyes
streameridentity.subject-refyes
kindconstyes
  • = "channel_subscription"
activebooleanyes
expires_atstring | nullyes
  • format date-time
subscriptionobject | nullyes
reasonstringyesgranted, renewed, canceled, expired, stripe_not_renewed, stripe_deleted, renewal_insufficient_credit, refund, chargeback, renewal_failed (a renewal charge failed: status past_due, grace_until set), grace_ended (the grace window passed without a paid renewal), credit_refund (a credit-paid period was refunded).
transaction_idstringgranted/renewed: the transaction that paid the period.
  • pattern ^txn_[0-9A-HJKMNP-TV-Z]{26}$
grace_untilstring | nullrenewal_failed: when Billing stops retrying the renewal and ends the subscription; null or absent otherwise.
  • format date-time
renewal_period_endstringrenewal_failed, grace_ended: the end of the period the failed renewal charge was for.
  • format date-time
revoked_periodobjectrefund/chargeback/credit_refund: the period the reversed payment had granted.
  • no other fields
revoked_period.starts_atstringyes
  • format date-time
revoked_period.ends_atstringyes
  • format date-time

Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

Valid: grace-ended
{
  "subject": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPR"
  },
  "streamer": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  },
  "kind": "channel_subscription",
  "active": false,
  "expires_at": "2026-10-23T10:00:00.000Z",
  "subscription": {
    "id": "sub_01JAB3C4D5E6F7G8H9J0K1MNQ0",
    "status": "expired",
    "auto_renew": false,
    "cancel_at_period_end": false,
    "provider": "credit"
  },
  "reason": "grace_ended",
  "grace_until": null,
  "renewal_period_end": "2026-11-23T10:00:00.000Z"
}
Valid: granted
{
  "subject": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPR"
  },
  "streamer": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  },
  "kind": "channel_subscription",
  "active": true,
  "expires_at": "2026-10-23T10:00:00.000Z",
  "subscription": {
    "id": "sub_01JAB3C4D5E6F7G8H9J0K1MNQ0",
    "status": "active",
    "auto_renew": true,
    "cancel_at_period_end": false,
    "provider": "credit"
  },
  "reason": "granted",
  "transaction_id": "txn_01JAB3C4D5E6F7G8H9J0K1MNQ4"
}
Valid: refund-revoked
{
  "subject": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPR"
  },
  "streamer": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  },
  "kind": "channel_subscription",
  "active": false,
  "expires_at": null,
  "subscription": {
    "id": "sub_01JAB3C4D5E6F7G8H9J0K1MNQ0",
    "status": "expired",
    "auto_renew": false,
    "cancel_at_period_end": false,
    "provider": "credit"
  },
  "reason": "refund",
  "revoked_period": {
    "starts_at": "2026-09-23T10:00:00.000Z",
    "ends_at": "2026-10-23T10:00:00.000Z"
  }
}
Valid: renewal-failed-past-due
{
  "subject": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPR"
  },
  "streamer": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  },
  "kind": "channel_subscription",
  "active": false,
  "expires_at": "2026-10-23T10:00:00.000Z",
  "subscription": {
    "id": "sub_01JAB3C4D5E6F7G8H9J0K1MNQ0",
    "status": "past_due",
    "auto_renew": true,
    "cancel_at_period_end": false,
    "provider": "credit"
  },
  "reason": "renewal_failed",
  "grace_until": "2026-10-26T10:00:00.000Z",
  "renewal_period_end": "2026-11-23T10:00:00.000Z"
}
Rejected: other-kind
{
  "subject": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPR"
  },
  "streamer": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  },
  "kind": "network_membership",
  "active": true,
  "expires_at": "2026-10-23T10:00:00.000Z",
  "subscription": {
    "id": "sub_01JAB3C4D5E6F7G8H9J0K1MNQ0",
    "status": "active",
    "auto_renew": true,
    "cancel_at_period_end": false,
    "provider": "credit"
  },
  "reason": "granted",
  "transaction_id": "txn_01JAB3C4D5E6F7G8H9J0K1MNQ4"
}
Rejected: unknown-status
{
  "subject": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPR"
  },
  "streamer": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  },
  "kind": "channel_subscription",
  "active": false,
  "expires_at": null,
  "subscription": {
    "id": "sub_01JAB3C4D5E6F7G8H9J0K1MNQ0",
    "status": "grace",
    "auto_renew": true,
    "cancel_at_period_end": false,
    "provider": "credit"
  },
  "reason": "renewal_failed"
}

Validate

const contracts = require('openvibe-contracts');
contracts.validate('billing.entitlement.changed@1', value);   // { valid, errors: [{ path, message }] }