Contracts are the center of CommodityAI’s standard object model. They represent purchase and sale agreements, with legs for allocatable segments and allocations for buy-to-sell coverage. Use these APIs when an external system creates or maintains contract records and needs CommodityAI IDs and references for reconciliation.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.
Resource Model
| Resource | Role |
|---|---|
| Contract | Parent purchase or sale agreement. Stores counterparty, product, quantity, delivery, payment, status, and external reference metadata. |
| Leg | Allocatable segment of a contract. Simple contracts use one default leg; tranched contracts use multiple lettered legs with leg-level overrides. |
| Allocation | Quantity assigned to a purchase leg, sale leg, or both sides. Complete allocations connect purchase volume to sale volume. |
| Product attributes | Commodity-specific product fields such as grade, origin, form, packaging, and company-defined attributes. |
| Quality specification | Structured requirement set for contracted product quality, tolerances, sampling, inspection, or certificate requirements. |
Flow
- Create purchase and sale contracts.
- Add legs when a contract needs tranches, shipment windows, ports, destinations, or quantity splits.
- Set product attributes and quality specifications at the contract level.
- Override product, quality, pricing, delivery, or payment fields on legs when needed.
- Create allocations for purchase-side, sale-side, or complete purchase-to-sale coverage.
- Store returned IDs and references in the upstream system.
Create Model
Contract creation is not just a parent record insert. CommodityAI also creates the operating structure around the contract:| Area | Behavior |
|---|---|
| Legs | Creates one default 0 leg for simple contracts, or lettered legs for tranched contracts. |
| Product attributes | Accepts structured product attribute values through quality_attributes or the attribute-values endpoint. |
| Quality specifications | Creates contract-scoped quality specs when provided, or seeds from product and grade templates. |
| Pricing terms | Stores formula pricing terms and components, optionally scoped to a leg. |
| Extension fields | Validates and stores configured contract extension fields. |
| Controls | Validates tenant references, tolerance ranges, pricing term references, and counterparty limits. |
References
| Example | Meaning |
|---|---|
P0001 | Purchase contract |
S0001 | Sale contract |
P0001.001 | Simple purchase-side allocation reference |
P0001.A01 | Tranched purchase-side allocation reference |
Endpoints
List Contracts
Retrieve company contracts.
Create Contract
Create a purchase or sale contract.
Product Attributes & Quality
Understand structured product values and quality specs.
Pricing Terms
Understand formula pricing terms accepted during contract creation.
Get Contract
Retrieve a single contract by ID.
Update Contract
Update commercial terms, status, or extension fields.
List Contract Legs
Retrieve allocatable legs for a contract.
Add Contract Leg
Add a tranche or allocatable segment.
List Allocations
Retrieve complete and partial allocation records.
Create Allocation
Create one-sided or purchase-to-sale allocations.
Set Attribute Values
Set structured product attribute values.