Capabilities & Flow Contracts

This article is the contract between your plugin and the platform — declare what your plugin can do, name your flows the way the platform expects, and FluxBilling wires everything together automatically. When you build a plugin, you don't tell the platform "call this flow when a service is provisioned." Instead, you do two things: you set capability flags that advertise what your plugin is able to do, and you give each flow a type and a slug (its short name) that match what the platform looks for. At runtime, when the platform needs to provision a service, take a payment, or sign a user in, it searches your plugin's flows for the expected names and runs the first match. Get the names right and your plugin works; this article lists the exact names for every plugin type.

If you haven't built a flow yet, start with Building Flows and Creating a Plugin. This article assumes you know what a flow, a flow type, and a slug are.

The two halves of the contract

Capabilities are flags you declare on your plugin that say what it supports — for example, that an infrastructure plugin can reboot a server, or that a payment gateway can issue refunds. The platform reads these flags to decide which buttons and options to show operators, so set them honestly. For Infrastructure Provider and Payment Gateway plugins you set capability flags from a checklist in the builder; for the other types, capabilities are a small set of values you provide directly.

Flow names are how the platform finds the right flow to run. Two things identify a flow:

• Its flow type — chosen when you create the flow (for example Provision, Custom Action, Data Fetch, Webhook Handler). The lifecycle types map directly to platform operations.
• Its slug — a short, lowercase, hyphenated name like create-payment or get-user-profile. For most operations the platform matches a flow by its operation, then its slug, then its name, trying a short list of accepted names and using the first one it finds.

A useful consequence: for several plugin types, a capability is inferred from whether the matching flow exists. If you add a refund-payment flow to a payment gateway, refunds light up automatically — you don't have to flip a separate flag. The per-type tables below note where this happens.

Tip: the flow builder hints these slug names as you create flows. The tables here are the authoritative list, but you'll see the same names suggested in the UI.

Infrastructure Provider

Infrastructure Provider plugins provision and manage customer services (VPS, game servers, hosting accounts, and so on) on an external control panel.

Capability flags

Declare these from the capabilities checklist. They control which lifecycle actions and management buttons the platform offers for services backed by your plugin.

Flag	Advertises that your plugin can…
canProvision	Create a new service
canSuspend	Suspend an active service
canUnsuspend	Restore a suspended service
canTerminate	Permanently remove a service
canReboot	Reboot the underlying server
canStart	Power a service on
canStop	Power a service off
canConsole	Provide console / remote-access details
canGetStats	Return usage statistics (CPU, bandwidth, etc.)
canGetStatus	Report the current power/state of a service
canReinstall	Reinstall the operating system or image
canBackup	Trigger a backup
canRestore	Restore from a backup
canSnapshot	Create and manage snapshots
canResize	Change a service's plan or resources

Lifecycle flows (by flow type)

The four service-lifecycle operations are matched by flow type. Create one flow of each type and name its slug to match the operation:

Operation	Flow type	Flow slug	Notes
Provision a service	Provision	provision	Receives order details (hostname, plan, location, OS, credentials, product options) as input
Suspend a service	Suspend	suspend	Receives the service's stored data
Unsuspend a service	Unsuspend	unsuspend
Terminate a service	Terminate	terminate

Service actions (Custom Action flows)

Everything else a customer or operator can do to a running service goes in a Custom Action flow, named for the operation. The platform routes a requested action to the action flow whose slug matches the action name:

Operation	Flow type	Flow slug	Notes
Start	Custom Action	start
Stop	Custom Action	stop
Restart / reboot	Custom Action	reboot
Reinstall	Custom Action	reinstall	Receives the chosen OS template
Resize / change plan	Custom Action	resize	Receives the new specs
Console access	Custom Action	console	Return the console URL or connection details
Create snapshot	Custom Action	snapshot-create
Restore snapshot	Custom Action	snapshot-restore	Receives the snapshot ID
Delete snapshot	Custom Action	snapshot-delete	Receives the snapshot ID

Name an action flow's slug exactly after the action it performs. Use hyphenated names for compound operations (for example snapshot-create), and keep them lowercase.

Lookups (Data Fetch flows)

Read-only lookups — current status, usage stats, the list of available OS templates, and listing snapshots — go in Data Fetch flows:

Operation	Flow type	Flow slug	Notes
Get status	Data Fetch	get-status	Return the service's power/state; the platform reads a status (or powerStatus) value from your output
Get stats	Data Fetch	get-stats	Return usage metrics
List OS templates	Data Fetch	os-templates	Return the installable images for the reinstall picker (os-images is also accepted)
List snapshots	Data Fetch	snapshot-list	Return the existing snapshots

The status lookup is the one exception to slug matching — the platform finds your status Data Fetch flow by its name containing the word "status", so give it a name like "Get Status".

If a status or stats flow is absent, the platform simply reports that the operation isn't supported — so only add the flows for operations your external API can actually perform, and keep your capability flags in sync.

Worked example: a reboot action

To add a reboot button to services backed by your plugin:

