Skip to main content
POST
/
api
/
v1
/
contracts
curl -X POST "https://commodityai.app/api/v1/contracts" \
  -H "Authorization: Bearer cai_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-contract-10024-create" \
  -d '{
    "type": "purchase",
    "counterparty_id": "223e4567-e89b-12d3-a456-426614174001",
    "external_reference": "ERP-PO-10024",
    "contract_date": "2026-05-19",
    "product_id": "923e4567-e89b-12d3-a456-426614174009",
    "grade_id": "a23e4567-e89b-12d3-a456-426614174010",
    "quantity": "50000",
    "quantity_unit_id": "323e4567-e89b-12d3-a456-426614174002",
    "pricing_type": "fixed",
    "price": "12.50",
    "price_currency_id": "d23e4567-e89b-12d3-a456-426614174013",
    "price_unit_id": "323e4567-e89b-12d3-a456-426614174002",
    "incoterms": "FOB",
    "shipment_start": "2026-06-01",
    "shipment_end": "2026-06-30",
    "payment_terms_type": "net",
    "payment_terms_days": 30,
    "quality_attributes": {
      "b23e4567-e89b-12d3-a456-426614174011": "Brazil",
      "c23e4567-e89b-12d3-a456-426614174012": "34"
    },
    "legs": [
      {
        "label": "A",
        "quantity": "25000",
        "overrides": {
          "shipment_start": "2026-06-01",
          "shipment_end": "2026-06-15"
        }
      },
      {
        "label": "B",
        "quantity": "25000",
        "overrides": {
          "shipment_start": "2026-06-16",
          "shipment_end": "2026-06-30"
        }
      }
    ]
  }'

{
  "contract": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "contract_number": "P0001",
    "type": "purchase",
    "status": "draft",
    "external_reference": "ERP-PO-10024"
  },
  "legs": [
    {
      "id": "423e4567-e89b-12d3-a456-426614174003",
      "label": "A",
      "quantity": "25000",
      "reference": "P0001.A"
    },
    {
      "id": "523e4567-e89b-12d3-a456-426614174004",
      "label": "B",
      "quantity": "25000",
      "reference": "P0001.B"
    }
  ],
  "warnings": []
}

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 a purchase or sale contract and returns the public contract shape with generated CommodityAI identifiers and references. Create Contract is the entry point for standard object flows around purchasing, sales, quality, pricing, and allocation. The public request should stay focused on commercial contract data. Advanced structures such as formula pricing and extension fields are available when they have been enabled for your integration.

​
Headers

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

​
Core Contract Fields

​
type
string
required
Contract side. Values: purchase, sale.
​
counterparty_id
string
required
Counterparty UUID for the supplier or buyer.
​
external_reference
string
Stable source-system contract reference. Use this for cross-system reconciliation, not as a replacement for Idempotency-Key.
​
contract_date
string
Contract date in YYYY-MM-DD format.
​
product_id
string
Product catalog UUID. Prefer this when using CommodityAI product reference data.
​
product
string
Product name when not using a product catalog ID.
​
grade_id
string
Product grade UUID.
​
quantity
string
Contract quantity as a positive numeric string.
​
quantity_unit_id
string
Quantity unit UUID.
​
pricing_type
string
Pricing type. Values: fixed, futures, formula.
​
price
string
Fixed price as a positive numeric string.
​
price_currency_id
string
Currency UUID for the quoted price.
​
price_unit_id
string
Unit UUID for the quoted price.
​
incoterms
string
Incoterms value such as FOB, CIF, or CFR.
​
shipment_start
string
Shipment period start date in YYYY-MM-DD format.
​
shipment_end
string
Shipment period end date in YYYY-MM-DD format.
​
payment_terms_type
string
Payment terms type. Values: net, prepayment, cad, lc, open_account.
​
payment_terms_days
number
Number of days for net-style payment terms.
​
standard_payment_terms_id
string
Standard payment term UUID from reference data.

​
External References

Use external_reference for the stable identifier from your ERP, CTRM, or integration source. It should not change when a contract is amended or retried. Use Idempotency-Key for retry protection. Unless CommodityAI has configured duplicate prevention for your integration, do not assume external_reference alone makes create requests idempotent.

​
Optional Structures

