Admin API: spend

These methods power the Settings → Spend («Настройки → Расходы») tab and the spend extension. You can also use them to send the spend of an ad account to the tracker from your own integration. Authorization is described on the Admin API: overview and authorization page, and the response and error format on the Request, response and error format page.

Access and license

A spend:write token is created in the panel: Settings → Spend, the Connect profile («Подключить профиль») block, the Create key («Создать ключ») button. Such a key is valid for 90 days. A full token is created on the API tab — see Access types.

All four methods work only on a paid license. On a trial license they respond with code 403:

{"code": "spend_paid_required", "message": "Расширение для расходов доступно после оплаты лицензии."}

The message means “the spend extension is available after the license is paid for”. When the license is inactive, the response is 402, see Expired license.

Methods

Get the settings and the state of days

GET /api/v1/spend

Returns the spend settings and the state of the last 60 days for which snapshots arrived.

Token scope: spend:write or full. There are no parameters and no body.

Response — code 200:

The same data is shown in the table on the Spend tab — see Days table.

Example response:

{
  "settings": {"ad_key": "sub_id_4", "timezone": "Europe/Warsaw"},
  "jobs": [
    {
      "day": "2026-10-03",
      "pending": false,
      "error": "",
      "campaigns": 4,
      "unmatched_ads": 1,
      "unmatched_spend": 3.2,
      "updated_at": "2026-10-04T06:15:22.104512Z"
    }
  ]
}

Save the spend settings

PUT /api/v1/spend/settings

Sets the click field with the ad ID. In the panel, this is the Ad ID field («Поле с ID объявления») list. The time zone is not configured: each snapshot passes it.

Token scope: full.

Response — code 200 and the saved values:

{"ad_key": "sub_id_4", "timezone": "UTC"}

Errors:

Send a daily spend snapshot

POST /api/v1/spend/snapshots

Accepts the full spend of one ad account for one day: a list of ads and the amount for each of them.

Token scope: spend:write or full. The body is one JSON object up to 2 MiB in size. Fields that are not in the table cause a 422 error.

How the tracker processes a snapshot:

• A snapshot replaces the earlier data of this account for this day rather than adding to it. Send all of the account's ads, not only the ones that changed.
• Of two snapshots of the same account for the same day, the one with the later fetched_at is kept. A snapshot with an earlier time is not applied.
• The amount is converted to USD at the rate for the spend date. The rate is fixed for the account and day with the first snapshot — see Rate for extension spend. USD does not need a rate.
• An ad's spend is split between campaigns by the clicks with its ID in the settings.ad_key field — see How spend gets into reports.

Response — code 202: the snapshot is accepted, and the distribution across campaigns runs in the background. Check the result in jobs of the GET /api/v1/spend method.

Example request:

curl -X POST https://panel.example.com/api/v1/spend/snapshots \
  -H "Api-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "1234567890123456",
    "day": "2026-10-03",
    "currency": "PLN",
    "timezone": "Europe/Warsaw",
    "fetched_at": "2026-10-04T06:15:00Z",
    "rows": [
      {"ad_id": "120210000000000001", "spend": 182.4},
      {"ad_id": "120210000000000002", "spend": 57.15}
    ]
  }'

Example response:

{"accepted": true, "changed": true, "rows": 2}

Errors:

Repeating the same snapshot with the same fetched_at is safe: the tracker responds 202 with "changed": false.

Download the extension

GET /api/v1/spend/extension

Returns the spend extension archive built for the panel domain, name and logo of this installation. It is the same file that the button on the Spend tab downloads — see Facebook spend extension.

Token scope: full. There are no parameters and no body.

Response — code 200, type application/zip, file name micator-spend.zip.

Example request:

curl https://panel.example.com/api/v1/spend/extension \
  -H "Api-Key: <token>" \
  -o micator-spend.zip

Errors:

Uploading from your own integration

1. Save the settings with the PUT /api/v1/spend/settings method or on the Settings → Spend tab.
2. Send one POST /api/v1/spend/snapshots request for each “account — day” pair.
3. Request GET /api/v1/spend and wait until the day you need has "pending": false with an empty error.
4. If unmatched_ads is not zero, check that the link in the ad passes the ad ID in the settings.ad_key field — see Source tokens and link parameters.

To distribute the spend across clicks that arrived after the upload, send the snapshot of that day again with a new fetched_at.