Skip to navigation
CatalogCatalog-Entries

Allowances

Learn how to manage allowances for a catalog entry

Allowances represent item-specific discounts or rebates applied to catalog entries stored in Ottimate. Common use cases include:

  • Volume rebates from distributors
  • Promotional discounts
  • Contract-based pricing adjustments

Configuration Requirements

Allowances require the client to have been configured for related features

Creating Allowances

If you wish to include allowances in Ottimate, include the allowances array when creating catalog entries:

POST /v1/catalog/entries
Content-Type: application/json
{
  "ottimate_company_id": 15196,
  "erp_vendor_id": "9999",
  "item_name": "BACON BITS PER LB",
  "upc": "23585000000",
  "reference_id": "23585000000",
  "price": 3.99,
  "allowances": [
    {
      "allowance_type": "discount",
      "amount": 0.25,
      "unit_allowance": 0.25,
      "target": "location",
      "ottimate_location_id": 456,
      "start_date": "2024-01-01T00:00:00Z",
      "end_date": "2024-12-31T23:59:59Z",
      "reference_id": "sysco-tomato-rebate-2024"
    }
  ]
}

Allowance Object Fields

FieldTypeRequiredDescription
allowance_typeStringNoType of allowance: "rebate", "discount", or "allowance". Defaults to "allowance".
amountDecimalNoTotal allowance amount per case
unit_allowanceDecimalNoAllowance per unit
percent_allowanceDecimalNoPercentage-based allowance (0-999.99). Mutually exclusive with amount/unit_allowance: on create, sending a nonzero amount/unit_allowance together with a nonzero percent_allowance is rejected (400); on update, setting percent_allowance automatically zeroes out the existing amount/unit_allowance.
targetEnumNoLevel at which the allowance should be applied:"company", "location", or "location_group". Determines whether ottimate_location_id/ottimate_group_id are required — see below.
ottimate_location_idIntegerNoLocation ID. Required when target is "location" (400 if omitted). Returns a 400 if supplied while target is "company" or "location_group". Cannot be combined with ottimate_group_id. Enforced identically on the nested path (allowances inside POST /catalog/entries) and the standalone POST/PATCH /catalog/allowances endpoints.
ottimate_group_idIntegerNoLocation group ID. Required when target is "location_group" (400 if omitted). Returns a 400 if supplied while target is "company" or "location". Cannot be combined with ottimate_location_id. Enforced identically on the nested path and the standalone endpoints.
start_dateDateTimeYesDate when allowance becomes effective.
end_dateDateTimeNoDate when allowance expires. If omitted at creation, defaults to 36,500 days (~100 years) after start_date rather than staying unset.
reference_idStringNoUnique identifier for this allowance

Managing Allowances Separately

List allowances for a catalog entry:

GET /v1/catalog/allowances?catalog_entry_id=cte_12345&ottimate_company_id=15196

Filter by effective date:

GET /v1/catalog/allowances?catalog_entry_id=cte_12345&ottimate_company_id=15196&effective_date=2024-12-01

Filter by location:

GET /v1/catalog/allowances?catalog_entry_id=cte_12345&ottimate_company_id=15196&ottimate_location_id=456

Create a new allowance:

POST /v1/catalog/allowances
Content-Type: application/json
{
  "catalog_entry_id": "cte_12345",
  "ottimate_company_id": 15196,
  "allowance_type": "rebate",
  "amount": 2.00,
  "target": "company",
  "start_date": "2024-12-01T00:00:00Z",
  "reference_id": "sysco-tomato-q4-rebate"
}

Update an allowance:

PATCH /v1/catalog/allowances/cta_jUqG68oiPFBj
Content-Type: application/json
{
  "amount": 2.50,
  "end_date": "2025-12-31T23:59:59Z"
}

All fields are optional on update. catalog_entry_id cannot be changed through this endpoint — any value you send is silently overwritten with the allowance’s existing catalog entry before the update runs, so an allowance can’t be moved to a different catalog entry after creation.