Skip to main content
POST
/
api
/
v1
/
allocations
curl -X POST "https://commodityai.app/api/v1/allocations" \
  -H "Authorization: Bearer cai_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-allocation-7781-create" \
  -d '{
    "purchase_leg_id": "423e4567-e89b-12d3-a456-426614174003",
    "sale_leg_id": "823e4567-e89b-12d3-a456-426614174007",
    "quantity": "25000"
  }'

{
  "allocation": {
    "id": "923e4567-e89b-12d3-a456-426614174008",
    "purchase_leg_id": "423e4567-e89b-12d3-a456-426614174003",
    "sale_leg_id": "823e4567-e89b-12d3-a456-426614174007",
    "quantity": "25000",
    "quantity_unit_id": "323e4567-e89b-12d3-a456-426614174002",
    "purchase_sequence_number": 1,
    "sale_sequence_number": 1
  },
  "purchase_reference": "P0001.A01",
  "sale_reference": "S0001.A01"
}

Documentation Index

Fetch the complete documentation index at: https://docs.commodityai.io/llms.txt

Use this file to discover all available pages before exploring further.

Creates an allocation for a quantity. An allocation can be complete, with both a purchase leg and sale leg, or partial, with only one side provided. When both sides are provided, the allocation links purchased volume to sold volume. When only one side is provided, CommodityAI records the one-sided allocation and returns a reference for the provided side.

​
Create Behavior

  • At least one of purchase_leg_id or sale_leg_id is required.
  • quantity must be a positive numeric string.
  • The provided purchase leg must belong to a purchase contract.
  • The provided sale leg must belong to a sale contract.
  • Referenced contracts must be draft or active.
  • If both sides are present, they cannot belong to the same contract.
  • If both sides are present and both legs have quantity units, the units must match.
  • If both sides are present and either leg is in scheduled mode, the purchase and sale legs must be covered by a schedule.
  • Quantity cannot exceed remaining capacity on any provided leg.
  • quantity_unit_id is inherited from the purchase leg when present, otherwise from the sale leg.
  • CommodityAI assigns side-specific sequence numbers and derives display references such as P0001.001 or P0001.A01.

​
Headers

HeaderRequiredNotes
Idempotency-KeyYesUnique key for safely retrying this write. Use a stable value from your source system, such as erp-allocation-7781-create.

​
Request Body

​
purchase_leg_id
string
Purchase leg UUID. At least one of purchase_leg_id or sale_leg_id is required.
​
sale_leg_id
string
Sale leg UUID. At least one of purchase_leg_id or sale_leg_id is required.
​
quantity
string
required
Allocated quantity as a positive numeric string.

​
Request Example

curl -X POST "https://commodityai.app/api/v1/allocations" \
  -H "Authorization: Bearer cai_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-allocation-7781-create" \
  -d '{
    "purchase_leg_id": "423e4567-e89b-12d3-a456-426614174003",
    "sale_leg_id": "823e4567-e89b-12d3-a456-426614174007",
    "quantity": "25000"
  }'

​
Response

{
  "allocation": {
    "id": "923e4567-e89b-12d3-a456-426614174008",
    "purchase_leg_id": "423e4567-e89b-12d3-a456-426614174003",
    "sale_leg_id": "823e4567-e89b-12d3-a456-426614174007",
    "quantity": "25000",
    "quantity_unit_id": "323e4567-e89b-12d3-a456-426614174002",
    "purchase_sequence_number": 1,
    "sale_sequence_number": 1
  },
  "purchase_reference": "P0001.A01",
  "sale_reference": "S0001.A01"
}

​
Business Rule Errors

Errors use stable HTTP status codes and machine-readable error_code values when a business rule blocks the request. Warnings, when present, are returned separately from the created allocation.
CodeMeaning
WRONG_CONTRACT_TYPEThe purchase leg belongs to a sale contract, or the sale leg belongs to a purchase contract.
CONTRACT_CLOSEDA referenced contract is closed.
CONTRACT_FULFILLEDA referenced contract is fulfilled.
SELF_DEALINGBoth legs belong to the same contract.
COMPANY_MISMATCHA referenced leg does not belong to your company.
UNIT_INCOMPATIBLEPurchase and sale legs have incompatible quantity units.
SCHEDULE_NOT_COVEREDScheduled legs are not covered by a matching schedule.
CAPACITY_EXCEEDEDQuantity exceeds remaining capacity on one of the provided legs.