1. Set canReboot (and canStart / canStop as appropriate) in the capabilities checklist.
2. Create a Custom Action flow with the slug reboot.
3. Inside the flow: Start → HTTP Request (call your provider's reboot endpoint, using {{config.api_key}} and the service identifier from the flow input) → Condition (check the response) → End.

The platform now shows a Reboot control on the service and runs this flow when an operator clicks it.

Payment Gateway

Payment Gateway plugins take payments, handle refunds, optionally save payment methods, and receive webhooks from a payment processor.

Capability flags and limits

Flag	Meaning
supportsRefund	Full refunds are available
supportsPartialRefund	Partial-amount refunds are available
supportsRecurring	The gateway can charge on a recurring schedule
supportsSavedPaymentMethods	Customers can store a payment method for later charges
supportsMultipleCurrencies	More than one currency is accepted
webhookRequired	The gateway relies on incoming webhooks to confirm payments

You can also set minimumAmount and maximumAmount to bound the charge amounts the platform will send to your gateway.

Several of these flags are inferred from your flows. If you add a refund-payment flow, refunds are treated as supported; if you add a handle-webhook flow, webhooks are treated as required. You can still set the flags explicitly to control how options appear, but you don't have to repeat yourself — adding the flow is enough to enable the behavior.

Flows the platform calls

Operation	Flow slug(s) — first match wins	Notes
Create a payment	create-checkout-session, create-payment, or payment	The entry point for taking a payment. Return a redirect URL (for hosted checkout) or the data the platform needs to complete the charge. Required.
Capture an authorized payment	capture-payment	For two-step (authorize-then-capture) flows. Omit if you charge immediately.
Refund a payment	refund-payment	Receives the transaction and (for partial refunds) an amount. Presence of this flow ⇒ refunds supported.
Get payment status	get-payment-status	Look up the current state of a transaction.
Poll payment status	poll-payment-status	Used when the platform actively re-checks a pending payment (get-payment-status is also accepted as a fallback).
Start saving a payment method	setup-save-method	Begin the save-card / mandate setup.
Finish saving a payment method	complete-save-method	Complete the setup started above.
Charge a saved method	charge-saved-method	Charge a previously stored payment method.
Remove a saved method	remove-saved-method	Detach a stored method. Optional — if you don't provide it, removal just succeeds locally.
Handle a webhook	handle-webhook	Verify and interpret incoming webhook events from the processor. Presence of this flow ⇒ webhooks required. Return the event type, transaction reference, and resulting status.

The save-method flows are only needed if you set (or imply) supportsSavedPaymentMethods. A gateway that only does one-off hosted checkout needs just a payment-creation flow and, usually, a handle-webhook flow.

Worked example: a minimal redirect gateway

1. Create a connection to your processor's API (see Connections and Authentication).
2. Create a flow with the slug create-payment: Start → HTTP Request (create a checkout session at the processor) → Transform (pull out the redirect URL) → End (return the redirect URL). The platform sends the customer there to pay.
3. Create a flow with the slug handle-webhook: Start → HTTP Request / verification → Switch (branch on the event type) → End (return the normalized event type, transaction reference, and status). Marking webhookRequired is automatic once this flow exists.
4. Optionally add refund-payment to enable refunds.

Authentication

Authentication plugins let customers sign in through an external identity provider using a standard authorization-code exchange.

Operation	Flow slug	Notes
Build the sign-in URL	get-auth-url	Receives the state value, redirect URI, and requested scopes; returns the provider authorization URL to send the user to.
Exchange the code for a token	exchange-token	Receives the authorization code and redirect URI; returns the access token.
Fetch the user's profile	get-user-profile	Receives the access token; returns the user's identity details (email, name, external ID).

Provide all three flows for a complete sign-in. The look of the sign-in button (its label and colors) comes from values you set on the plugin.

AI Provider

AI Provider plugins connect an external AI service for text, embeddings, or images.

Operation	Flow slug	Notes
Generate a completion	generate-completion	The core text-generation call. Return the generated text plus token counts and the model used.
Stream a completion	stream-completion	For incremental/streamed output. Optional — if absent, the platform falls back to your completion flow and returns the result in one piece.
Generate an image	generate-image	Return an image URL or data.
Create embeddings	embed	Return the embedding vector.
Count tokens	count-tokens	Return a token count for the given text.
List models	list-models	Return the available model names. Optional — if absent, the platform uses the model list you declare on the plugin.

A working AI plugin needs at least a generate-completion flow; the others are added as your provider supports them.

Notification, Automation, and Custom

Notification plugins send event-driven messages to an outside channel. Rather than the fixed lifecycle names above, a notification plugin subscribes to platform events and runs a flow when each one fires. This has its own article — see Notification Plugins.

Automation and Custom plugins are free-form. They don't have a fixed set of expected flow names; you define flows and decide how they run — triggered manually, on a schedule, or in response to platform events. Use these when your integration doesn't fit one of the typed roles above and you want full control over what runs and when.

Naming checklist

• Slugs are lowercase and hyphenated (get-payment-status, not getPaymentStatus).
• Use the flow type only for the four infrastructure lifecycle operations; use the slug to match every other operation, including the payment webhook (handle-webhook).
• When more than one slug is accepted for an operation, you only need one of them — pick the clearest.
• Only create the flows your external service can actually perform, and keep your capability flags consistent with the flows you've built.

---

Related: Building Flows · Node Reference · Variables and Expressions · Connections and Authentication · Configuration Settings · Notification Plugins