# 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](https://docs.limio.com/integrations/order-orchestration/webhooks-and-notifications) (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](https://docs.limio.com/integrations/order-orchestration/webhooks-and-notifications) 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](https://docs.limio.com/integrations/order-orchestration/troubleshooting-order-processing).

## 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](https://docs.limio.com/integrations/order-orchestration/available-plugins).