Programs

A program is the top-level container returned by GET /programs. It represents a manufacturer's incentive program for a given time frame and defines the structure within which participants can earn incentives. Programs contain metadata, time boundaries, qualifications, and one or more offers.

At a Glance

Field	Type	Purpose
`key`	`string`	Unique identifier for the program
`label`	`string`	Human-readable name displayed in UIs
`summary`	`string`	Brief one-line summary of the program
`description`	`string`	Detailed description of the program's purpose and rules
`attributes`	`[Attribute]`	Arbitrary metadata labels attached to the program
`time_frame`	`string`	The program year or season (e.g., `"2026"`)
`key_dates`	`[TimePeriod]`	Notable dates associated with the program
`start_date`	`string`	Earliest date the program is effective
`end_date`	`string`	Latest date the program is effective
`sku_keys`	`[string]`	All SKUs referenced across qualifications in the program
`time_periods`	`[TimePeriod]`	Named date ranges used by program qualifications
`transaction_types`	`[string]`	Which transaction flows the program covers
`program_supplier_key`	`string`	Manufacturer or supplier that owns the program
`version`	`string`	Version identifier for the program configuration
`qualifications`	`[Qualification]`	Conditions that gate whether the program's offers pay out
`qualifier`	`string \\| null`	Boolean expression combining qualification results
`external_ids`	`[KeyValuePair]`	Cross-reference identifiers from external systems
`verifications`	`[Verification]`	Audit trail of who verified the program and when
`offers`	`[Offer]`	The individual earning opportunities within the program

Identification

Every program has a unique composite identity:

Field	Type	Description
`key`	`string`	Unique identifier for the program. Convention: `{supplier}.{year}.{channel}.{scope}.{category}` (e.g., `corteva.2026.retailer.national.crop_protection`)
`label`	`string`	Human-readable name displayed in UIs
`program_supplier_key`	`string`	Identifies the manufacturer or supplier that owns the program (e.g., `corteva`, `basf`, `syngenta`)
`version`	`string`	Version identifier for the program configuration. Changes when the program is updated

Programs Response

{
  "key": "corteva.2026.retailer.national.crop_protection",
  "label": "Corteva 2026 Retailer National Crop Protection",
  "program_supplier_key": "corteva",
  "version": "1.0.0"
}

Description

Programs carry two text fields that describe what the program is about:

Field	Type	Description
`summary`	`string`	A brief one-line summary of the program
`description`	`string`	A longer, detailed description of the program's purpose and rules

Time Frame & Dates

These fields define when the program is active:

Field	Type	Description
`time_frame`	`string`	The program year or season (e.g., `"2026"`)
`start_date`	`string`	The earliest date the program is effective (ISO 8601 format)
`end_date`	`string`	The latest date the program is effective (ISO 8601 format)

Programs Response

{
  "time_frame": "2026",
  "start_date": "2025-09-01",
  "end_date": "2026-12-31"
}

Reading this: This program covers the 2026 crop year, starting September 1, 2025 (when early-season purchasing begins) and ending December 31, 2026.

Time Periods

Time periods are named date ranges used by program qualifications to scope transactions to specific windows. A program can define multiple time periods — for example, an early-order window, a full incentive period, and a prior-year comparison period.

Field	Type	Description
`key`	`string`	Unique identifier referenced by program qualifications (e.g., `incentive_period`, `early_order_period`)
`label`	`string`	Human-readable name
`start_date`	`string`	Period start date (ISO 8601)
`start_date_label`	`string \\| null`	Human-friendly start date label
`end_date`	`string`	Period end date (ISO 8601)
`end_date_label`	`string \\| null`	Human-friendly end date label

Programs Response

{
  "time_periods": [
    {
      "key": "incentive_period",
      "label": "Full Season",
      "start_date": "2025-09-01",
      "end_date": "2026-08-31"
    },
    {
      "key": "early_order_period",
      "label": "Early Order",
      "start_date": "2025-09-01",
      "end_date": "2025-12-31"
    },
    {
      "key": "prior_year_period",
      "label": "Prior Year",
      "start_date": "2024-09-01",
      "end_date": "2025-08-31"
    }
  ]
}

