Skip to main content
PATCH
/
api
/
v1
/
contracts
/
{id}
curl -X PATCH "https://commodityai.app/api/v1/contracts/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer cai_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-contract-10024-status-active" \
  -d '{
    "status": "active",
    "shipment_end": "2026-07-05",
    "extension_fields": {
      "source_system": "ERP"
    }
  }'

{
  "contract": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "contract_number": "P0001",
    "status": "active",
    "shipment_end": "2026-07-05"
  }
}

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.

Updates a contract. Use this endpoint for status transitions, commercial field changes, and extension fields.

​
Path Parameters

​
id
string
required
Contract UUID.

​
Headers

HeaderRequiredNotes
Idempotency-KeyYesUnique key for safely retrying this write. Use a stable value from your source system, such as erp-contract-10024-status-active.

​
Request Body

​
status
string
Lifecycle status. Values: draft, active, fulfilled, closed.
​
external_reference
string
Source-system contract reference.
​
counterparty_id
string
Counterparty UUID.
​
product
string
Product name when not using a product catalog ID.
​
quantity
string
Contract quantity as a positive numeric string.
​
price
string
Fixed price as a positive numeric string.
​
shipment_start
string
Shipment period start date in YYYY-MM-DD format.
​
shipment_end
string
Shipment period end date in YYYY-MM-DD format.
​
quality_attributes
object
Structured product attribute values keyed by product attribute UUID.
​
extension_fields
object
Company-specific extension fields.
​
confirmed
boolean
Confirms an update when CommodityAI returns an impact warning that requires confirmation.

​
Request Example

curl -X PATCH "https://commodityai.app/api/v1/contracts/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer cai_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-contract-10024-status-active" \
  -d '{
    "status": "active",
    "shipment_end": "2026-07-05",
    "extension_fields": {
      "source_system": "ERP"
    }
  }'

​
Response

{
  "contract": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "contract_number": "P0001",
    "status": "active",
    "shipment_end": "2026-07-05"
  }
}

​
Errors and Warnings

Some updates can affect allocations, document requirements, pricing, or other downstream workflow state. If an update needs explicit confirmation, CommodityAI returns a warning response with requires_confirmation: true. Retry the same update with confirmed: true after reviewing the impact.
StatusCodeMeaning
400validation_errorRequired fields, IDs, date formats, or product attribute values are invalid.
404not_foundThe contract or a referenced record was not found for the company.
409conflictThe requested change conflicts with the contract lifecycle or existing downstream records.
422business_rule_failedThe update is structurally valid but fails a CommodityAI contract rule.