Subscriptions

Subscriptions enable customers to make recurring payments for product access. Managing subscriptions requires storing additional customer information to facilitate future charges.

Subscription objects

The following core API resources are essential for subscription management:

How payments work with subscriptions

Payment status

Payment processing varies by payment method and location. Since initial payments can fail (due to incorrect card information or insufficient funds), multiple payment outcomes are possible.

Frame generates a ChargeIntent to track each payment's lifecycle. The ChargeIntent ID links to the Subscription object, and its state determines the subscription status:

Payment succeeded

When payment succeeds, the ChargeIntent status becomes succeeded and the subscription becomes active. At this point, you should grant access to your product. For detailed guidance on subscription lifecycle and provisioning best practices, refer to our guide.

Recurring charges

Frame automates recurring charge management:

• Initiates payments at the start of new billing cycles
• Handles payment retries upon failure, with up to 3 attempts at 24-hour intervals
• Updates subscription status to past_due after initial failure
• Changes status to unpaid after maximum retries, halting further attempts

The subscription lifecycle

This is what the recommended subscription flow looks like:

1. You must have active recurring products, active customers and payment methods that linked to the customers before creating subscription.
2. You create the subscription. The status of the subscription is pending.
3. The customer pays the first invoice.
4. When the payment succeeds: The subscription status moves to active and Frame sends a customer.subscription.created event.
5. When the payment failed: The subscription status moves to incomplete and Frame sends a customer.subscription.incomplete event.
6. You provision access to your product. You can confirm whether the invoice has been paid by setting up an event destination and listening for the customer.subscription.created event, or, you can manually checking the subscription object and looking for subscription.status=active.

Successful payments

Upon successful invoice payment, the subscription becomes active, indicating you should provision product access.

Failed payments

Subscriptions maintain active status while automatic payments succeed. Failed payments trigger:

• Status update to past_due
• Frame initiates recovery attempts based on retry rules
• Status changes to unpaid if recovery fails

Cancel subscriptions

Cancellation prevents new charges and stops automatic payment collection. The subscription becomes unmodifiable, including metadata. If your customer wants to resubscribe, you need to collect new payment information from them and create a new subscription.

Subscription statuses

Subscription events

Frame triggers events for subscription creation and changes. Some events occur immediately upon creation, while others follow billing intervals. We recommend implementing an event destination for monitoring.

Ensure your integration handles events appropriately, such as sending payment failure notifications or managing access revocation upon cancellation.

The following table describes the most common events related to subscriptions and, where applicable, suggests actions for handling the events.