Allocora
Docs / Revenue API Endpoints

API Reference

Revenue API endpoints

Use revenue endpoints to post transaction records from trusted systems and retrieve rows for reconciliation.

Start Free Try Sample Data

Details

What to know

Revenue object

A revenue record represents one sale, refund, or adjustment that can be used in payout calculations.

  • Use external_id to make revenue submissions idempotent for a source.
  • Use positive amounts for sales and negative amounts for refunds.
  • Use adjustment records to correct non-refund differences.
  • A linked refund can include original_revenue_id. The original must be a sale in the same workspace and currency, and all linked refunds together cannot exceed the original sale amount.
  • Revenue records cannot be edited through the API after creation.

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/revenues

List revenues

Returns paginated revenue records with optional filters.

  • Requires read:revenues.
  • Supports type, revenue_source_id, currency, date_from, date_to, search, per_page, and page.

Request example

curl -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  "https://www.allocora.com/api/v1/revenues?type=sale&currency=USD&per_page=25&page=1"

Response example

{
  "data": [
    {
      "id": "<REVENUE_ID>",
      "external_id": "invoice_123",
      "type": "sale",
      "amount": "249.000",
      "currency": "USD",
      "occurred_at": "2026-05-31T10:00:00+00:00"
    }
  ],
  "meta": {"current_page": 1, "last_page": 1, "per_page": 25, "total": 1}
}
GET /api/v1/revenues/{id}

Retrieve revenue

Returns one revenue record by ID.

  • Requires read:revenues.

Request example

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

Response example

{
  "data": {
    "id": "<REVENUE_ID>",
    "external_id": "invoice_123",
    "external_product_identifier": "sku_annual_pro",
    "type": "sale",
    "amount": "249.000",
    "currency": "USD",
    "revenue_source_id": "<REVENUE_SOURCE_ID>"
  }
}
POST /api/v1/revenues

Create revenue

Creates one sale, refund, or adjustment record.

  • Requires write:revenues.
  • Duplicate external_id values for the same revenue source return the existing record with skipped_duplicate.
  • Linked refunds are validated atomically against their original sale; over-refunds, cross-currency links, and refund-of-refund links return 422.

Request example

curl -X POST https://www.allocora.com/api/v1/revenues \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "revenue_source_id": "<REVENUE_SOURCE_ID>",
    "type": "sale",
    "amount": "249.000",
    "currency": "USD",
    "occurred_at": "2026-05-31T10:00:00Z",
    "external_id": "invoice_123",
    "external_product_identifier": "sku_annual_pro"
  }'

Response example

{
  "data": {
    "id": "<REVENUE_ID>",
    "external_id": "invoice_123",
    "type": "sale",
    "amount": "249.000",
    "currency": "USD",
    "revenue_source_id": "<REVENUE_SOURCE_ID>"
  },
  "outcome": "created"
}
POST /api/v1/revenues/batch

Create revenues in batch

Creates up to 100 sale, refund, or adjustment records in one request.

  • Requires write:revenues.
  • Each record uses the same fields as create revenue.

Request example

curl -X POST https://www.allocora.com/api/v1/revenues/batch \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "revenue_source_id": "<REVENUE_SOURCE_ID>",
        "type": "sale",
        "amount": "249.000",
        "currency": "USD",
        "occurred_at": "2026-05-31T10:00:00Z",
        "external_id": "invoice_123"
      }
    ]
  }'

Response example

{
  "data": [
    {
      "index": 0,
      "success": true,
      "status": 201,
      "response": {
        "data": {"id": "<REVENUE_ID>", "external_id": "invoice_123"},
        "outcome": "created"
      }
    }
  ],
  "meta": {"processed": 1, "succeeded": 1, "failed": 0, "limit": 100}
}

Reference Tables

Fields and checks

Common revenue fields

These fields appear in revenue create and response examples.

Field Type Notes
id string Allocora revenue ID returned by the API.
revenue_source_id string Revenue source that owns the record.
type string sale, refund, or adjustment.
amount decimal string Canonical amount, returned as a string.
currency string Three-letter currency code.
occurred_at datetime When the source transaction happened.
external_id string Source transaction ID used for duplicate protection.
external_product_identifier string or null Source product identifier for matching and mapping.
original_revenue_id string or null For a linked refund, the original sale in the same workspace and currency. Cumulative linked refunds cannot exceed that sale.

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