​
legs
array
Optional contract legs. Use legs when a contract needs tranche-level quantity, shipment windows, delivery terms, or other overrides.
​
quality_attributes
object
Structured product attribute values keyed by product attribute UUID. For select attributes, the value is an option UUID. For multi_select attributes, the value is an array of option UUIDs.
​
quality_specifications
array
Optional contract-scoped quality specifications. Requires product_id.
If legs is omitted, CommodityAI creates one default leg with label 0 that inherits the contract fields. If legs is provided, it must contain at least two legs. Labels default to A, B, C, and must be unique uppercase letters. Each leg has:
FieldTypeNotes
labelstringOptional single uppercase letter. Defaults to A, B, C, … in tranched mode.
quantitystringPositive numeric string.
overridesobjectOptional overrides for inherited contract fields.

​
Advanced Structures

​
pricing_terms
array
Formula pricing terms for the contract or a specific leg. See Pricing Terms.
​
extension_fields
object
Company-specific contract extension fields enabled for your integration.

​
Side Effects

Creating a contract can also create or schedule related standard-object work:
  • A default leg or lettered contract legs are created for allocation and fulfillment.
  • Contract quality specifications may be seeded from product or grade templates.
  • Sale contracts may create expected letter-of-credit workflow records when LC terms apply.
  • Document requirements may be synced and requirement checks may be scheduled.

​
Request Example

curl -X POST "https://commodityai.app/api/v1/contracts" \
  -H "Authorization: Bearer cai_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-contract-10024-create" \
  -d '{
    "type": "purchase",
    "counterparty_id": "223e4567-e89b-12d3-a456-426614174001",
    "external_reference": "ERP-PO-10024",
    "contract_date": "2026-05-19",
    "product_id": "923e4567-e89b-12d3-a456-426614174009",
    "grade_id": "a23e4567-e89b-12d3-a456-426614174010",
    "quantity": "50000",
    "quantity_unit_id": "323e4567-e89b-12d3-a456-426614174002",
    "pricing_type": "fixed",
    "price": "12.50",
    "price_currency_id": "d23e4567-e89b-12d3-a456-426614174013",
    "price_unit_id": "323e4567-e89b-12d3-a456-426614174002",
    "incoterms": "FOB",
    "shipment_start": "2026-06-01",
    "shipment_end": "2026-06-30",
    "payment_terms_type": "net",
    "payment_terms_days": 30,
    "quality_attributes": {
      "b23e4567-e89b-12d3-a456-426614174011": "Brazil",
      "c23e4567-e89b-12d3-a456-426614174012": "34"
    },
    "legs": [
      {
        "label": "A",
        "quantity": "25000",
        "overrides": {
          "shipment_start": "2026-06-01",
          "shipment_end": "2026-06-15"
        }
      },
      {
        "label": "B",
        "quantity": "25000",
        "overrides": {
          "shipment_start": "2026-06-16",
          "shipment_end": "2026-06-30"
        }
      }
    ]
  }'

​
Public Response Shape

The response is a public API shape, not a raw internal database object. Stable fields include:
FieldNotes
contract.idCommodityAI contract UUID.
contract.contract_numberGenerated display reference such as P0001 or S0001.
contract.typepurchase or sale.
contract.statusCurrent lifecycle status. New contracts usually start as draft.
contract.external_referenceSource-system reference when provided.
legs[]Public leg IDs, labels, quantities, and generated leg references when available.
warnings[]Optional non-blocking warnings from downstream workflow setup.
{
  "contract": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "contract_number": "P0001",
    "type": "purchase",
    "status": "draft",
    "external_reference": "ERP-PO-10024"
  },
  "legs": [
    {
      "id": "423e4567-e89b-12d3-a456-426614174003",
      "label": "A",
      "quantity": "25000",
      "reference": "P0001.A"
    },
    {
      "id": "523e4567-e89b-12d3-a456-426614174004",
      "label": "B",
      "quantity": "25000",
      "reference": "P0001.B"
    }
  ],
  "warnings": []
}

​
Errors and Warnings

Errors use stable HTTP status codes and machine-readable error_code values where a business rule blocks the request.
StatusCodeMeaning
400validation_errorRequired fields, IDs, date formats, product attribute values, or pricing payloads are invalid.
404not_foundA referenced counterparty, product, grade, unit, currency, port, or template was not found for the company.
409duplicate_or_conflictThe request conflicts with an existing contract or integration rule.
422business_rule_failedThe contract is structurally valid but fails a CommodityAI contract rule.
Warnings are returned in warnings[] when CommodityAI accepts the contract but needs to report non-blocking workflow setup issues.