Endpoint

Propose a split rule

POST/v1/split_rules

Creates a rule in awaiting_approval. It creates no payout legs until a key-holding member confirms it with a passkey in the dashboard. Nothing is ever sent by a rule: each paid order it applies to creates payouts of kind split_leg in awaiting_approval.

Scope a restricted key needs: payouts:write
Publishable key: Not allowed: secret or restricted key only
Idempotency-Key: Recommended, as for every POST.

Parameters

Parameters of Propose a split rule
Parameter	Type and place	Meaning
`Orrerie-Version`	stringheader	API version date. Default: the version the key was created with. Example `2026-10-11`.

Request body

A JSON object. The body is required. A field the call does not list is refused with parameter_unknown.

Request body of Propose a split rule
Field	Type	Meaning
`name`	string	Your name for the rule.
`scope`	object	Which paid orders the rule applies to: `{kind: product, product}`, `{kind: payment_link, payment_link}` or `{kind: merchant}`.
`shares`	array of objects	1 to 20 shares, each a saved address and its percent.
`shares[].saved_address`	string	The `dst_` id of an active saved address of kind `third_party`.
`shares[].percent`	string	Its share of each order, with two decimals, above zero; all shares together at most `100.00`.
`remind_daily`	boolean	`true` to remind the Owners and Finance members each day of legs waiting for approval.

Example request

curl

curl https://api.orrerie.com/v1/split_rules \
  -H "Authorization: Bearer $ORRERIE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Roaster share",
  "scope": {
    "kind": "product",
    "product": "prod_8m2k5q9x1w4e7r0t3y6u2i5o",
    "payment_link": null
  },
  "shares": [
    {
      "saved_address": "dst_3f7k0n2p5s8v1x4z7b0d3g6j",
      "percent": "30.00"
    },
    {
      "saved_address": "dst_9c2e5h8k1n4q7t0w3z6b9d2g",
      "percent": "10.00"
    }
  ],
  "remind_daily": false
}'

JavaScript

const response = await fetch("https://api.orrerie.com/v1/split_rules", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORRERIE_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Roaster share",
    "scope": {
      "kind": "product",
      "product": "prod_8m2k5q9x1w4e7r0t3y6u2i5o",
      "payment_link": null
    },
    "shares": [
      {
        "saved_address": "dst_3f7k0n2p5s8v1x4z7b0d3g6j",
        "percent": "30.00"
      },
      {
        "saved_address": "dst_9c2e5h8k1n4q7t0w3z6b9d2g",
        "percent": "10.00"
      }
    ],
    "remind_daily": false
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result);

Python

import os
import requests

response = requests.post(
    "https://api.orrerie.com/v1/split_rules",
    headers={"Authorization": f"Bearer {os.environ['ORRERIE_SECRET_KEY']}"},
    json={
        "name": "Roaster share",
        "scope": {
            "kind": "product",
            "product": "prod_8m2k5q9x1w4e7r0t3y6u2i5o",
            "payment_link": None,
        },
        "shares": [
            {
                "saved_address": "dst_3f7k0n2p5s8v1x4z7b0d3g6j",
                "percent": "30.00",
            },
            {
                "saved_address": "dst_9c2e5h8k1n4q7t0w3z6b9d2g",
                "percent": "10.00",
            },
        ],
        "remind_daily": False,
    },
    timeout=30,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result)

PHP

<?php
$request = curl_init('https://api.orrerie.com/v1/split_rules');
curl_setopt_array($request, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('ORRERIE_SECRET_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'name' => 'Roaster share',
        'scope' => [
            'kind' => 'product',
            'product' => 'prod_8m2k5q9x1w4e7r0t3y6u2i5o',
            'payment_link' => null,
        ],
        'shares' => [
            [
                'saved_address' => 'dst_3f7k0n2p5s8v1x4z7b0d3g6j',
                'percent' => '30.00',
            ],
            [
                'saved_address' => 'dst_9c2e5h8k1n4q7t0w3z6b9d2g',
                'percent' => '10.00',
            ],
        ],
        'remind_daily' => false,
    ]),
]);
$body = curl_exec($request);
if ($body === false) {
    throw new RuntimeException(curl_error($request));
}
$result = json_decode($body, true);
if (curl_getinfo($request, CURLINFO_HTTP_CODE) >= 400) {
    throw new RuntimeException($result['error']['code'] . ': ' . $result['error']['message']);
}
print_r($result);

Responses

`201` Created

The answer is the split_rule object. Headers: Orrerie-Request-Id.

Example response, 201

{
  "id": "srl_4n7q0t2w5z8c1f3h6k9m2p4r",
  "object": "split_rule",
  "livemode": true,
  "created": "2026-10-11T14:20:00.000Z",
  "name": "Roaster share",
  "status": "awaiting_approval",
  "scope": {
    "kind": "product",
    "product": "prod_8m2k5q9x1w4e7r0t3y6u2i5o",
    "payment_link": null
  },
  "shares": [
    {
      "saved_address": "dst_3f7k0n2p5s8v1x4z7b0d3g6j",
      "percent": "30.00"
    },
    {
      "saved_address": "dst_9c2e5h8k1n4q7t0w3z6b9d2g",
      "percent": "10.00"
    }
  ],
  "kept_percent": "60.00",
  "remind_daily": false,
  "pending": {
    "legs": 0,
    "totals": []
  }
}

Any other status: an error

A status of 400 or above answers with the error object. Branch on its code, never on its message.

Errors

This call has no error of its own. It answers with the errors every call can answer with: a bad key, a missing scope, an object that does not exist, the rate limit. Every error code has its own entry.