Integration guide

From your catalogue to product access.

From a commercial draft to an active offer, then from confirmed Checkout to product access. Free, credit and historical Plan workflows are explained separately. These examples use sayAllow’s existing HTTP API.

Before you begin

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.

Register your application in Products, then configure source Plans in Catalog. A Free Plan supports direct activation. A paid fixed-price Plan can be copied into an independent commercial offer draft. Your application reads terms from the API.

In Payments, configure the tenant’s Stripe account and link the paid Plan to a compatible price. Hosted Checkout and the billing portal use Stripe; your application does not collect card data.

Read historical and Free Plans from your backend
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.

Prepare, publish, activate

Each offer owns its own draft.

One application can have several commercial offers, each with a stable code and its own history. The Plan is a starting point: once copied, the draft belongs to the offer. Editing it changes neither the shared Plan, published revisions nor already accepted commitments.

  1. In the console, open Products, your application, then Manage offers. Create an offer with a name and a code unique to that application.
  2. Use Prepare a revision to copy a paid fixed-price Plan into the draft. Configure its entitlements, quotas, seats, trial and grace, then use Save draft. Price, currency, cycle and price reference come from the initial Plan copy.
  3. Preview the saved conditions, then publish the version. Publication checks the draft version atomically; a concurrent edit returns 409. The console keeps local edits and asks you to reload explicitly.
  4. Activate the chosen revision separately. Publishing does not activate it: each offer has at most one active version. Deactivate an active version before withdrawing it; withdrawal is irreversible and retains history.

Tenant administrators and members can manage offers; read-only users can inspect history. Registering an application and managing its server keys remain administrator-only. The Hanko session and selected tenant determine permissions. A published but inactive offer is not offered to new subscriptions.

Open applications in the console

Available scope and future work

This CommercialOffer workflow supports fixed pricing, entitlements, quotas, allowed seats, recurring trials and grace. It does not support additional per-seat pricing, coupons, metered billing or a trial on a one-time purchase. Historical Plans, usage meters and credit packs keep their separate workflows.

Contract amendment acceptance, extending this profile to other pricing models and dedicated offerCode SDK methods remain future work. They are not presented here as available.

Backend integration

Resolve active offers by code.

From your application backend, list GET /product/offers or resolve GET /product/offers/{code}. The response exposes code, name, version and terms: published price, currency, cycle, entitlements, quotas and policies. Your application needs neither a hard-coded revision ID nor an Admin key.

HTTP · server-side product key
curl "$SAYALLOW_URL/product/offers" \
  -H "x-clavis-product-key: $SAYALLOW_PRODUCT_KEY"

# Resolve one active offer by its stable code:
curl "$SAYALLOW_URL/product/offers/professional" \
  -H "x-clavis-product-key: $SAYALLOW_PRODUCT_KEY"

Only offers with an active, non-withdrawn revision are listed. A code without an active version returns 404: show it as unavailable and reload offers instead of silently choosing a different price. The product key scopes responses to its application and tenant.

To start Checkout below, send offerCode. sayAllow resolves the active version and freezes its conditions in a persistent commitment. A later activation does not rewrite that Checkout; the provider must confirm payment or the allowed trial before paid access is granted.

These examples call HTTP directly. Existing SDKs retain their historical methods; do not assume they already expose these new operations.

Create Checkout with offerCode

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.

HTTP · example body
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.

Starting the flow

Activate Free or open an offer Checkout.

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.

HTTP · replace the UUIDs
POST /product/organizations/<organization UUID>/subscriptions
Content-Type: application/json
x-clavis-product-key: <server-side product key>

{ "planId": "<free plan UUID>", "seatCount": 1 }

Active offer: hosted Checkout by code

Choose a code returned by GET /product/offers. The backend sends organizationId, offerCode and its return URLs; it sends neither a price nor a revisionId. Creating Checkout returns a hosted Stripe url and a sessionId. Redirect the customer to that url.

HTTP · replace UUIDs and URLs
POST /product/checkout
Content-Type: application/json
x-clavis-product-key: <server-side product key>

{
  "organizationId": "<organization UUID>",
  "offerCode": "professional",
  "successUrl": "https://app.example.com/billing/success",
  "cancelUrl": "https://app.example.com/billing"
}

Compatibility: historical POST /product/checkout with planId remains available. It is separate from the offerCode workflow above and does not provide the same immutable commercial terms.

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.

HTTP · export:pdf
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.

HTTP · body and partial response
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.

An insufficient balance causes no debit
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.

Top up through a pack Checkout
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.

HTTP · api_calls
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 and fixed-price CommercialOffer commitments are rejected by this flow. Use it only with the historical Plan-based metering configuration. 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 active paid offer using offerCode and the same organizationId. The executable scenario below retains the historical planId selector. 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 historical Plan-based scenario with your test product.

This script demonstrates the historical Free → planId flow and credits. For versioned commercial offers, use the offerCode HTTP flow above; corresponding SDK methods are not available yet.

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.

  1. 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.
  2. Include export:pdf in both plans; add export:batch only to demo-pro. Set these before subscribing. The historical planId flow may still read Plan policies; use the published offers described above to retain accepted terms.
  3. 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.
Download the Node script
1 · Activate Free and check its features
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.json

The 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.

2 · Debit 1 then 2, replay and reach the limit
node access-journey.mjs credits --state /tmp/sayallow-journey.json

The 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.

3 · Open Checkout, pay in test mode, then verify the upgrade
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.json

Replace 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.

For invoices, payment methods and permitted operations, create POST /product/billing-portal using organizationId and returnUrl. For an offerCode commitment, a price or Plan change requires a new contractual decision; that amendment acceptance workflow is not available yet.

Ready to configure your first product?

The console brings together your catalogue, organisations and billing.

Open the consoleAn integration question?