Skip to main content

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.

Pricing terms are an advanced contract creation structure. Use them when CommodityAI has enabled formula pricing for your integration and you need to describe how contract price should be interpreted or calculated. Pricing terms are currently created as part of Create Contract.

​
Pricing Term Fields

FieldTypeNotes
leg_labelstringOptional. Use 0 for a simple contract’s default leg, or A, B, … for tranched legs.
pricing_rolestringfinal or provisional. Defaults to final.
formula_result_typestringunit_price or total_value. Defaults to unit_price.
pricing_familystringRequired family key.
term_kindstringfixed, index_formula, netback_formula, buyback_formula, split_pricing, import_agent, or other.
formula_textstringOptional readable formula.
formula_astobjectRequired structured formula.
finalization_triggerstringOptional rule for when pricing finalizes.
settlement_termsstringOptional settlement language.
output_currency_idstringOptional currency UUID.
output_unit_idstringOptional unit UUID.
quote_unit_textstringOptional quote unit label.
commentsstringOptional notes.
source_contextobjectOptional source/provenance context.
componentsarrayFormula components. Defaults to [].

​
Components

Each component has component_key, label, and component_type. Supported component types include market_index, index_average, quality_assay, constant, premium_discount, freight, conversion, moisture, option, formula, external_resale, fee, and other. Components can also include market_index_id, value_amount, value_type, currency_id, unit_id, quote_unit_text, quality_assay, basis_percent, quotation-period fields, source_text, and metadata. Use Market Indexes to resolve market_index_id for market_index and index_average components.

​
Formula AST

formula_ast uses version 1 and a root formula node. 
{
  "version": "1",
  "root": {
    "type": "component_ref",
    "componentKey": "index_price"
  }
}
Supported node types are literal, list, component_ref, physical_ref, unary_op, binary_op, comparison_op, logical_op, case, and function.

​
Example

{
  "pricing_terms": [
    {
      "leg_label": "A",
      "pricing_role": "final",
      "formula_result_type": "unit_price",
      "pricing_family": "discharge_port_differential",
      "term_kind": "index_formula",
      "output_currency_id": "55555555-5555-5555-5555-555555555555",
      "output_unit_id": "66666666-6666-6666-6666-666666666666",
      "formula_ast": {
        "version": "1",
        "root": {
          "type": "case",
          "branches": [
            {
              "when": {
                "type": "comparison_op",
                "op": "in",
                "left": {
                  "type": "physical_ref",
                  "key": "discharge_port",
                  "basis": "actual"
                },
                "right": {
                  "type": "list",
                  "items": [
                    {
                      "type": "literal",
                      "value": "Tianjin",
                      "valueType": "text"
                    }
                  ]
                }
              },
              "result": {
                "type": "component_ref",
                "componentKey": "north_china_freight_diff"
              }
            }
          ],
          "else": {
            "type": "literal",
            "value": "0",
            "valueType": "number"
          }
        }
      },
      "components": [
        {
          "component_key": "north_china_freight_diff",
          "label": "North China freight differential",
          "component_type": "freight",
          "currency_id": "55555555-5555-5555-5555-555555555555",
          "unit_id": "66666666-6666-6666-6666-666666666666"
        }
      ]
    }
  ]
}