API Product Subscription

An API Product Subscription records that one Consumer (the subscriber) holds one API Product for a period, with a status. | |The API Product describes the plan: which endpoints (its API Collection), how many calls (six rate limits), the monthly price, and any attributes. The Subscription is the record of who holds it. Its status is what makes the product enforceable: | |- requested: created, nothing granted yet. |- active: OBP-API has given the Consumer a rate limit record with the product's six limits, and a Scope for each Role required by the endpoints in the product's Collection. |- past_due: payment is overdue. A grace period; nothing changes for the Consumer. |- suspended: the subscription's rate limit record is set to 0 in every period, which blocks the Consumer's calls. Scopes are kept so reinstatement is cheap. |- cancelled: the rate limit record and the derived Scopes are removed. Terminal; a new subscription is a new record. | |Only the rate limit record and the Scopes created by the subscription are touched. Limits and Scopes granted by hand are never removed. Overlapping rate limit records are summed, so a Consumer holding two products gets both allowances. | |A developer never needs a Role to subscribe their own Consumer, read their own subscriptions or cancel them. Roles exist for bank staff (enrol a partner's Consumer, approve, suspend, reinstate) and for billing systems (move the status on payment events). Two attributes on the API Product decide the flow: SELF_SUBSCRIBE (may developers subscribe their own Consumers; default true) and BILLING_SYSTEM (none activates at once; manual waits for a bank admin; stripe or invoice_ninja waits for that billing system). | |OBP-API core carries no billing vocabulary: payments, invoices and refunds live in the billing system, which only ever changes the subscription status. |