Skip to main content

Create Cost Allocation

POST 
/api/cost-allocations

Creates a single cost allocation directly, assigning part (or all) of a cost entry's amount to a target entity. This is the low-level create: the caller supplies both currency amounts and the proration metadata explicitly. For most integrations the allocate endpoints under /api/cost-entries/{cost_entry}/allocate/... are simpler - they compute the account-currency amount and proration weights automatically.

Required scope: purchase-orders:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Fields:

  • cost_entry_id (required, integer): ID of the cost entry to allocate from. Unknown IDs return 404.
  • allocatable_type (required, string): fully qualified target type. One of: App\Models\Product, App\Models\ProductBrand, App\Models\Supplier, App\Models\SalesChannel, App\Models\SalesOrderLine.
  • allocatable_id (required, integer): ID of the target entity.
  • allocation_date (required, date YYYY-MM-DD): ledger date of the allocation.
  • amount (required, number): amount to allocate, in the cost entry's currency.
  • amount_in_tenant_currency (required, number): the same amount expressed in the account currency.
  • proration_strategy (required, string): one of revenue_based, cost_based, weight_based, volume_based, quantity_based, specific_line, manual. Use manual for a direct allocation.
  • period_start, period_end (optional, date YYYY-MM-DD): the period the cost applies to.
  • proration_weight (optional, number): the weight used when the allocation is part of a prorated distribution.
  • amortization_period_id (optional, integer): links the allocation to an amortization period. Leave null for manual allocations - amortization-linked allocations are normally created by the amortization processor.

The allocated amount is validated against the cost entry's remaining unallocated amount (taking into account amounts reserved by a pending amortization schedule); exceeding it returns 422. Creating an allocation also recalculates the parent cost entry's allocation status (pending_allocation, partially_allocated or allocated).

Note that this endpoint returns HTTP 200 (not 201) on success.

Authentication: Requires Bearer token. Scope: purchase-orders (read/write).

Request​

Responses​

OK

Response Headers
    Content-Type