---
title: "Create a catalog allowance"
method: POST
path: "/catalog/allowances"
tags: ["catalog"]
---

# Create a catalog allowance

`POST /catalog/allowances`

Creates a new catalog allowance for a catalog entry.

## Headers

- `Authorization` string, required
- `X-Api-Key` string, required
- `X-API-Version` string
- `Idempotency-Key` string

## Request body

- object
  - `ottimate_company_id` integer, required — The Ottimate company ID this allowance belongs to
  - `catalog_entry_id` string, required — The ID of the catalog entry this allowance applies to (prefixed with cte_)
  - `allowance_type` 'allowance' | 'discount' | 'rebate' — Type of allowance (default: 'allowance')
  - `amount` number, double — Allowance amount for the pack size (default: 0). Mutually exclusive with percent_allowance.
  - `unit_allowance` number, double — Allowance amount per individual unit (default: 0)
  - `percent_allowance` number, double — Percentage-based allowance (0-999.99). Mutually exclusive with amount and unit_allowance.
  - `target` 'company' | 'location_group' | 'location' — Allowance target: company (default), location_group, or location
  - `ottimate_location_id` integer — Location ID (required when target is location)
  - `ottimate_group_id` integer — Location group ID (required when target is 15/location_group)
  - `start_date` string, date-time, required — Allowance effective start date (ISO 8601)
  - `end_date` string, date-time — Allowance effective end date (ISO 8601, optional). If omitted, defaults to 36,500 days (~100 years) after start_date rather than staying null.
  - `reference_id` string — Unique reference ID for upsert operations

## Response `201`

Catalog allowance created successfully

- CatalogAllowanceObject — Catalog allowance object for standalone list endpoint
  - `id` string, required — Unique identifier (prefixed with cta_)
  - `catalog_entry_id` string, required — Associated catalog entry ID (prefixed with cte_)
  - `ottimate_company_id` integer, required — Company ID
  - `ottimate_location_id` integer — Location ID
  - `ottimate_group_id` integer — Location group ID
  - `allowance_type` 'allowance' | 'discount' | 'rebate', required — Type of allowance
  - `amount` string — Allowance amount (decimal string)
  - `unit_allowance` string — Unit allowance amount (decimal string)
  - `percent_allowance` string — Percentage-based allowance (decimal string). Always present and non-null - "0.00" when the allowance is not percent-mode.
  - `target` integer, required — Target code (10=company, 15=location_group, 20=location)
  - `target_type` 'company' | 'location_group' | 'location' — Human-readable target type
  - `start_date` string, date-time, required — Start date
  - `start_date_utc` string, date-time, nullable — UTC equivalent of start_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z".
  - `end_date` string, date-time — End date. Defaults to 36,500 days (~100 years) after start_date when not supplied at creation, rather than staying null.
  - `end_date_utc` string, date-time, nullable — UTC equivalent of end_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z".
  - `reference_id` string — Unique key
  - `created_date` string, date-time — Record creation date
  - `created_date_utc` string, date-time, nullable — UTC equivalent of created_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z".
  - `last_modified_date` string, date-time — Record last modified date
  - `last_modified_date_utc` string, date-time, nullable — UTC equivalent of last_modified_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z".

## Other responses

- `400` — Bad request - Invalid parameters or request format
- `401` — Unauthorized - Authentication required or invalid credentials
- `403` — Forbidden - Access denied or insufficient permissions

## Changes

- **2026-08-27** `f7c4667f0606` — 1 breaking, 1 info
  - the `catalog_entry_id` request property type/format changed from `integer`/`` to `string`/``
  - added the optional property `ottimate_group_id` to the response with the `201` status
- **2026-08-22** `75aab60eedc9` — 2 breaking, 1 warning
  - for the `header` request parameter `Idempotency-Key`, the minLength was increased from `0` to `1`
  - added the pattern `^[A-Za-z0-9._\-+=/]{1,128}$` to the `header` request parameter `Idempotency-Key`
  - for the `header` request parameter `Idempotency-Key`, the maxLength was set to `128`
- **2026-08-19** `c0b5cf6c7a72` — 1 info
  - added the non-success response with the status `403`
- **2026-08-17** `c231509a03cf` — 2 breaking, 8 info
  - the `message` response's property type/format changed from `string`/`` to ``/`` for status `400`
  - the `message` response's property type/format changed from `string`/`` to ``/`` for status `401`
  - the `amount` request property default value `0` was added
  - the `percent_allowance` request property default value `0` was added
  - …6 more
- **2026-08-13** `1f089f3e34d9` — 6 breaking
  - the response property `code` became optional for the status `400`
  - the response property `code` became optional for the status `401`
  - the response property `message` became optional for the status `400`
  - the response property `message` became optional for the status `401`
  - …2 more

[Change history](https://skmtc.dev/ottimate/apis/api-reference/changes/catalog/allowances/post.md)

---

[API](https://skmtc.dev/ottimate/apis/api-reference.md) · [All operations](https://skmtc.dev/ottimate/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ottimate/api-reference/revisions/ba91ff4c6969/schema)