# Ads

> Campaigns, ad sets, ads and daily results.

Source: https://www.onlucra.com/docs/api-ads

Run approved submissions as ads on the brand's own ad accounts, and see what each creator's work drives. Connect an ad account first with a [connection](https://www.onlucra.com/docs/api-connections).

## Create a campaign

A campaign runs on one Meta, TikTok, Google or Snapchat connection. Its `creatives` are approved submissions, and their creators earn what their [program pays](https://www.onlucra.com/docs/api-programs#pay). This one spends $50 a day:

```json
{
  "name": "Spring launch – Meta",
  "connection": "conn_02PEZI7pHWLT3UpakbRmfNB",
  "destination": { "type": "website", "value": "https://acme.com/spring" },
  "budget": { "daily": 5000 },
  "schedule": { "startDate": "2026-10-10" },
  "audience": { "countries": ["US"], "ageMin": 21 },
  "creatives": ["sub_14XA4WGiSOmaVI3B4QLm4Fs"],
  "ad": { "primaryText": "Made for spring.", "callToAction": "shop_now" }
}
```

Lucra sets the campaign up on the ad platform right away; it's `processing` until that's done. By default it then turns on. Send `"launch": false` to leave it `paused`, or `scheduledLaunchAt` to turn it on later.

Change its `status` to `live`, `paused` or `archived` with `PATCH /v1/campaigns/:id`. [Webhooks](https://www.onlucra.com/docs/webhooks) report when publishing finishes (`campaign.published`) or needs attention.

## How creators are credited

When creators earn a share of revenue or a fixed amount per lead, `attribution` sets what counts. `lucra` counts your [Lucra Pixel](https://www.onlucra.com/docs/tracking#conversions)'s matches of one conversion from each ad's link; `platform` counts what the ad platform reports. New campaigns default to `lucra` when your pixel is verified and the destination is a website:

```json
{ "attribution": { "source": "lucra", "conversion": "conv_1fK7pQ2wXy9LmN4bVc8RtZa" } }
```

Leave out `conversion` to use an active purchase (revenue share) or lead (per lead) conversion; Lucra creates one if you have none. It can't change once the campaign is on its ad platform. Ad-spend pay always counts the platform's spend.

## Ad defaults

`PATCH /v1/ad-defaults` sets what new campaigns start with: objective, Meta Advantage+ audience, naming and tracking.

## Tracking

`tracking` sets click tracking on a campaign: `urlParameters` on every platform, a Google `trackingUrlTemplate`, and TikTok click and impression trackers. You can change it on a live campaign.

Every ad's link also carries `lucra_id` (its video) and `lucra_campaign` (the campaign), which the Lucra Pixel reads; Lucra sets them, replacing any already in the URL.

## Boost an existing TikTok post

Run a post that's already on TikTok as a Spark Ad, with no upload. Add it to the brand's library with `POST /v1/submissions`, by the creator's Spark code, the post's full link, or both:

```json
{ "post": { "connection": "conn_02PEZI7pHWLT3UpakbRmfNB", "sparkCode": "#Abc123…" } }
```

With a code, the post is ready at once: its `existingPost.ready` is `true` and `existingPost.authorizedUntil` says when the code ends. Then put its `sub_` ID in a TikTok campaign's `creatives`, on the same connection. A campaign runs either existing posts or uploaded videos, and existing posts run only on TikTok.

With just a link, Lucra asks the creator for a code. The submission's `adAuthorization` is the request (`platform: "tiktok"`). Read it with `GET /v1/ad-authorizations/:id` for its `requestUrl`: send that link to the creator, who pastes their code there, with no Lucra account needed. A creator who connected that TikTok account to Lucra also gets the request in the app. When the code arrives, you get `ad_authorization.granted` and the post is ready. If the creator sends you the code instead, send it with `POST /v1/submissions` again, or `PATCH /v1/ad-authorizations/:id` with `{ "status": "granted", "sparkCode": "…" }`.

Three days before a code ends, Lucra asks the creator for a new one and sends `ad_authorization.requested`. An existing post never pays its creator through Lucra: it isn't part of a program.

## Ad sets and ads

`GET /v1/ad-sets` and `GET /v1/ads` list what's running. `PATCH` renames, pauses, resumes or archives them. Meta and TikTok ad sets also take `bidding` and `audience`, including saved audiences (`GET /v1/ad-audiences`) and interests (`GET /v1/ad-interests`). Copy a campaign, ad set or ad with `POST …/copies`.

## Ad fields

`GET /v1/ad-fields` lists every setting each platform takes, with the platform's own name and docs.

## Run as the creator

To run a submission as a Meta Partnership Ad under the creator's own account, request an authorization with `POST /v1/ad-authorizations`. The creator grants it, and you get `ad_authorization.granted`. On TikTok, a campaign with `identity: "creator"` runs under the creator's whole account, which they approve once to your Business Center; until they have, the campaign save answers 422 saying what's missing.

## Ads Lucra didn't launch

Lucra also reads back the other ads in each connected ad account: the last 90 days on the first 30-minute sync after the account connects, then on every sync like Lucra's own. List them with `GET /v1/ads?source=external`: each has `source: "external"`, its platform ID, and its campaign and ad set on the platform (`platformCampaign`, `platformAdSet`). They're read-only, and they're never billed, settled or paid out. Their `status` is `unknown`: Lucra reports their results, not their state.

## Analytics

`GET /v1/analytics` returns daily spend, revenue, clicks, conversions and `paidViews` between `from` and `to`. Paid views are each platform's own video view count: Meta's 3-second views, TikTok's video plays, Snapchat's 2-second views and Google's TrueView views. Split each day with `group`, by `campaign`, `submission`, `creator`, `ad` or `platform`. `source=external` reads the ads Lucra didn't launch instead, and `source=all` both:

```ts
const { data } = await lucra.analytics.retrieve({
  query: { from: "2026-10-01", to: "2026-10-07", group: "creator" },
})
```

## Endpoints

- `GET /v1/analytics` (read, SDK `lucra.analytics.retrieve`): Get daily ad results, or creators' organic results, optionally filtered and split by campaign, submission, creator, ad or platform; as a creator, your own work's ad results across brands
- `POST /v1/campaigns` (write, SDK `lucra.campaigns.create`): Create and launch a campaign
- `POST /v1/campaigns/:id/copies` (write, SDK `lucra.campaigns.copies.create`): Copy a campaign with its ad sets and ads, as a new campaign
- `GET /v1/campaigns` (read, SDK `lucra.campaigns.list`): List campaigns
- `GET /v1/campaigns/:id` (read, SDK `lucra.campaigns.retrieve`): Get a campaign
- `PATCH /v1/campaigns/:id` (write, SDK `lucra.campaigns.update`): Change a campaign, its ad sets' budgets, or its status: launch, pause, resume, retry or archive
- `GET /v1/ad-fields` (read, SDK `lucra.adFields.list`): List the settings each ad platform takes for campaigns, ad sets and ads
- `GET /v1/ad-defaults` (read, SDK `lucra.adDefaults.retrieve`): Get what the account's new campaigns start with
- `PATCH /v1/ad-defaults` (write, SDK `lucra.adDefaults.update`): Change what the account's new campaigns start with
- `GET /v1/ad-audiences` (read, SDK `lucra.adAudiences.list`): List an ad account's saved audiences (Meta custom and lookalike audiences, TikTok audiences)
- `GET /v1/ad-interests` (read, SDK `lucra.adInterests.list`): Search the interests an ad set can target on Meta or TikTok
- `GET /v1/ad-sets` (read, SDK `lucra.adSets.list`): List ad sets (Meta ad sets, TikTok and Google ad groups, Snapchat ad squads)
- `GET /v1/ad-sets/:id` (read, SDK `lucra.adSets.retrieve`): Get an ad set
- `PATCH /v1/ad-sets/:id` (write, SDK `lucra.adSets.update`): Rename, pause, resume, archive or re-budget an ad set on its platform
- `POST /v1/ad-sets/:id/copies` (write, SDK `lucra.adSets.copies.create`): Copy an ad set (and run it paused) in its campaign or another one
- `GET /v1/ads` (read, SDK `lucra.ads.list`): List ads: the ones Lucra launched, or with `source=external` the other ads in your connected ad accounts
- `GET /v1/ads/:id` (read, SDK `lucra.ads.retrieve`): Get an ad
- `PATCH /v1/ads/:id` (write, SDK `lucra.ads.update`): Rename, pause, resume or archive an ad on its platform
- `POST /v1/ads/:id/copies` (write, SDK `lucra.ads.copies.create`): Copy an ad (and run it paused) in its ad set or another one
- `GET /v1/ad-authorizations` (read, SDK `lucra.adAuthorizations.list`): List ad authorizations: a brand's requests, or, as a creator, the ones asked of you
- `GET /v1/ad-authorizations/:id` (read, SDK `lucra.adAuthorizations.retrieve`): Get an ad authorization
- `POST /v1/ad-authorizations` (write, SDK `lucra.adAuthorizations.create`): Ask a submission's creator to authorize it as a Meta partnership ad, or an existing TikTok post's creator for a Spark code
- `PATCH /v1/ad-authorizations/:id` (write, SDK `lucra.adAuthorizations.update`): Grant an ad authorization as its creator (on TikTok, with the post's Spark code), or revoke it