Purchase Needs

Overview

Purchase needs represent internal procurement demands from a buyer's system. They express the quantities needed by delivery warehouses for specific products within a date range.

Important: Purchase needs are internal to the buyer organization and are not visible to suppliers. They are used by buyer personas (e.g., retailer employees) to perform allocation—matching supplier-offered quantities against warehouse-expressed demands.

This endpoint enables buyers to:

Submit procurement demands from ERP or planning systems
Track and update fulfillment status as allocations are made
Incrementally update existing needs (quantities, status) over multiple API calls

Endpoints

Method	Endpoint	Description
POST	`/v2/partner/{workspaceID}/purchase-needs`	Create or update purchase needs
GET	`/v2/partner/{workspaceID}/purchase-needs`	Get purchase needs by date range

Data Model

Structure

Each purchase need is a flat record representing a single product demand—one record per product, quantity, delivery window, and location. There is no header/line hierarchy; each record is self-contained.

Idempotency

The code field is the idempotency key:

Submitting a new code creates a new record
Resubmitting an existing code updates the existing record

This allows safe retries and incremental updates without creating duplicates.

Fields

Field	Type	Required	Description
`id`	uint	No	Consentio internal ID (read-only)
`code`	string(256)	Yes	Unique identifier — idempotency key
`reference_code`	string(256)	Yes	Product code (EAN/SKU/internal)
`start_date`	date	Yes	Start of delivery window (ISO 8601)
`end_date`	date	Yes	End of delivery window (ISO 8601)
`quantity`	number	Yes	Requested quantity
`quantity_unit`	enum	Yes	Unit of measure: `box`, `pallet`, `kg`, `piece`, `unknown`
`external_status`	string(32)	Yes	Fulfillment status (free-form)
`storage_location_code`	string(20)	No	Warehouse or storage facility code
`delivery_address_code`	string(20)	No	Delivery address or depot code
`logistics_unit_code`	string(20)	No	Logistics unit type code
`tender_kind`	enum	No	Tender type: `standard`, `promotion`, `regional_promotion`, `weekend_flash_offer`, `promotion_radio`, `promotion_leaflet`
`metadata`	object	No	Partner-specific key-value pairs
`created_at`	datetime	No	Creation timestamp (read-only)
`updated_at`	datetime	No	Last update timestamp (read-only)

Creating Purchase Needs

Submit one or more purchase needs using POST /purchase-needs. The request accepts a batch of flat records, each representing a single product demand.

Request

POST /v2/partner/{workspaceID}/purchase-needs
Content-Type: application/json
Authorization: Bearer {token}

{
  "purchase_needs": [
    {
      "code": "PN-2025-001234-001",
      "reference_code": "PRD-12345678",
      "start_date": "2025-03-15",
      "end_date": "2025-03-15",
      "quantity": 50,
      "quantity_unit": "box",
      "external_status": "A",
      "storage_location_code": "WH01",
      "delivery_address_code": "DEP03",
      "logistics_unit_code": "PAL",
      "tender_kind": "standard",
      "metadata": {
        "department": "fresh-produce",
        "priority": "high",
        "target_price": 12.50
      }
    },
    {
      "code": "PN-2025-001234-002",
      "reference_code": "PRD-87654321",
      "start_date": "2025-03-15",
      "end_date": "2025-03-15",
      "quantity": 30,
      "quantity_unit": "kg",
      "external_status": "A",
      "storage_location_code": "WH01",
      "delivery_address_code": "DEP03"
    }
  ]
}

Response

{
  "purchase_needs": [
    {
      "id": 12345,
      "code": "PN-2025-001234-001",
      "reference_code": "PRD-12345678",
      "start_date": "2025-03-15",
      "end_date": "2025-03-15",
      "quantity": 50,
      "quantity_unit": "box",
      "external_status": "A",
      "storage_location_code": "WH01",
      "delivery_address_code": "DEP03",
      "logistics_unit_code": "PAL",
      "tender_kind": "standard",
      "metadata": {
        "department": "fresh-produce",
        "priority": "high",
        "target_price": 12.50
      },
      "created_at": "2025-03-10T14:30:00Z",
      "updated_at": "2025-03-10T14:30:00Z"
    },
    {
      "id": 12346,
      "code": "PN-2025-001234-002",
      "reference_code": "PRD-87654321",
      "start_date": "2025-03-15",
      "end_date": "2025-03-15",
      "quantity": 30,
      "quantity_unit": "kg",
      "external_status": "A",
      "storage_location_code": "WH01",
      "delivery_address_code": "DEP03",
      "created_at": "2025-03-10T14:30:00Z",
      "updated_at": "2025-03-10T14:30:00Z"
    }
  ],
  "errors": []
}

