Skip to content

API: products awaiting a successor

When a product is replaced, Voorcast keeps asking what replaces it until someone answers. This endpoint lets your own systems read that list: for example, to find the old product when a new version arrives and needs a product created for it.

Before you start

You need an API key for your organization. Create one under Settings → Assistants and API keys. A read-only key is enough, because this endpoint only reads. Send it with every request:

Authorization: Bearer YOUR_API_KEY

A key only ever sees its own organization's products.

The request

GET https://api.voorcast.com/api/v1/products/awaiting-successor

Both filters are optional:

  • supplierId: only products from this supplier, or whose successor you expect from this supplier.
  • updatedSince: only products that changed at or after this time (ISO 8601, for example 2026-11-01T00:00:00Z). Use it to fetch only what changed since your last read.

The response

{
  "data": {
    "pending": 1,
    "untriaged": 1,
    "entries": [
      {
        "productId": "cm…",
        "sku": "ABC-2024",
        "name": "Example product 2024",
        "isActive": true,
        "stock": 0,
        "state": "PENDING",
        "statedAt": "2026-11-10T09:12:00.000Z",
        "supplierId": "cm…",
        "updatedAt": "2026-11-10T09:12:00.000Z",
        "expectedSuccessor": {
          "supplierId": "cm…",
          "supplierName": "Acme Supply",
          "supplierCode": "P-2025",
          "name": "Example product 2025",
          "price": 12.5
        },
        "proposedSuccessor": null
      }
    ]
  }
}

Each product has a state:

  • PENDING: someone said a replacement is coming that isn't in your catalogue yet. statedAt is when they said it.
  • UNTRIAGED: the product is marked replaced, but nobody has said what replaces it.

Products whose successor is settled are never listed: those with a confirmed successor, and those where someone said nothing replaces them.

expectedSuccessor is what the person expected the successor to arrive as: the supplier, the supplier's product code, the name and the purchase price excluding VAT. Any of these can be null, and the whole field is null when nothing was said.

proposedSuccessor is a product already in your catalogue that Voorcast suggests as the successor, with confidence from 0 to 1. It is a suggestion, not a confirmed answer, and it is null when there is none.

Errors

  • 401: the key is missing or invalid.
  • 400: updatedSince isn't a date.