Stripe

Stripe charges the customer; Oclavex licenses them. Keep the two in sync by turning Stripe’s subscription events into entitlement changes. There is no Stripe code to install — you relay Stripe’s webhooks to Oclavex’s REST API and key everything on an external reference.

The setup

Stripe subscription event
   → your relay (a Zapier Zap, or a small function)
      → Oclavex REST API, keyed on the Stripe id

The relay is where the mapping lives. Zapier is the quickest relay to set up; a serverless function that verifies Stripe’s signature and calls the API works identically.

Tie an entitlement to a Stripe id

When you create the entitlement, stamp the Stripe ids onto it:

• externalReference → stripe:subscription:sub_…
• customerExternalReference → stripe:customer:cus_…

Oclavex does not interpret these values — it stores them verbatim and indexes them per tenant. From then on your relay can find the right entitlement without keeping its own id map:

GET /api/v1/provision/admin/entitlements/by-external-reference/stripe:subscription:sub_1234

The lookup also matches archived and canceled entitlements, so re-delivering the same event is safe — you update the existing entitlement instead of creating a duplicate.

Map events to entitlement actions

Stripe event	What it means	Do in Oclavex
customer.subscription.created (active)	New paid subscription	Create an entitlement from an offer, set the external references, enable activations
customer.subscription.created (trialing)	Trial started	Same, on your trial offer
customer.subscription.updated → active	Recovered or un-paused	Resume; enable activations
customer.subscription.updated → plan change	Upgrade / downgrade	Apply the matching plan
invoice.payment_failed → past due	Payment problem	Pause — activations are refused until it resolves
customer.subscription.paused	Paused by the customer	Pause
customer.subscription.deleted (canceled)	Churn	Cancel — disable activations

Each action is one REST call — create, apply-plan, pause, resume, enable/disable activations. The exact endpoints and payloads are in the REST API reference; the entitlement operations themselves are covered in Entitlement operations.

Payment failures and holds

A failed payment should stop new activations without destroying the entitlement. Pause does that: the entitlement stays configured but refuses to issue activations, so an app trying to check out a seat gets a clear “on hold” refusal. When Stripe reports the payment recovered, resume lifts the hold and activations work again. Cancellation is the terminal step — reserve it for a truly ended subscription.

Read license state back into Stripe

The flow runs the other way too. Subscribe a webhook (see Zapier) to MeteredUsage.OverageStatusChanged and Entitlement.*, and your relay can push consumption and license state onto the Stripe customer’s metadata — so support and finance see, next to the invoice, how much of the plan the customer is actually using.

A managed connector is on the roadmap

Today you wire Stripe with the relay-plus-REST pattern above, which gives you full control over the mapping. A managed Stripe connector — where a single subscription event provisions, pauses or cancels from an offer automatically — is planned; it will use the same external-reference convention, so anything you build now carries straight over.

See it live: sign up and try Mirage — the metered-SaaS product this integration serves, with hourly quotas, prepaid credits and an in-app plan upgrade, on a license issued to you.