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:

1POST /v1/catalog/entries
2Content-Type: application/json
3
4{
5  "ottimate_company_id": 15196,
6  "erp_vendor_id": "9999",
7  "item_name": "BACON BITS PER LB",
8  "upc": "23585000000",
9  "reference_id": "23585000000",
10  "price": 3.99,
11  "allowances": [
12    {
13      "allowance_type": "discount",
14      "amount": 0.25,
15      "unit_allowance": 0.25,
16      "target": "location",
17      "ottimate_location_id": 456,
18      "start_date": "2024-01-01T00:00:00Z",
19      "end_date": "2024-12-31T23:59:59Z",
20      "reference_id": "sysco-tomato-rebate-2024"
21    }
22  ]
23}

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". Cross-validation against ottimate_location_id/ottimate_group_id depends on which endpoint you use — see note below.
ottimate_location_idIntegerNoLocation ID. Required when target is "location" when creating a nested allowance via POST /v1/catalog/entries (shown above) — see note below for how this differs on the standalone allowance endpoints.
ottimate_group_idIntegerNoLocation group ID. Required when target is "location_group" when creating a nested allowance via POST /v1/catalog/entries — see note below.
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

Cross-validation of target against ottimate_location_id/ottimate_group_id differs by endpoint. The nested path shown above (allowances inside POST /v1/catalog/entries) does enforce it: target: "location" without ottimate_location_id returns a 400, and the same for target: "location_group" without ottimate_group_id.

The standalone endpoints below (POST/PATCH /v1/catalog/allowances) do NOT enforce this — keep them consistent yourself. target: "location" without ottimate_location_id does not error there; it creates an allowance with no location scope. The reverse also isn’t checked: target: "company" with an ottimate_location_id supplied stores that location id as-is rather than clearing it, leaving the allowance internally inconsistent (target_type: "company" with a non-null location id).

Managing Allowances Separately

List allowances for a catalog entry:

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

Filter by effective date:

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

Filter by location:

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

Create a new allowance:

1POST /v1/catalog/allowances
2Content-Type: application/json
3
4{
5  "catalog_entry_id": "cte_12345",
6  "ottimate_company_id": 15196,
7  "allowance_type": "rebate",
8  "amount": 2.00,
9  "target": "company",
10  "start_date": "2024-12-01T00:00:00Z",
11  "reference_id": "sysco-tomato-q4-rebate"
12}

Update an allowance:

1PATCH /v1/catalog/allowances/cta_jUqG68oiPFBj
2Content-Type: application/json
3
4{
5  "amount": 2.50,
6  "end_date": "2025-12-31T23:59:59Z"
7}

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.