Upsert multiple cost entries in one call (e.g. daily spend per ad_id); an entry with the same link, breakdown, period and source updates the existing record

PUT

/api/v1/costs/bulk

curl --request PUT \
  --url https://example.com/api/v1/costs/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "records": [ { "linkId": "550e8400-e29b-41d4-a716-446655440000", "breakdownKey": "sub_id_2", "breakdownValue": "ad_12345", "periodStart": "2026-03-01", "periodEnd": "2026-03-01", "amount": 42.5, "currency": "USD", "source": "manual", "notes": "example" } ] }'

Authorizations

• bearer

Request Body^required

Media typeapplication/json

object

records

required

Cost entries to record in one go, e.g. a day worth of spend across ad_ids

Array<object>

object

linkId

Link this cost applies to. Omit for a workspace-wide (unallocated) cost.

string

Example

550e8400-e29b-41d4-a716-446655440000

breakdownKey

Breakdown dimension key, e.g. “sub_id_2”

string

<= 50 characters

Example

sub_id_2

breakdownValue

Breakdown dimension value, e.g. “ad_12345”

string

<= 255 characters

Example

ad_12345

periodStart

required

Period start (date)

string

Example

2026-03-01

periodEnd

required

Period end (date)

string

Example

2026-03-01

amount

required

number

Example

42.5

currency

string

default: USD <= 3 characters

Example

USD

source

string

default: manual

Allowed values: manual api

notes

string

<= 1000 characters

Responses

200

Media typeapplication/json

Array<object>

object

id

required

string

linkId

object

breakdownKey

object

breakdownValue

object

periodStart

required

string

periodEnd

required

string

amount

required

number

currency

required

string

source

required

string

notes

object

createdAt

required

string

updatedAt

required

string

Example ^generated

[
  {
    "id": "example",
    "linkId": {},
    "breakdownKey": {},
    "breakdownValue": {},
    "periodStart": "example",
    "periodEnd": "example",
    "amount": 1,
    "currency": "example",
    "source": "example",
    "notes": {},
    "createdAt": "example",
    "updatedAt": "example"
  }
]