---
title: "Record a change"
method: POST
path: "/sites/{site}/changes"
tags: ["Changes"]
---

# Record a change

`POST /sites/{site}/changes`

## Request

- Base URL: `https://api.onelence.com/v1`
- URL: `https://api.onelence.com/v1/sites/{site}/changes`
- Auth: one of:
  - OAuth 2 (authorization code, authorization URL `https://api.onelence.com/oauth/authorize`, token URL `https://api.onelence.com/oauth/token`, scopes: `workspace:write`)
  - HTTP bearer

Records a change the team made outside OneLence (budget, offer, pricing, tracking, creative, campaign, partner, email, social post, launch, or offline activity such as a TV or radio ad, billboard, influencer campaign, press coverage or event), on one source or the whole site, so OneLence can observe the period after it. Offline activity is recorded on the whole site only. Optional ends_on, image_url, link_url and markets are stored with the change when they are sent. It changes nothing on ad platforms.

## Path parameters

- `site` string, required

## Query parameters

- `dry_run` boolean

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `label` string, required: What changed, in a few words, e.g. "Raised the TikTok budget".
  - `occurred_on` string, required: Local date of the change (YYYY-MM-DD).
  - `time` string: Local time (HH:MM). Default 12:00.
  - `timezone` string, required: IANA time zone, e.g. Europe/Rome.
  - `source_id` string: The source it was made on (from the sources list). Without it, the whole site.
  - `family` 'budget_change' | 'campaign_change' | 'creative_change' | 'partner_change' | 'email_campaign' | 'social_post' | 'pricing_change' | 'offer_change' | 'tracking_change' | 'site_launch' | 'tv_radio_ad' | 'outdoor_ad' | 'influencer_campaign' | 'press_coverage' | 'event_sponsorship' | 'other'
  - `ends_on` string: Last local date the change ran through (YYYY-MM-DD), from the start date through 730 days after it.
  - `image_url` string: https address of a picture, at most 2048 characters, without a username or password.
  - `link_url` string: https address for the change, at most 2048 characters, without a username or password.
  - `markets` string[]: One to 30 different two-letter country codes, such as IT or DE.
  - `quantified_change` object
    - `metric` 'commission_rate' | 'budget' | 'spend_cap' | 'price' | 'discount_rate' | 'other', required
    - `metric_label` string: Required when metric is other.
    - `change` 'from_to' | 'set_to' | 'delta', required
    - `before` string
    - `after` string
    - `delta` string
    - `unit` 'currency' | 'percent_rate' | 'percentage_points' | 'relative_percent' | 'count', required
    - `currency` string: ISO code, for unit currency.
    - `period` 'day' | 'week' | 'month'
  - `note` string

## Response `200`

With dry_run=true: what would change. Nothing is applied.

- Preview
  - `object` 'preview', required
  - `capability` string, required
  - `summary` object, required
    - `title` string, required
    - `details` string[], required

## Other responses

- `201`: Success.
- `400`: Invalid input; `error.param` names the field.
- `401`: Missing, expired or revoked token. WWW-Authenticate points to the resource metadata.
- `402`: subscription_required or upgrade_required; the error carries billing_url.
- `403`: insufficient_scope or admin_required.
- `404`: Unknown endpoint, site, source or record.
- `409`: A request with this Idempotency-Key is still running.
- `422`: This Idempotency-Key was already used for a different request.
- `429`: Rate limited. Retry after Retry-After seconds.
- `500`: OneLence could not complete the request.

---

[API](https://skmtc.dev/onelence/apis/onelence-api.md) · [All operations](https://skmtc.dev/onelence/apis/onelence-api/llms.txt) · [OpenAPI document](https://skmtc.dev/onelence/apis/onelence-api/revisions/971c72fe9a42?raw)