Allocora
Docs / Product API Endpoints

API Reference

Product API endpoints

Use product endpoints to keep catalog identifiers, categories, tags, and metadata aligned before revenue is imported or posted.

Start Free Try Sample Data

Details

What to know

Product object

A product represents a sellable item, subscription, service, or catalog entry that revenue can reference.

  • Use external_id to connect Allocora products to your source system.
  • Use category values configured in your workspace settings.
  • Use tags and metadata for reporting context.
  • Use archive endpoints when a product should stop behaving as active.

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

List products

Returns products and available category options.

  • Requires read:products.

Request example

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

Response example

{
  "data": [
    {
      "id": "<PRODUCT_ID>",
      "external_id": "sku_annual_pro",
      "name": "Annual Pro Plan",
      "category": "saas_subscription",
      "status": "active"
    }
  ],
  "category_options": [
    {"name": "saas_subscription", "label": "SaaS Subscription"}
  ]
}
GET /api/v1/products/{id}

Retrieve a product

Returns one product by ID.

  • Requires read:products.

Request example

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

Response example

{
  "data": {
    "id": "<PRODUCT_ID>",
    "external_id": "sku_annual_pro",
    "name": "Annual Pro Plan",
    "category": "saas_subscription",
    "status": "active",
    "revenue_count": 0
  },
  "category_options": [
    {"name": "saas_subscription", "label": "SaaS Subscription"}
  ]
}
POST /api/v1/products

Create a product

Creates one product.

  • Requires write:products.
  • external_id is optional but recommended for future upserts.

Request example

curl -X POST https://www.allocora.com/api/v1/products \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "sku_annual_pro",
    "name": "Annual Pro Plan",
    "category": "saas_subscription",
    "status": "active",
    "tags": ["subscription"]
  }'

Response example

{
  "data": {
    "id": "<PRODUCT_ID>",
    "external_id": "sku_annual_pro",
    "name": "Annual Pro Plan",
    "category": "saas_subscription",
    "status": "active",
    "tags": ["subscription"]
  }
}
POST /api/v1/products/upsert

Upsert a product

Creates or updates one product by external_id.

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

Request example

curl -X POST https://www.allocora.com/api/v1/products/upsert \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "sku_annual_pro",
    "operation": "create_or_update",
    "name": "Annual Pro Plan",
    "category": "saas_subscription",
    "status": "active"
  }'

Response example

{
  "data": {
    "id": "<PRODUCT_ID>",
    "external_id": "sku_annual_pro",
    "name": "Annual Pro Plan",
    "category": "saas_subscription",
    "status": "active"
  }
}
POST /api/v1/products/batch

Create products in batch

Creates up to 100 products in one request.

  • Requires write:products.
  • Each record uses the same fields as create product.

Request example

curl -X POST https://www.allocora.com/api/v1/products/batch \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "external_id": "sku_annual_pro",
        "name": "Annual Pro Plan",
        "category": "saas_subscription"
      }
    ]
  }'

Response example

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

Upsert products in batch

Creates or updates up to 100 products by external_id.

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

Request example

curl -X POST https://www.allocora.com/api/v1/products/batch/upsert \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "external_id": "sku_annual_pro",
        "operation": "create_or_update",
        "name": "Annual Pro Plan"
      }
    ]
  }'

Response example

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

Update a product

Updates one product by ID.

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

Request example

curl -X PUT https://www.allocora.com/api/v1/products/<PRODUCT_ID> \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Annual Pro Plan 2026",
    "status": "active"
  }'

Response example

{
  "data": {
    "id": "<PRODUCT_ID>",
    "external_id": "sku_annual_pro",
    "name": "Annual Pro Plan 2026",
    "status": "active"
  }
}
PUT /api/v1/products/batch

Update products in batch

Updates up to 100 products by ID.

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

Request example

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

Response example

{
  "data": [
    {
      "index": 0,
      "success": true,
      "status": 200,
      "response": {
        "data": {"id": "<PRODUCT_ID>", "status": "inactive"}
      }
    }
  ],
  "meta": {"processed": 1, "succeeded": 1, "failed": 0, "limit": 100}
}
DELETE /api/v1/products/{id}

Archive a product

Archives one product by ID.

  • Requires write:products.
  • Archived products return inactive status.

Request example

curl -X DELETE https://www.allocora.com/api/v1/products/<PRODUCT_ID> \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>"

Response example

{
  "data": {
    "id": "<PRODUCT_ID>",
    "external_id": "sku_annual_pro",
    "name": "Annual Pro Plan",
    "status": "inactive"
  }
}
DELETE /api/v1/products/batch

Archive products in batch

Archives up to 100 products by ID.

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

Request example

curl -X DELETE https://www.allocora.com/api/v1/products/batch \
  -H "Authorization: Bearer <ALLOCORA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {"id": "<PRODUCT_ID>"}
    ]
  }'

Response example

{
  "data": [
    {
      "index": 0,
      "success": true,
      "status": 200,
      "response": {
        "data": {"id": "<PRODUCT_ID>", "status": "inactive"}
      }
    }
  ],
  "meta": {"processed": 1, "succeeded": 1, "failed": 0, "limit": 100}
}

Reference Tables

Fields and checks

Common product fields

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

Field Type Notes
id string Allocora product ID returned by the API.
external_id string or null Your stable product identifier.
name string Display name for the product.
category string or null Workspace category key, such as saas_subscription.
status string active or inactive.
tags array Optional short labels.
metadata object Optional key/value context.
revenue_count integer Number of linked revenue records returned in responses.

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