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.

Tiered allocation contract

A tiered allocation contains one payee, contiguous tier bands, and an optional tier_policy. Omitting tier_policy preserves the original per-revenue-record marginal calculation. Grouped policies are an additive opt-in capability.

  • attainment_window accepts revenue_record, calculation_run, quarter, or year.
  • application_method accepts marginal; current_period_rate for calculation-run/quarter/year windows; or retroactive_true_up for quarter/year windows.
  • current_period_rate and retroactive_true_up require threshold_trigger: at_threshold or above_threshold.
  • Quarter/year policies require cycle_start_month, an IANA timezone, and refund_treatment.
  • Omit tier_program_id for a new grouped allocation. The server creates it and returns/preserves that stable rule/payee identity across compatible updates.

Grouped-tier safety constraints

Grouped tier commissions are available across account and API workflows, while monthly quarter/year runs remain protected by locked predecessor state.

  • Create, import, upsert, and policy-changing update requests accept grouped tiers; omitting tier_policy preserves legacy per-record marginal behavior.
  • An open effective attainment window prevents policy or rate changes that would make locked history ambiguous.
  • reverse_original_commission_only is accepted for grouped refunds and reverses the canonical locked original commission without changing attainment.
  • restate_original_attainment_window is accepted for quarter/year policies. Authorized account users reconcile a linked negative refund through chronological, delta-only replacement runs that must be reviewed and locked in order.

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.
allocations[].tiers array Tiered rules: contiguous min/max/percentage bands starting at zero; only the final max can be null.
allocations[].tier_policy object or omitted Tiered rules: attainment window and application semantics. Omitted means revenue_record + marginal.
tier_policy.threshold_trigger string when required at_threshold uses the higher tier at equality; above_threshold waits until attainment is greater than the tier minimum.
tier_policy.cycle_start_month / timezone integer / IANA string Required for quarter/year window boundaries.
tier_policy.refund_treatment string Required for quarter/year. Use reverse_original_commission_only to preserve attainment or restate_original_attainment_window for controlled chronological reconciliation.
allocations[].tier_program_id server-owned string Stable grouped rule/payee identity. Omit it when creating a new grouped allocation.
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