> This page is for Gateway.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Routing policies

> Create per-customer routing policies with a ranked priority list or an intelligent strategy, and choose which one is the customer's default.

A customer routing policy picks the model when the customer's request doesn't pin one. `PRIORITY` is a ranked list that falls back to the next model on failure; `INTELLIGENT` lets Gateway choose per request from an allowed set, optimizing for `COST`, `PERFORMANCE`, or `CAPABILITY`.

## Create a policy

`POST /v1/customers/{customer_id}/routing-policies`. The customer's first policy becomes its default.

**`Priority`**

```bash title="Priority"
curl -X POST https://api-gateway.merge.dev/v1/customers/{customer_id}/routing-policies \
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "workflow-a",
    "strategy": "PRIORITY",
    "priority_order": [
      { "model": "openai/gpt-5.5", "priority": 1 },
      { "model": "anthropic/claude-opus-4-8", "priority": 2 }
    ]
  }'
```

**`Intelligent`**

```bash title="Intelligent"
curl -X POST https://api-gateway.merge.dev/v1/customers/{customer_id}/routing-policies \
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "smart-router",
    "strategy": "INTELLIGENT",
    "axis": "CAPABILITY",
    "allowed_models": ["openai/gpt-5.5", "anthropic/claude-opus-4-8"]
  }'
```

Naming a model the customer's controls and key usage mode don't allow returns `400`, so check [the customer's allowed models](/merge-gateway/embedded-routing-stack/overview#listing-a-customers-allowed-models) first.

## Change the default

Send `is_default: true` on create or `PATCH`, or call `PUT /v1/customers/{customer_id}/default-routing-policy` with `{"routing_policy_id": "..."}`. Deleting the default leaves the customer with none, so its requests fall back to your organization's default policy.

`GET`, `PATCH`, and `DELETE` on `/v1/customers/{customer_id}/routing-policies/{policy_id}` manage a single policy.

## Reference

| Field                       | Type                        | Description                                                                                         |
| --------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------- |
| `id`                        | UUID                        | Pass as `routing_policy_id` to select this policy on a request                                      |
| `name`, `description`       | string                      | Label and optional description                                                                      |
| `strategy`                  | enum                        | `PRIORITY` or `INTELLIGENT`. Custom strategies and tag rules aren't supported on customer policies. |
| `is_default`                | boolean                     | Used when a request names no policy                                                                 |
| `priority_order`            | list of `{model, priority}` | `PRIORITY` only. Models are tried in order.                                                         |
| `allowed_models`            | list                        | Required for `INTELLIGENT`. The set Gateway chooses from.                                           |
| `allowed_providers`         | list                        | `INTELLIGENT` only. Derived from `allowed_models`. If you send it, it must match their providers.   |
| `axis`                      | enum                        | `INTELLIGENT` only: `COST` (default), `PERFORMANCE`, or `CAPABILITY`                                |
| `created_at`, `modified_at` | datetime                    | Timestamps                                                                                          |

Fields for the other strategy come back `null`; sending them, or duplicate models in a list, returns `422`.

## Next steps

#### [Using routing policies](/merge-gateway/routing/using-policies)

How policies resolve and how requests override them

#### [Customer keys](/merge-gateway/embedded-routing-stack/customer-keys)

Control which credentials serve the policy's models