> For the complete documentation index, see [llms.txt](https://docs.limio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limio.com/integrations/order-orchestration/order-orchestration-framework.md).

# Order Orchestration Framework

## Introduction

The **Order Orchestration Framework** in Limio manages the end-to-end processing of orders and subscription changes. Orders are sent from various sources, including Limio Shop, Limio Self-Service, Limio for Salesforce, or [via API](https://docs.limio.com/api/orders-api/orders). The framework operates as a sequential orchestration mechanism, moving from one plugin to the next in a defined sequence.

While some customers require a simple orchestration — for example, updating Salesforce then Zuora — others need more extensibility, such as managing fulfilment, entitlements, or integrating with external provisioning systems.

The Order Orchestration Framework ensures:

* **Orchestration:** Orders move sequentially through processing steps, with all critical steps needing to pass for the order to complete successfully.
* **Fault Tolerance:** If any critical step fails, the order terminates with a failure message. Error messages are surfaced to end-users, while providing Limio admin users visibility on what step failed.
* **Customisation:** The framework supports webhooks, synchronous callouts, and configurable plugin sequences per order type.
* **Extensibility:** Custom logic or new partners can be added using plugins.
* **Decomposition:** Limio can send parts of the order to specific systems based on conditions.

## How Plugin Sequencing Works

Plugins run **sequentially** in the order defined in your configuration. Each plugin processes the order and passes the result to the next plugin in the sequence.

### Typical Default Sequence

A common configuration for a Zuora + Salesforce setup looks like this:

```
1. Salesforce V3      → Creates/updates Salesforce Account and Contact
2. Zuora              → Creates subscription, processes payment
3. Platform Events    → Fires Salesforce Platform Event for downstream flows
```

Limio also fires [async webhooks](/integrations/order-orchestration/webhooks-and-notifications.md) (e.g., Order Submitted) separately from the plugin pipeline. Note that these fire when the order is created, regardless of whether all plugins succeed — see [Webhooks and Notifications](/integrations/order-orchestration/webhooks-and-notifications.md) for details.

This sequence is fully configurable. You might place a Callout Plugin before Zuora to provision a user in an external system first, or add a Duplicate Subscription Check after Salesforce V3 to prevent duplicate purchases.

### Example: Orchestration with External Provisioning

```
1. Callout Plugin     → Provisions user in external system, returns account ID
2. Salesforce V3      → Creates Salesforce Account
3. Zuora              → Creates subscription using the account ID from step 1
4. Entitlements       → Activates user entitlements (post-processing phase)
```

### Processing and Post-Processing

The framework has two phases:

1. **Process Order** — The main phase. Plugins run sequentially. Critical failures halt the pipeline.
2. **Post-Process Order** — Runs after the main phase completes. Used for side-effects like entitlement propagation or custom webhooks that need access to enriched data (e.g., CRM IDs created during processing).

## Critical vs Non-Critical Plugins

Each plugin is configured as either **critical** or **non-critical**:

| Type             | Behaviour on Failure                                          | Use When                                                                                                           |
| ---------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Critical**     | Order fails immediately. Error is surfaced to the end-user.   | The step is essential for the order to be valid (e.g., billing, payment, user provisioning).                       |
| **Non-Critical** | Failure is logged but the order continues to the next plugin. | The step is supplementary and can be retried or handled separately (e.g., entitlement callout, analytics webhook). |

**Examples:**

* **Critical:** Zuora plugin (billing must succeed), Callout Plugin for user provisioning (account must exist before billing)
* **Non-Critical:** Entitlements plugin (can be retried), a data warehouse callout (informational only)

If all critical plugins succeed, the order reaches a completion state (e.g., "order complete" or "change complete").

## Configuring Plugin Sequences

### Plugin Configuration Format

Each plugin in the sequence is defined as a JSON object:

```json
{
  "name": "calloutPlugin",
  "critical": true,
  "options": {
    "endpoint": "https://example.com/provision",
    "timeoutValue": 5000,
    "shouldRejectOn": {
      "status": [400, 404, 500]
    }
  }
}
```

| Field      | Description                                                            |
| ---------- | ---------------------------------------------------------------------- |
| `name`     | The plugin identifier (e.g., `zuora`, `salesforceV3`, `calloutPlugin`) |
| `critical` | Whether the plugin must succeed for the order to complete              |
| `options`  | Plugin-specific configuration (varies per plugin)                      |

### Overrides by Order Type

The framework allows configuring different plugin sequences based on the **order type**. This means you can have a different set of plugins for new orders vs. cancellations vs. renewals.

Supported order types include:

| Order Type                | Description                            |
| ------------------------- | -------------------------------------- |
| `new` / `submitted`       | New subscription order                 |
| `cancel_subscription`     | Subscription cancellation              |
| `change_offer`            | Switching to a different offer         |
| `add_offer`               | Adding an additional offer             |
| `change_payment`          | Updating payment method                |
| `change_address`          | Updating delivery/billing address      |
| `update_customer_details` | Updating customer information          |
| `update_subscription`     | Modifying subscription (e.g., add-ons) |
| `renew`                   | Subscription renewal                   |
| `refund`                  | Processing a refund                    |
| `credit`                  | Applying a credit                      |
| `external`                | Externally-initiated order             |
| `activation`              | Activating a pending subscription      |

**Example:** Skip the Zuora plugin for `refund` orders, by defining an override for the `refund` order type that excludes the Zuora plugin.

### Overrides by Processing Type

Different checkout experiences can have different plugin sequences. For example, **Express Apple Pay** checkouts might use a simplified sequence compared to standard checkouts.

{% hint style="info" %}
**Order type and processing type are the only two things an override can match on.** You cannot vary the plugin sequence by offer type (for example, `trial` or `gift`), as the offer type is never consulted when resolving the sequence. To give a promotional or gift offer a different processing path, model it as a distinct order type or processing type, or handle the difference inside a plugin.
{% endhint %}

## Failures and Visibility

All plugin failures are recorded in **Process Events**, with full logs available for troubleshooting. This allows operational teams to understand failure points and remedy them.

Learn more in [Troubleshooting Order Processing](/integrations/order-orchestration/troubleshooting-order-processing.md).

## How to View Your Configuration

1. Navigate to **Settings > Order Processing Config** in Limio
2. You will see the order processing configuration for your tenant, including the plugin sequence and any overrides.

## How to Change Your Configuration

Order processing configuration is currently managed by Limio as part of setting up integrations (e.g., Zuora, Salesforce). If you need to:

* **Add or remove a plugin** — contact <support@limio.com>
* **Change the sequence** — contact <support@limio.com>
* **Add an override for a specific order type** — contact <support@limio.com>
* **Request a new plugin** — Limio is constantly adding new partners to support hybrid billing, fulfilment, and entitlement strategies. Contact <support@limio.com>

## Available Plugins

See the full list of available plugins in [Available Plugins](/integrations/order-orchestration/available-plugins.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.limio.com/integrations/order-orchestration/order-orchestration-framework.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.