Reading this: This program defines three periods. The incentive_period covers the full season. The early_order_period captures fall purchases. The prior_year_period is used by year-over-year qualifications to compare against the previous year.

Note

Time periods defined at the program level are available to all qualifications within the program. Offers define their own time periods separately.

Transaction Types

The transaction_types array lists which transaction flows are relevant to the program. This is the union of all transaction types used across qualifications in the program.

Transaction Type	Description
`retailer_purchases_from_distribution`	Purchases a retailer makes from a distributor
`retailer_sales_to_growers`	Sales a retailer makes to end-user growers
`contractor_purchases_from_distribution`	Purchases a contractor makes from distribution
`distributor_sales_to_retail`	Sales a distributor makes to retailers
`inventory`	Inventory-related transactions

Programs Response

{
  "transaction_types": [
    "retailer_purchases_from_distribution",
    "retailer_sales_to_growers"
  ]
}

SKU Keys

The sku_keys array contains every SKU referenced across all qualifications in the program. This is a convenience field — the engine extracts it automatically from qualification filters.

{
  "sku_keys": [
    "agri_shield_insecticide_2.5_gal_53551",
    "crop_guard_30_l_herbicide_2.5_gal_22654",
    "harvest_max_pro_herbicide_2.5_gal_46367"
  ]
}

Note

This only includes SKUs from qualification filters, not from offer incentives. Each offer carries its own sku_keys array for the SKUs it incentivizes.

Qualifications & Qualifier

Programs can define qualifications — conditions that must be met before any of the program's offers are evaluated. If the program-level qualifier evaluates to false, none of its offers pay out.

Field	Type	Description
`qualifications`	`[Qualification]`	Array of qualification definitions. See Qualifications for all seven types
`qualifier`	`string \\| null`	Boolean expression combining qualification keys with `AND` / `OR` logic. If `null`, the program is always considered qualified

Programs Response

{
  "qualifications": [
    {
      "type": "aggregated_amount",
      "key": "minimum_cp_purchases",
      "label": "Minimum Crop Protection Purchases",
      "operator": "greater_than_or_equal_to",
      "value": 100000.0,
      "filters": [
        {
          "period_key": "incentive_period",
          "sku_keys": ["agri_shield_insecticide_2.5_gal_53551"],
          "transaction_type": "retailer_purchases_from_distribution"
        }
      ],
      "attributes": []
    }
  ],
  "qualifier": "minimum_cp_purchases"
}

Reading this: The program requires at least $100,000 in crop protection purchases. Only if this qualification is met will the program's offers be evaluated.

For a complete reference of all qualification types and how qualifiers work, see Qualifications.

Verifications

Verifications provide an audit trail of who has reviewed and verified the program configuration:

Field	Type	Description
`verified_by`	`string`	Who performed the verification: `"gmatter"` or `"program_supplier"`
`verified_on`	`string`	Date the verification occurred (ISO 8601)
`notes`	`string`	Free-text notes about the verification

Programs Response

{
  "verifications": [
    {
      "verified_by": "gmatter",
      "verified_on": "2025-08-15",
      "notes": "Program configuration verified against manufacturer documentation"
    },
    {
      "verified_by": "program_supplier",
      "verified_on": "2025-08-20",
      "notes": "Confirmed rates and qualification thresholds"
    }
  ]
}

External IDs

External IDs allow the program to be cross-referenced with identifiers from other systems. Each entry is a typed key-value pair:

Field	Type	Description
`type`	`string`	The type of the value: `"string"`, `"number"`, `"boolean"`, or `"json"`
`key`	`string`	The identifier key in the external system
`value`	varies	The identifier value

Programs Response

{
  "external_ids": [
    {
      "type": "string",
      "key": "nocodb_id",
      "value": "rec_abc123"
    }
  ]
}

Attributes

Attributes are arbitrary metadata labels attached to a program. They are not used in calculation logic but provide additional context.

Field	Type	Description
`type`	`string`	Category or type of the attribute
`value`	`string`	The attribute value
`label`	`string`	Human-readable label

Programs Response

{
  "attributes": [
    {
      "type": "category",
      "value": "crop_protection",
      "label": "Crop Protection"
    },
    {
      "type": "channel",
      "value": "retailer",
      "label": "Retailer"
    }
  ]
}

