> ## Documentation Index
> Fetch the complete documentation index at: https://docs.affonso.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Campaign

> Create a draft program campaign, including retainer rewards

Create a draft campaign for your team. Status is always `DRAFT` on create. Requires `write:program`.

Reward type rules:

* `flat_rate` requires `reward_amount`
* `range` requires `reward_amount_min` and `reward_amount_max` (min >= 0.01, max >= min)
* `custom` sets no amounts
* `retainer` requires `reward_amount`, `retainer_interval`, and either `retainer_day_of_month` (monthly) or `retainer_weekday` (weekly). For retainer, omitted `application_required` is set to `true`; sending `false` returns `VALIDATION_ERROR` ("Retainer campaigns require an application"). Ignores `max_budget` (stored as `null`)

## Body Parameters

**name** `string` *required*

Campaign title. Must be between 1 and 255 characters.

**reward\_type** `string` *required*

Reward type. Valid values: `flat_rate`, `custom`, `range`, `retainer`.

**start\_date** `string` *required*

Campaign start datetime (ISO 8601).

**description** `string | null`

Campaign description. Maximum 10,000 characters. Set to `null` or omit for none.

**reward\_amount** `number | null`

Fixed reward amount in program currency. Required for `flat_rate` and `retainer`. Minimum 0.01. Null for `custom` and `range`.

**reward\_amount\_min** `number | null`

Range minimum. Required when `reward_type` is `range`. Minimum 0.01.

**reward\_amount\_max** `number | null`

Range maximum. Required when `reward_type` is `range`. Must be greater than or equal to `reward_amount_min`.

**max\_budget** `number | null`

Owner-only cap on approved reward spend. Null or omit for no cap. Partners never see this. Ignored on retainer (stored as `null`).

**retainer\_interval** `string | null`

Required when `reward_type` is `retainer`. Valid values: `monthly`, `weekly`.

**retainer\_day\_of\_month** `integer | string | null`

Monthly retainer day. Valid values: integer `1`-`28`, or `"last"`. Required when `retainer_interval` is `monthly`.

**retainer\_weekday** `string | null`

Weekly retainer weekday. Valid values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. Required when `retainer_interval` is `weekly`.

**end\_date** `string | null`

Campaign end datetime (ISO 8601). Set to `null` or omit for open-ended.

**application\_required** `boolean`

When true, affiliates must apply and be accepted before submitting proof. For retainer, omitted `application_required` is set to `true`; sending `false` returns `VALIDATION_ERROR` ("Retainer campaigns require an application").

**application\_prompt** `string | null`

Question shown to affiliates when they apply. Maximum 10,000 characters.

**max\_submissions\_per\_user** `integer | null`

Maximum approved submissions per affiliate. Integer >= 1, or `null` for no limit.

## Response

Returns the created campaign object (HTTP 201).

**success** `boolean`

Always `true` for successful responses

**data** `object`

The created campaign.

**Data Object Properties**

**id** `string`

Encoded campaign id

**name** `string`

Campaign title

**description** `string | null`

Campaign description

**kind** `string`

Always `"submission"`

**status** `string`

Campaign status. On create this is `"DRAFT"`. Valid values: `DRAFT`, `SCHEDULED`, `ACTIVE`, `ENDED`, `ARCHIVED`.

**reward\_type** `string`

`flat_rate`, `custom`, `range`, or `retainer`

**reward\_amount** `number | null`

Fixed reward amount

**reward\_amount\_min** `number | null`

Range minimum

**reward\_amount\_max** `number | null`

Range maximum

**max\_budget** `number | null`

Owner-only spend cap. Null means no cap. Always null on retainer.

**retainer\_interval** `string | null`

`monthly` or `weekly` for retainer campaigns, otherwise `null`

**retainer\_day\_of\_month** `integer | string | null`

`1`-`28` or `"last"` for monthly retainers, otherwise `null`

**retainer\_weekday** `string | null`

Weekday for weekly retainers, otherwise `null`

**retainer\_schedule\_changed\_at** `string | null`

ISO 8601 timestamp of the last retainer schedule change, or `null`

**retainer\_resumed\_at** `string | null`

ISO 8601 timestamp set only when a retainer campaign moves from ENDED or ARCHIVED to ACTIVE, or `null`

**start\_date** `string`

ISO 8601 start datetime

**end\_date** `string | null`

ISO 8601 end datetime, or `null`

**application\_required** `boolean`

Whether affiliates must apply before submitting proof

**application\_prompt** `string | null`

Application question text

**max\_submissions\_per\_user** `integer | null`

Per-affiliate submission cap

**created\_at** `string`

ISO 8601 creation timestamp

**updated\_at** `string`

ISO 8601 update timestamp

```bash cURL (retainer monthly) theme={null}
curl -X POST "https://api.affonso.io/v1/program/campaigns" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Creator Retainer",
    "description": "Monthly content retainer",
    "reward_type": "retainer",
    "reward_amount": 500,
    "retainer_interval": "monthly",
    "retainer_day_of_month": 1,
    "start_date": "2026-11-01T00:00:00.000Z",
    "application_prompt": "Share your content plan and audience size"
  }'
```

```bash cURL (retainer weekly) theme={null}
curl -X POST "https://api.affonso.io/v1/program/campaigns" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Shorts Retainer",
    "reward_type": "retainer",
    "reward_amount": 150,
    "retainer_interval": "weekly",
    "retainer_weekday": "monday",
    "start_date": "2026-11-03T00:00:00.000Z"
  }'
```

```bash cURL (flat rate) theme={null}
curl -X POST "https://api.affonso.io/v1/program/campaigns" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Launch Review Bounty",
    "reward_type": "flat_rate",
    "reward_amount": 100,
    "max_budget": 2000,
    "start_date": "2026-11-01T00:00:00.000Z",
    "application_required": true,
    "application_prompt": "Link your review draft"
  }'
```

```json Response (201) theme={null}
{
  "success": true,
  "data": {
    "id": "cmretainer01camp0001",
    "name": "Creator Retainer",
    "description": "Monthly content retainer",
    "kind": "submission",
    "status": "DRAFT",
    "reward_type": "retainer",
    "reward_amount": 500,
    "reward_amount_min": null,
    "reward_amount_max": null,
    "max_budget": null,
    "retainer_interval": "monthly",
    "retainer_day_of_month": 1,
    "retainer_weekday": null,
    "retainer_schedule_changed_at": null,
    "retainer_resumed_at": null,
    "start_date": "2026-11-01T00:00:00.000Z",
    "end_date": null,
    "application_required": true,
    "application_prompt": "Share your content plan and audience size",
    "max_submissions_per_user": null,
    "created_at": "2026-10-12T14:30:00.000Z",
    "updated_at": "2026-10-12T14:30:00.000Z"
  }
}
```

## Notes

* Requires `write:program`.
* Retainer campaigns always require applications. For retainer, omitted `application_required` is set to `true`; sending `false` returns `VALIDATION_ERROR` ("Retainer campaigns require an application").
* `max_budget` is ignored for retainer and stored as `null`.
* Campaign IDs are encoded, same as marketplace campaign IDs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.