Partial Success

The endpoint processes each purchase need independently. If some items fail validation, successfully processed items are returned in purchase_needs while errors are collected in errors:

{
  "purchase_needs": [
    { "id": 12345, "code": "PN-001", "..." : "..." }
  ],
  "errors": [
    "PN-002: reference_code 'INVALID' not found"
  ]
}

Retrieving Purchase Needs

Fetch existing purchase needs using GET /purchase-needs with date filters.

Request

GET /v2/partner/{workspaceID}/purchase-needs?start_date=2025-03-01&end_date=2025-03-31
Authorization: Bearer {token}

Query Parameters

Parameter	Type	Required	Description
`start_date`	date	Yes	Filter where `start_date >= start_date`
`end_date`	date	Yes	Filter where `end_date <= end_date`
`status`	string	No	Filter by `external_status` (exact match)

Response

Returns an array of purchase needs matching the filters.

Updating Purchase Needs

Purchase needs support incremental updates over multiple API calls. To update an existing record, resubmit it with the same code. The record will be fully replaced with the new values.

Any field can be updated: quantity, status, dates, metadata, etc.

Update Pattern

sequenceDiagram
    participant ERP as Buyer ERP
    participant API as Consentio API

    ERP->>API: POST { code: "PN-001", quantity: 50, external_status: "pending" }
    API-->>ERP: 200 OK (created)

    Note over ERP: Demand increased

    ERP->>API: POST { code: "PN-001", quantity: 75, external_status: "pending" }
    API-->>ERP: 200 OK (updated - quantity changed)

    Note over ERP: Partial allocation made

    ERP->>API: POST { code: "PN-001", quantity: 75, external_status: "partial" }
    API-->>ERP: 200 OK (updated - status changed)

Common Update Scenarios

Quantity adjustment: Demand changed—update quantity
Status progression: Update external_status as allocation progresses
Date changes: Adjust start_date or end_date if delivery window shifts
Metadata updates: Add or modify metadata fields with allocation details

Integration Workflow

Typical Flow

sequenceDiagram
    participant ERP as Buyer ERP
    participant API as Consentio API
    participant User as Buyer User (Allocation)

    ERP->>API: POST /purchase-needs
(warehouse demands)
    API-->>ERP: 200 OK (with Consentio IDs)

    Note over API: Needs stored internally
(not visible to suppliers)

    User->>API: View purchase needs
    User->>API: Allocate supplier offers
against warehouse needs

    loop As allocations progress or needs are updated
        ERP->>API: POST /purchase-needs
        API-->>ERP: 200 OK
    end

    ERP->>API: GET /purchase-needs?from=...&to=...
    API-->>ERP: Current status of all needs

Error Handling

HTTP Code	Meaning
200	Request processed (check `errors` for partial failures)
400	Invalid request body or parameters
401	Invalid or expired token
403	Insufficient permissions for this workspace

Best Practices

Use meaningful codes: The code field should uniquely identify each product demand in your system for easy reconciliation
Batch submissions: Submit multiple needs in a single request to reduce API calls
Incremental updates: Resubmit with the same code to update any field (quantity, status, dates, metadata)—no need to track Consentio IDs
Status tracking: Use external_status to reflect allocation progress (e.g., pending, partial, fulfilled)
Date ranges: Use start_date = end_date for single-day deliveries, or a range for flexible delivery windows
Metadata for context: Use metadata for allocation details, priority flags, or other partner-specific data
Idempotent retries: Safe to retry failed requests—duplicates are prevented by the code key

Orders

References