Key Dates

The key_dates array contains notable dates associated with the program. These use the same TimePeriod structure as time periods:

{
  "key_dates": [
    {
      "key": "sign_up_deadline",
      "label": "Sign-Up Deadline",
      "start_date": "2025-09-01",
      "end_date": "2025-11-30"
    }
  ]
}

Offers

The offers array contains the individual earning opportunities within the program. Each offer defines which SKUs are incentivized, how the incentive is calculated, and any offer-level qualifications.

Programs typically contain one or more offers. A single program might have a base rebate offer, a growth bonus offer, and a loyalty offer — each with different SKUs, rates, and qualification requirements.

For a complete reference of offer structure and components, see Offers.

Programs Response (abbreviated)

{
  "offers": [
    {
      "key": "corteva.2026.retailer.national.crop_protection.base",
      "label": "Base Rebate",
      "strategy_key": "standard",
      "calculator_key": "percent_of_amount",
      "sku_keys": ["agri_shield_insecticide_2.5_gal_53551", "crop_guard_30_l_herbicide_2.5_gal_22654"],
      "..."
    },
    {
      "key": "corteva.2026.retailer.national.crop_protection.growth",
      "label": "Growth Bonus",
      "strategy_key": "stepped",
      "calculator_key": "percent_of_amount",
      "sku_keys": ["agri_shield_insecticide_2.5_gal_53551"],
      "..."
    }
  ]
}

Program State

Programs have a state that controls whether they are active and visible. State is determined from the program's operational status and catalog status:

State	Description
`unreleased`	Program has not yet been released for use
`released`	Program is active and available for calculations
`suspended`	Program has been temporarily suspended

State can be influenced by a state override (explicitly suspending or releasing a program) and by the catalog status of the program's SKUs and prices (whether all required SKUs and their prices are present in the system).

Complete Programs Response

Putting all the components together, a full program in the GET /programs response looks like this:

{
  "key": "corteva.2026.retailer.national.crop_protection",
  "label": "Corteva 2026 Retailer National Crop Protection",
  "summary": "National crop protection rebate program for retailers",
  "description": "Offers base and growth rebates on Corteva crop protection products purchased through distribution.",
  "attributes": [
    { "type": "category", "value": "crop_protection", "label": "Crop Protection" }
  ],
  "time_frame": "2026",
  "key_dates": [],
  "start_date": "2025-09-01",
  "end_date": "2026-12-31",
  "sku_keys": ["agri_shield_insecticide_2.5_gal_53551", "crop_guard_30_l_herbicide_2.5_gal_22654"],
  "time_periods": [
    {
      "key": "incentive_period",
      "label": "Full Season",
      "start_date": "2025-09-01",
      "end_date": "2026-08-31"
    }
  ],
  "transaction_types": ["retailer_purchases_from_distribution"],
  "program_supplier_key": "corteva",
  "version": "1.0.0",
  "qualifications": [
    {
      "type": "aggregated_amount",
      "key": "minimum_cp_purchases",
      "label": "Minimum Crop Protection Purchases",
      "operator": "greater_than_or_equal_to",
      "value": 100000.0,
      "filters": [
        {
          "period_key": "incentive_period",
          "sku_keys": ["agri_shield_insecticide_2.5_gal_53551", "crop_guard_30_l_herbicide_2.5_gal_22654"],
          "transaction_type": "retailer_purchases_from_distribution"
        }
      ],
      "attributes": []
    }
  ],
  "qualifier": "minimum_cp_purchases",
  "external_ids": [],
  "verifications": [
    {
      "verified_by": "gmatter",
      "verified_on": "2025-08-15",
      "notes": "Verified against manufacturer program guide"
    }
  ],
  "offers": [
    { "..." }
  ]
}

Summary

A program is the top-level container for a manufacturer's incentive program
It defines the time frame, time periods, transaction types, and SKUs that scope the entire program
Qualifications at the program level gate whether any offers within the program are evaluated — see Qualifications
Offers within the program define the actual earning opportunities — see Offers
Verifications and external IDs provide audit trails and cross-system references
State controls whether the program is active (released), pending (unreleased), or paused (suspended)