Configure the Suger Channel¶

Suger is the aggregator that holds your AWS, Azure and GCP listings and reports one entitlement shape to Omnistrate. Connecting it is a one-time setup in FinOps Center → Marketplace Channels.

Before You Start¶

You need three things from Suger, and one thing from your own product:

1. A Suger organization with a marketplace product/listing, offers, and commercial terms already configured. Complete listing publication and marketplace review in Suger and the target cloud marketplace; Omnistrate maps existing Suger products/listings but does not publish them.
2. An OAuth app created under Suger's organization settings. Suger deprecated API key authentication, so Omnistrate uses the OAuth client ID and secret to authenticate to Suger.
3. The webhook signing secret Suger shows you, so Omnistrate can verify inbound webhooks from it.
4. A callback URL on your own portal, where buyers land after onboarding.

Register the Landing URL First¶

Open the Suger card and the drawer shows your Omnistrate landing URL before it asks for anything else. That is deliberate: this URL has to be registered in Suger before a purchase can reach you, and you can copy it before you have credentials.

Register it in Suger, the product configuration, in the field named Signup URL.

The Configuration Fields¶

Billing provider¶

Read-only, and locked to Suger. Contracts on this channel are billed by the channel, and usage is reported with the same credential. A channel and the provider that collects for it are not independently choosable, so this is shown rather than asked.

Organization ID¶

The Suger organization that holds your listings. Format org_123456.

OAuth client ID¶

From Suger organization settings → API Client → OAuth Apps. Shown once when the app is created.

This is not a password field, on purpose. It is an identifier that authorizes nothing on its own, and you need to read it back to compare against the OAuth app in Suger's console — which is exactly what you will be doing if a grant is ever refused.

OAuth client secret¶

The other half of the OAuth app. It is write-only in Omnistrate, so keep a copy.

Webhook signing secret¶

Verifies inbound webhooks from Suger to Omnistrate. Contract reads work without it; webhooks are refused until it is set.

Register the Inbound Webhook¶

The Signup URL handles the initial browser arrival, but later marketplace lifecycle changes reach Omnistrate through a separate webhook.

1. Open the channel's Event routing tab.
2. Copy the read-only Webhook URL for Suger.
3. In Suger, open Settings → Notification → Webhook and paste the URL into the Webhook field.
4. In the channel's Configuration tab, enter the webhook signing secret that Suger uses for this webhook.

Without this registration, a purchase can still arrive through the Signup URL, but suspension, reinstatement, pending-cancellation, cancellation, and termination notifications do not reach Omnistrate.

Configure the Buyer Handoff and Event Routing¶

ISV portal callback URL — required¶

Omnistrate sends the buyer here once onboarding completes, appending ?code= to this URL. Your portal redeems that code server-side to establish the session.

HTTPS only, and no query string of your own — Omnistrate appends one.

This is a user-facing page. A buyer's browser lands on it.

contract.discovered receiver — optional¶

In Event routing, configure a receiver URL for contract.discovered when you want the initial handoff delivered server to server. Leave this event route empty when the handoff credential should arrive on the callback URL above, carried by the buyer's browser.

Not both. Whichever you configure is the one Omnistrate uses.

This is a program endpoint. It verifies a signature and answers 2xx. Pointing us at your user-facing page here means signed webhooks arrive at a web page; pointing us at your webhook endpoint for the callback sends buyers somewhere they cannot use.

HTTPS only. Private, loopback, link-local and cloud metadata addresses are refused, both at registration and again at delivery time.

Lifecycle event receivers¶

The Event routing tab has a separate receiver URL for each of the seven event types. Routes can point to different services. An event with no receiver URL is not delivered, and there is no shared default route.

The redirect happens only during the initial purchase. Configure routes for every later event your product must process, including entitlement changes, suspension, reinstatement, pending cancellation, cancellation, and fulfillment failure.

Signing secret¶

What Omnistrate signs outbound deliveries to your event receivers with, so you can prove they came from us. At least 32 bytes, because deliveries are signed with HMAC-SHA256 and a key shorter than the hash weakens it.

Write-only: encrypted on arrival and returned by no read, so keep a copy.

Supplying a value is a rotation. Leave it blank when editing anything else on an already-connected channel and the stored secret is kept.

Buyer account domain¶

Enter the domain Omnistrate should use when creating the buyer's root user. Use a domain you control or an intentionally non-routable domain such as buyers.example.invalid.

Confirmation settings¶

• Time to confirm sets how long your integration has to provision the buyer and confirm fulfillment before Omnistrate flags the contract for attention.
• Handoff credential lifetime sets how long the buyer handoff credential can be redeemed. Leave it empty to use the displayed default.
• Confirm automatically skips your confirmation call. Enable it only when your product requires no provider-managed onboarding before the subscription becomes usable.
• Fulfill purchases on this channel enables production fulfillment. Turn it on only after the callback, event routes, listing mappings, and Sandbox tests are ready.

Map your listings¶

A purchase has to resolve to something you sell. Open Configure listings on the channel card and map each Suger product/listing returned by the catalog to one of your SaaS Products and a Plan within it.

Suger exposes products/listings to this integration; it does not expose a separate plan catalog. In Omnistrate, choose the SaaS Product first and then its Plan.

Two rules the mapping enforces:

• The Plan must list MARKETPLACE as a billing provider.
• Only production plans are offered. A marketplace buyer is a paying customer, and serving them from a dev or staging tier would take their money onto a test plan.

A channel cannot be enabled with no mapped listing, because a purchase on a channel that sells nothing resolves to no plan.

The listing mapping selects the Plan used for the pending subscription request and the subscription created after confirmation. Configure pricing and metering on that Plan before accepting purchases; see Billing and Usage Reporting.

Verify the connection¶

Use Test connection to verify the Suger organization and OAuth credentials before enabling the channel.

What Suger can and cannot do¶

Each channel declares what Omnistrate is allowed to control. Suger owns the registered landing page and the fulfillment callbacks, so the contract is already committed on the marketplace before Omnistrate is called:

This is why the buyer is paying before you confirm, and why fulfillmentState rather than contractStatus is the thing to branch on.