Integration guide
From your catalogue to product access.
A server-to-server flow, from your first product to enforced access, controlled consumption and a confirmed plan change. These examples use sayAllow’s existing HTTP API.
Get console access and configure a product. SAYALLOW_URL is your environment’s public API base URL, including its gateway prefix. SAYALLOW_PRODUCT_KEY is your product key, stored in your backend’s secrets.
If your APIM gateway requires a subscription key, also send the Ocp-Apim-Subscription-Key header. It does not replace the product key.
The catalogue
Configure what your product sells.
In the console, create your product, its plans and the features they include. Choose a free or paid plan, its billing cycles, seats and quotas. Your product does not hard-code prices.
For payments, configure Stripe for this product. Hosted Checkout and the billing portal use Stripe; your application does not collect card data.
curl "$SAYALLOW_URL/product/plans" -H "x-clavis-product-key: $SAYALLOW_PRODUCT_KEY"The historical x-clavis-product-key header remains the current HTTP contract.
The customer
Connect an organisation to your customer account.
The organisation represents the team, workspace or billing entity. Create it once and save its identifier in your database. Your backend selects this organisation from the authenticated session.
POST /product/organizations
Content-Type: application/json
x-clavis-product-key: <server-side product key>
{
"name": "Atelier Studio",
"email": "billing@example.com"
}Do not send your product key to the browser. The browser calls your backend, which verifies the account and forwards the request to sayAllow.
Activation
Choose the plan’s flow.
Free plan: direct activation
A kind: free plan is activated from the backend without Stripe or Checkout. Repeating the same activation is idempotent; another current subscription may produce a 409 response.
POST /product/organizations/<organization UUID>/subscriptions
Content-Type: application/json
x-clavis-product-key: <server-side product key>
{ "planId": "<free plan UUID>", "seatCount": 1 }Paid plan: hosted Checkout
Choose a plan returned by the catalogue. Creating Checkout returns a hosted Stripe url and a sessionId. Redirect the customer to that url.
POST /product/checkout
Content-Type: application/json
x-clavis-product-key: <server-side product key>
{
"organizationId": "<organization UUID>",
"planId": "<paid plan UUID>",
"billingCycle": "monthly",
"seatCount": 5,
"successUrl": "https://app.example.com/billing/success",
"cancelUrl": "https://app.example.com/billing"
}Your backend sets return URLs on your product’s allowed origins. Returning to successUrl does not yet prove payment: show a pending state and re-read the subscription.
The access decision
Check an entitlement. Enforce the answer.
After activation, your backend asks whether its organisation may use export:pdf. A plan feature is resolved from its subscription licence; no extra manual grant is required.
GET /product/organizations/<organization UUID>/entitlements/export%3Apdf
x-clavis-product-key: <server-side product key>
HTTP 200
{ "capability": "export:pdf", "granted": true }Your backend turns granted: false into a refusal of that action. Handle API unavailability separately: a network error or 5xx is not an entitlement confirmation. Your application remains responsible for executing the action.
Entitlements are additive: an active manual grant or pack can also grant the capability. Revoking one source does not remove another valid source. GET …/entitlements lists grant history; use the capability check for effective access.
For access granted by a subscription, this boolean check requires a writable subscription and licence. A read-only licence in grace does not grant access through this path. On-premises deployments use the detailed licence contract, signature, expiry and read_only flag to enforce their own degraded mode.
Prepaid consumption
Debit once. Recognise a limit.
Read GET /product/organizations/{id}/credits: balance.available is the usable balance. It is separate from feature entitlements and plan quotas. Reading the balance does not reserve credits; the atomic debit is what accepts or refuses consumption.
POST /product/organizations/<organization UUID>/usage
Content-Type: application/json
x-clavis-product-key: <server-side product key>
{
"action": "export.pdf",
"credits": 1,
"reference": "export-job-2026-001"
}
HTTP 201
{ "id": "<event UUID>", "credits": 1, "reference": "export-job-2026-001" }Derive the reference from your durable operation ID before the first call. Reuse it after a timeout: the same organisation, reference and billable terms return the same event without another debit, including concurrent requests. Reusing a reference with a different action, service or cost returns 409.
The original event’s actor and metadata are retained on replay. Without reference, every call is new consumption: existing clients remain compatible but do not receive this retry guarantee.
HTTP 402
{
"code": "insufficient_credits",
"message": "Not enough credits for this action",
"required": 1,
"available": 0,
"missing": 1
}On 402, do not perform the paid action; offer a top-up. For external work, keep a durable operation with the same reference in your application: an idempotent debit does not automatically make your export, worker or another provider idempotent.
POST /product/packs/<active pack code>/checkout
Content-Type: application/json
x-clavis-product-key: <server-side product key>
{
"organizationId": "<organization UUID>",
"quantity": 1,
"successUrl": "https://app.example.com/credits/success",
"cancelUrl": "https://app.example.com/credits"
}List available packs with GET /product/packs. After confirmed payment, sayAllow credits the account; re-read the balance and retry the refused operation. A 402 did not consume its reference. Do not grant credits from the payment return page.
Postpaid usage
Record metered usage separately.
For a paid subscription, configure its meter and price in the console first. This operation records a positive integer quantity for billing; it does not debit prepaid credits or automatically enforce a plan quota.
POST /product/organizations/<organization UUID>/usage/metered
Content-Type: application/json
x-clavis-product-key: <server-side product key>
{
"metricKey": "api_calls",
"value": 3,
"reference": "request-2026-001"
}The reference is required. The same meter, reference and value return the existing event; a different value returns 409. Free plans are rejected by this flow. The example below uses the credit balance for its hard limit.
pending and sending mean delivery is underway; submitted means the provider accepted the event for asynchronous processing. blocked requires checking configuration. Reconcile the final Stripe invoice: submitted alone does not prove the billed amount.
Changing plans
Keep Free until confirmation.
Create Checkout for the paid plan using the same organizationId. Until paid activation is confirmed, Free remains current and a paid-only feature such as export:batch stays denied. Retrying the same Checkout preserves the upgrade intent.
After a callback or the customer’s return, re-read subscriptions and effective access. Confirmed fulfillment must replace Free and grant the paid feature. A pending state remains pending; a success URL never replaces confirmation.
Changing plans does not automatically top up credits. A top-up is a separate pack purchase. The scenario deliberately checks that the exhausted balance stays zero after upgrade: changing plans and buying credits are different operations.
The executable walkthrough
Run the scenario with your test product.
This Node 22 script installs no SDK. It calls the real API from your machine or backend, keeps retry identifiers in a local file, and stores neither product nor licence keys. It creates a dedicated test organisation.
- In the console, create demo-free (Free kind) and demo-pro (paid), with compatible seat limits. Attach the paid plan to its test Stripe price and selected billing cycle.
- Include export:pdf in both plans; add export:batch only to demo-pro. Set these before subscribing: editing the plan later does not rewrite issued licences.
- Use that product’s key and test API base URL. Add SAYALLOW_APIM_SUBSCRIPTION_KEY if required by your gateway. Running this script needs no database or Kubernetes access.
curl --fail --output access-journey.mjs https://sayallow.com/examples/access-journey.mjs
export SAYALLOW_URL="<API base URL including gateway prefix>"
export SAYALLOW_PRODUCT_KEY="<test product key>"
node access-journey.mjs start --state /tmp/sayallow-journey.jsonThe script prints organizationId. In Customers, open that organisation and adjust its balance by +3 credits with a trial note. This is an operator’s test grant, separate from a payment. Then continue with the same state file.
node access-journey.mjs credits --state /tmp/sayallow-journey.jsonThe result expects no second debit on replay, a 409 for a changed cost, a final zero balance and a 402 without overdraft on the next operation. References survive an interrupted run.
node access-journey.mjs upgrade --state /tmp/sayallow-journey.json --success-url https://app.example.com/billing/success --cancel-url https://app.example.com/billing
# After the provider confirms the test payment:
node access-journey.mjs verify --state /tmp/sayallow-journey.jsonReplace return URLs with your application’s allowed origins. Open checkoutUrl and complete the provider’s test payment. verify succeeds only after effective activation, export:batch being granted and Free being replaced. Credits remain separate.
Plan and feature keys can be changed with --free-plan, --paid-plan, --capability and --paid-capability. The result measures this run from start, not account preparation or a guaranteed integration time.
Synchronisation
Receive events. Re-read the source of truth.
Configure your backend’s callback URL and signing secret in the console. sayAllow sends events including subscription.updated and subscription.deleted following payment provider events.
- Verify X-Clavis-Signature against the raw body bytes with your callback secret before processing JSON.
- Make processing idempotent on event.id and do not assume callbacks arrive in order.
- Store the event and respond promptly with 2xx. Failed delivery may be retried.
- Re-read GET /product/organizations/{id}/subscriptions on return from Checkout and after an event. A pending status must not unlock paid access.
To let the customer manage billing, create a session with POST /product/billing-portal using organizationId and returnUrl, then redirect to the returned URL.
Ready to configure your first product?
The console brings together your catalogue, organisations and billing.
Open the consoleAn integration question?