# 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",
  "service": "limio",
  "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`) |
| `service`  | The service category (e.g., `zuora`, `salesforce`, `limio`)            |
| `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:** Pass free trial orders to Salesforce but not Zuora — by defining an override for the `trial` offer 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.

### Overrides by Offer Type

You can also override the sequence based on the offer type (e.g., `trial`, `gift`, `standard`). This allows different processing paths for promotional offers or gift subscriptions.

## 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.