Allocora
Docs / Rule API Endpoints

API Reference

Rule API endpoints

Use rule endpoints to automate payout allocation configuration and review saved rule history.

Start Free Try Sample Data

Details

What to know

Rule object

A rule controls which revenue records match and how allocation percentages or tiers are applied.

  • Use external_id to connect Allocora rules to your source system.
  • Use priority to control which matching rules win when several could apply.
  • Use allocation_type flat for percentage splits and tiered for tier-based logic.
  • Use the versions endpoint when you need to review saved rule history.

Endpoint Examples

Requests and responses

Each example shows the request shape and a shortened successful response. Replace placeholder IDs with values from your workspace.

GET /api/v1/rules

List rules

Returns rules available to the API key workspace.

  • Requires read:rules.

Request example

curl -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  https://www.allocora.com/api/v1/rules

Response example

{
  "data": [
    {
      "id": "<RULE_ID>",
      "external_id": "rule_partner_20_percent",
      "name": "Partner 20 percent",
      "status": "active",
      "allocation_type": "flat",
      "allocation_total": 20
    }
  ]
}
GET /api/v1/rules/{id}

Retrieve a rule

Returns one rule by ID.

  • Requires read:rules.

Request example

curl -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  https://www.allocora.com/api/v1/rules/<RULE_ID>

Response example

{
  "data": {
    "id": "<RULE_ID>",
    "external_id": "rule_partner_20_percent",
    "name": "Partner 20 percent",
    "status": "active",
    "priority": 100,
    "allocation_type": "flat",
    "allocations": [
      {"payee_id": "<PAYEE_ID>", "percentage": 20}
    ]
  }
}
POST /api/v1/rules

Create a rule

Creates one allocation rule.

  • Requires write:rules.
  • At least one allocation is required.

Request example

curl -X POST https://www.allocora.com/api/v1/rules \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "rule_partner_20_percent",
    "name": "Partner 20 percent",
    "status": "active",
    "priority": 100,
    "allocation_type": "flat",
    "allocations": [
      {"payee_id": "<PAYEE_ID>", "percentage": 20}
    ]
  }'

Response example

{
  "data": {
    "id": "<RULE_ID>",
    "external_id": "rule_partner_20_percent",
    "name": "Partner 20 percent",
    "status": "active",
    "allocation_type": "flat",
    "allocation_total": 20
  }
}
POST /api/v1/rules/upsert

Upsert a rule

Creates or updates one rule by external_id.

  • Requires write:rules.
  • operation must be create_only, update_only, or create_or_update.

Request example

curl -X POST https://www.allocora.com/api/v1/rules/upsert \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "rule_partner_20_percent",
    "operation": "create_or_update",
    "name": "Partner 20 percent",
    "status": "active",
    "allocations": [
      {"payee_id": "<PAYEE_ID>", "percentage": 20}
    ]
  }'

Response example

{
  "data": {
    "id": "<RULE_ID>",
    "external_id": "rule_partner_20_percent",
    "name": "Partner 20 percent",
    "status": "active",
    "allocation_total": 20
  }
}
POST /api/v1/rules/batch

Create rules in batch

Creates up to 100 rules in one request.

  • Requires write:rules.
  • Each record uses the same fields as create rule.

Request example

curl -X POST https://www.allocora.com/api/v1/rules/batch \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "external_id": "rule_partner_20_percent",
        "name": "Partner 20 percent",
        "allocations": [
          {"payee_id": "<PAYEE_ID>", "percentage": 20}
        ]
      }
    ]
  }'

Response example

{
  "data": [
    {
      "index": 0,
      "success": true,
      "status": 201,
      "response": {
        "data": {"id": "<RULE_ID>", "external_id": "rule_partner_20_percent"}
      }
    }
  ],
  "meta": {"processed": 1, "succeeded": 1, "failed": 0, "limit": 100}
}
POST /api/v1/rules/batch/upsert

Upsert rules in batch

Creates or updates up to 100 rules by external_id.

  • Requires write:rules.
  • Each record must include external_id and operation.

Request example

curl -X POST https://www.allocora.com/api/v1/rules/batch/upsert \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "external_id": "rule_partner_20_percent",
        "operation": "create_or_update",
        "name": "Partner 20 percent",
        "allocations": [
          {"payee_id": "<PAYEE_ID>", "percentage": 20}
        ]
      }
    ]
  }'

Response example

{
  "data": [
    {
      "index": 0,
      "success": true,
      "status": 200,
      "response": {
        "data": {"id": "<RULE_ID>", "external_id": "rule_partner_20_percent"}
      }
    }
  ],
  "meta": {"processed": 1, "succeeded": 1, "failed": 0, "limit": 100}
}
PUT /api/v1/rules/{id}

Update a rule

Updates one rule by ID.

  • Requires write:rules.
  • Send only the fields you want to change.

Request example

curl -X PUT https://www.allocora.com/api/v1/rules/<RULE_ID> \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "priority": 50,
    "status": "active"
  }'

Response example

{
  "data": {
    "id": "<RULE_ID>",
    "external_id": "rule_partner_20_percent",
    "name": "Partner 20 percent",
    "status": "active",
    "priority": 50
  }
}
PUT /api/v1/rules/batch

Update rules in batch

Updates up to 100 rules by ID.

  • Requires write:rules.
  • Each record must include id.

Request example

curl -X PUT https://www.allocora.com/api/v1/rules/batch \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {"id": "<RULE_ID>", "priority": 50}
    ]
  }'

Response example

{
  "data": [
    {
      "index": 0,
      "success": true,
      "status": 200,
      "response": {
        "data": {"id": "<RULE_ID>", "priority": 50}
      }
    }
  ],
  "meta": {"processed": 1, "succeeded": 1, "failed": 0, "limit": 100}
}
POST /api/v1/rules/{id}/toggle-status

Toggle rule status

Activates or deactivates one rule.

  • Requires write:rules.
  • No request body is required.

Request example

curl -X POST https://www.allocora.com/api/v1/rules/<RULE_ID>/toggle-status \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>"

Response example

{
  "data": {
    "id": "<RULE_ID>",
    "external_id": "rule_partner_20_percent",
    "name": "Partner 20 percent",
    "status": "inactive"
  }
}
GET /api/v1/rules/{id}/versions

List rule versions

Returns saved history for one rule.

  • Requires read:rules.

Request example

curl -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  https://www.allocora.com/api/v1/rules/<RULE_ID>/versions

Response example

{
  "data": {
    "rule_id": "<RULE_ID>",
    "active_version": 2,
    "versions": [
      {"version": 1, "status": "active", "is_active": false},
      {"version": 2, "status": "inactive", "is_active": true}
    ]
  }
}

Reference Tables

Fields and checks

Common rule fields

These fields appear in rule create, update, and response examples.

Field Type Notes
id string Allocora rule ID returned by the API.
external_id string or null Your stable rule identifier.
name string Display name for the rule.
status string active or inactive.
priority integer Higher-priority matching control.
allocation_type string flat or tiered.
allocations array Payee allocation definitions.
valid_from / valid_to date or null Optional effective window.

Feedback

Was this page helpful?

Send a note if a step is unclear, missing, or out of date.

Email Support

Apply this in a workspace

Start free, use sample data, then replace examples with your own revenue rows when the workflow is clear.

Start Free Browse Docs