> This page is for version V1 (default).
> For other versions, use one of these documentation indexes:
> - V1 (default): https://docs.ottimate.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ottimate.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ottimate.com/_mcp/server.

# Allowances

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:

```json
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

| Field                  | Type     | Required | Description                                                                                                                                                                                                                                                                                                                                              |
| ---------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allowance_type`       | String   | No       | Type of allowance: `"rebate"`, `"discount"`, or `"allowance"`. Defaults to `"allowance"`.                                                                                                                                                                                                                                                                |
| `amount`               | Decimal  | No       | Total allowance amount per case                                                                                                                                                                                                                                                                                                                          |
| `unit_allowance`       | Decimal  | No       | Allowance per unit                                                                                                                                                                                                                                                                                                                                       |
| `percent_allowance`    | Decimal  | No       | Percentage-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`.                                  |
| `target`               | Enum     | No       | Level 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_id` | Integer  | No       | Location 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_id`    | Integer  | No       | Location 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_date`           | DateTime | Yes      | Date when allowance becomes effective.                                                                                                                                                                                                                                                                                                                   |
| `end_date`             | DateTime | No       | Date when allowance expires. If omitted at creation, defaults to 36,500 days (\~100 years) after `start_date` rather than staying unset.                                                                                                                                                                                                                 |
| `reference_id`         | String   | No       | Unique identifier for this allowance                                                                                                                                                                                                                                                                                                                     |

#### Managing Allowances Separately

**List allowances for a catalog entry:**

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

**Filter by effective date:**

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

**Filter by location:**

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

**Create a new allowance:**

```http
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:**

```http
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.