How subscriptions work

A subscription is a recurring lifecycle, not a one-time payment. It connects a customer, one or more recurring prices, billing periods, invoices, payment collection, statuses, and events.

Your integration owns the product-access decision. Paypercut sends server-side events and exposes API objects that let your backend decide when to grant, extend, recover, or revoke access.

What this page covers

The objects involved in a subscription integration
How invoices and payments relate to billing periods
Which actor owns each part of the flow
Common misunderstandings that cause incorrect access decisions

Object model

Object	Role
Customer	The buyer or account owner being billed.
Product / Price	The plan and billing terms, such as EUR 19.00 per month.
Checkout Session	The customer-facing signup flow when Paypercut collects payment details.
Subscription	The recurring agreement that tracks the customer, items, status, and billing cadence.
Invoice	The billing-period record. It tells you what Paypercut attempted to collect for a period.
Payment / PaymentIntent	The payment-level attempt used to collect money.
Webhook event	The server-side signal that Checkout, invoice, or payment state changed.

Actor ownership

Actor	Responsibility
Customer	Completes Checkout and provides payment details.
Your frontend	Sends the customer to Checkout or embeds the Checkout experience.
Your backend	Creates Checkout Sessions, stores IDs, receives webhooks, retrieves latest state, and grants or extends access.
Paypercut	Hosts Checkout, creates the subscription flow, collects payments, creates invoices, and sends events.

Lifecycle model

Your backend creates or selects a recurring Price.
Your backend creates a Checkout Session in subscription mode.
The customer completes Checkout.
Paypercut creates or links the subscription and collects payment through the Checkout flow.
Paypercut sends checkout_session.completed.
Paypercut sends invoice events for paid or failed billing periods.
Your backend updates access from confirmed server-side state.

The important distinction is between Checkout completion and paid-period confirmation:

checkout_session.completed tells you the customer completed Checkout and lets you retrieve the session and linked subscription.
invoice.paid tells you an invoice for a billing period was paid.
invoice.payment_failed tells you payment collection failed and your recovery flow should start.

What to store

Store identifiers in your own database so future events can be reconciled to the right user, account, workspace, or tenant.

Store	Why
Internal user or account ID	Connects Paypercut events to your product account.
`customer_id`	Lets you look up the Paypercut Customer.
`price_id`	Connects the plan purchased to your entitlement model.
`checkout_session_id`	Lets you reconcile the signup flow.
`subscription_id`	Lets you retrieve and reconcile the recurring lifecycle.
Relevant `invoice_id` values	Lets you make billing-period decisions idempotently.
Webhook event or delivery IDs	Prevents duplicate processing when events are retried.

Common misunderstandings

The success URL is not access proof

The customer can return to your success URL before your backend has processed the server-side state you need. Browser redirects can also be interrupted or replayed. Use the success URL to show a pending or confirmation UI, then let your backend grant access after confirmed events or retrieved state.

Renewal events matter

A subscription integration is not complete after the first signup. Renewal payments can succeed or fail later. Handle invoice.paid and invoice.payment_failed so access stays aligned with billing state.

PaymentIntent events are not the primary subscription state

Payment and PaymentIntent events are useful for reconciliation and debugging individual payment attempts. For subscription access, use invoice events and subscription state because invoices represent billing periods.

Public subscription webhooks are not currently the beginner contract

The current public event model for subscription integrations uses Checkout, invoice, and payment events. Do not build against subscription.created, subscription.updated, or subscription.canceled unless those events are exposed in the public API reference for your account.

Overview

Choose a flow