> ## 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. # Campaign Tools > MCP tools for program campaigns, applications, submissions, and retainers ## Overview Campaign tools manage your team's program campaigns through natural language. They mirror REST `/v1/program/campaigns`, including retainer create/update, application accept with conditions, and period approve/reject. All tools support `response_format` (`markdown` or `json`). `responseFormat` is accepted as an alias. List tools use `limit` and `offset`, not `page`. > [!NOTE] > > Campaign create/update/list/get use `read:program` / `write:program`. Application, submission, and retainer period actions use `read:affiliates` / `write:affiliates`. See permissions below. ## Available Tools | Tool | Description | Permission | | - | - | - | | `affonso_list_campaigns` | List team campaigns (reward type, retainer fields, owner max\_budget) | `read:program` | | `affonso_get_campaign` | Get one team campaign by encoded id | `read:program` | | `affonso_create_campaign` | Create a draft campaign, including retainer | `write:program` | | `affonso_update_campaign` | Update application, reward, retainer, status, and/or max\_budget | `write:program` | | `affonso_apply_to_campaign` | Submit an application for an affiliate on your team | `write:affiliates` | | `affonso_list_campaign_applications` | List applications for one campaign | `read:affiliates` | | `affonso_accept_campaign_application` | Accept a pending application (retainer requires has\_condition) | `write:affiliates` | | `affonso_reject_campaign_application` | Reject a pending application | `write:affiliates` | | `affonso_approve_campaign_submission` | Approve a pending submission (custom/range need amount) | `write:affiliates` | | `affonso_update_retainer_condition` | Change the retainer condition on an accepted application | `write:affiliates` | | `affonso_end_campaign_retainer` | End a partner retainer (no new periods) | `write:affiliates` | | `affonso_resume_campaign_retainer` | Resume an ended partner retainer | `write:affiliates` | | `affonso_list_campaign_retainer_periods` | List PENDING\_MANUAL\_APPROVAL retainer periods | `read:affiliates` | | `affonso_approve_campaign_retainer_period` | Approve a period earning to READY\_FOR\_PAYMENT | `write:affiliates` | | `affonso_reject_campaign_retainer_period` | Reject a period earning to DECLINED | `write:affiliates` | *** ## affonso\_create\_campaign Create a draft program campaign. Same as `POST /v1/program/campaigns`. 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`. ### Parameters **name** `string` *required* Campaign title (1-255 characters) **reward\_type** `string` *required* `flat_rate`, `custom`, `range`, or `retainer` **start\_date** `string` *required* ISO start datetime **description** `string | null` Campaign description (max 10,000 characters) **reward\_amount** `number | null` Flat rate / retainer amount (min 0.01). Null for custom and range. **reward\_amount\_min** `number | null` Range minimum. Required when reward\_type is range. **reward\_amount\_max** `number | null` Range maximum. Must be >= reward\_amount\_min. **max\_budget** `number | null` Owner-only spend cap. Null or omit for no cap. Ignored on retainer. **retainer\_interval** `string | null` Required for retainer: `monthly` or `weekly` **retainer\_day\_of\_month** `integer | string | null` Monthly day: 1-28 or `last` **retainer\_weekday** `string | null` Weekly weekday: monday through sunday **end\_date** `string | null` ISO end datetime **application\_required** `boolean` Whether affiliates must apply first. For retainer, omitted `application_required` is set to `true`; sending `false` returns `VALIDATION_ERROR` ("Retainer campaigns require an application"). **application\_prompt** `string | null` Application question text **max\_submissions\_per\_user** `integer | null` Per-affiliate submission cap (>= 1), or null **response\_format** `string` (default: markdown) Response format: `markdown` or `json`. Also accepted as `responseFormat`. ### Example Prompts ``` Create a monthly retainer campaign named Creator Retainer for 500 on the 1st Add a weekly retainer for 150 every Monday Create a flat rate campaign Launch Review Bounty for 100 with max budget 2000 ``` *** ## affonso\_update\_campaign Update application settings, reward type, retainer cadence, status, and/or owner max\_budget. Same as `PATCH /v1/program/campaigns/{id}`. Does not create earnings. Switching to or from retainer is blocked when applications exist. Only moving a retainer campaign from `ENDED` or `ARCHIVED` to `ACTIVE` sets `retainer_resumed_at`. Retainer ignores `max_budget`. For retainer, omitted `application_required` is set to `true`; sending `false` returns `VALIDATION_ERROR` ("Retainer campaigns require an application"). ### Parameters **campaign\_id** `string` *required* Encoded campaign id **application\_required** `boolean` Whether affiliates must apply before submitting proof **application\_prompt** `string | null` Application question text **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` Set, change, or clear (null) the owner-only spend cap. Ignored on retainer. **retainer\_interval** `string | null` `monthly` or `weekly` **retainer\_day\_of\_month** `integer | string | null` 1-28 or `last` **retainer\_weekday** `string | null` monday through sunday **status** `string` `DRAFT`, `SCHEDULED`, `ACTIVE`, `ENDED`, or `ARCHIVED` **response\_format** `string` (default: markdown) Response format: `markdown` or `json`. Also accepted as `responseFormat`. ### Example Prompts ``` Update campaign cmretainer01camp0001 to pay on the last day of the month Set campaign cmretainer01camp0001 status to ACTIVE Change retainer reward amount to 600 on campaign cmretainer01camp0001 ``` *** ## affonso\_accept\_campaign\_application Accept a pending campaign application. Assignment only: no earnings and no budget reserve. Same as `POST /v1/program/campaigns/{id}/applications/{applicationId}/accept`. Retainer requires `has_condition` (`true` or `false`). When true, `condition` is required (max 2000 characters). ### Parameters **campaign\_id** `string` *required* Encoded campaign id **application\_id** `string` *required* Encoded application id **has\_condition** `boolean` Retainer only. Required true or false. Choose whether this retainer has a condition. **condition** `string | null` Retainer only. Required when has\_condition is true. Max 2000 characters. **response\_format** `string` (default: markdown) Response format: `markdown` or `json`. Also accepted as `responseFormat`. ### Example Prompts ``` Accept application cmapp01retainer0001 on campaign cmretainer01camp0001 with condition "Post at least 2 Shorts per week mentioning our product" Accept retainer application cmapp01retainer0002 with has_condition false ``` *** ## affonso\_update\_retainer\_condition Change the retainer condition on an accepted application. Requires `has_condition`. Same as `PATCH /v1/program/campaigns/{id}/applications/{applicationId}/condition`. ### Parameters **campaign\_id** `string` *required* Encoded campaign id **application\_id** `string` *required* Encoded application id **has\_condition** `boolean` *required* True to keep or set a condition. False clears it. **condition** `string | null` Condition text. Required when has\_condition is true. Max 2000 characters. **response\_format** `string` (default: markdown) Response format: `markdown` or `json`. Also accepted as `responseFormat`. ### Example Prompts ``` Update retainer condition on application cmapp01retainer0001 to "Post at least 3 Shorts per week mentioning our product" Clear the retainer condition on application cmapp01retainer0001 ``` *** ## affonso\_end\_campaign\_retainer End a partner retainer. No new periods are created for that application. Same as `POST /v1/program/campaigns/{id}/applications/{applicationId}/end-retainer`. ### Parameters **campaign\_id** `string` *required* Encoded campaign id **application\_id** `string` *required* Encoded application id **response\_format** `string` (default: markdown) Response format: `markdown` or `json`. Also accepted as `responseFormat`. ### Example Prompts ``` End the retainer for application cmapp01retainer0001 on campaign cmretainer01camp0001 Stop new retainer periods for partner application cmapp01retainer0001 ``` *** ## affonso\_resume\_campaign\_retainer Resume an ended partner retainer. Same as `POST /v1/program/campaigns/{id}/applications/{applicationId}/resume-retainer`. ### Parameters **campaign\_id** `string` *required* Encoded campaign id **application\_id** `string` *required* Encoded application id **response\_format** `string` (default: markdown) Response format: `markdown` or `json`. Also accepted as `responseFormat`. ### Example Prompts ``` Resume the retainer for application cmapp01retainer0001 Restart partner retainer periods on campaign cmretainer01camp0001 for application cmapp01retainer0001 ``` *** ## affonso\_list\_campaign\_retainer\_periods List open retainer periods waiting for manual approval. Same as `GET /v1/program/campaigns/{id}/retainer-periods`. ### Parameters **campaign\_id** `string` *required* Encoded campaign id **limit** `number` (default: 20) Number of results to return **offset** `number` (default: 0) Number of results to skip **response\_format** `string` (default: markdown) Response format: `markdown` or `json`. Also accepted as `responseFormat`. ### Example Prompts ``` List open retainer periods for campaign cmretainer01camp0001 Show PENDING_MANUAL_APPROVAL retainer periods on my Creator Retainer campaign ``` ### Response Period objects include: `id`, `campaign_id`, `application_id`, `affiliate_id`, `period_start`, `amount`, `earning_id`, `earning_status`, `condition`, `created_at`. *** ## affonso\_approve\_campaign\_retainer\_period Approve a retainer period earning that is `PENDING_MANUAL_APPROVAL`. Writes `READY_FOR_PAYMENT`. Same as `POST /v1/program/campaigns/{id}/retainer-periods/{periodId}/approve`. ### Parameters **campaign\_id** `string` *required* Encoded campaign id **period\_id** `string` *required* Encoded retainer period id **response\_format** `string` (default: markdown) Response format: `markdown` or `json`. Also accepted as `responseFormat`. ### Example Prompts ``` Approve retainer period cmperiod01retainer001 on campaign cmretainer01camp0001 Mark period cmperiod01retainer001 as ready for payment ``` *** ## affonso\_reject\_campaign\_retainer\_period Reject a retainer period earning that is `PENDING_MANUAL_APPROVAL`. Writes `DECLINED`. Same as `POST /v1/program/campaigns/{id}/retainer-periods/{periodId}/reject`. ### Parameters **campaign\_id** `string` *required* Encoded campaign id **period\_id** `string` *required* Encoded retainer period id **response\_format** `string` (default: markdown) Response format: `markdown` or `json`. Also accepted as `responseFormat`. ### Example Prompts ``` Reject retainer period cmperiod01retainer001 Decline period cmperiod01retainer001 on campaign cmretainer01camp0001 ``` *** ## Other campaign tools These tools are part of the same campaigns surface and appear in the overview table: * `affonso_list_campaigns` / `affonso_get_campaign`: read team campaigns including retainer fields and owner `max_budget` * `affonso_apply_to_campaign`: body needs `campaign_id`, `affiliate_id`, and `answers` * `affonso_list_campaign_applications`: filter by status and affiliate; uses `limit` / `offset` * `affonso_reject_campaign_application`: pending applications only; affiliate may apply again * `affonso_approve_campaign_submission`: custom/range need `amount`; optional `reject_open_applications` on budget close; non-retainer approvals create one `CAMPAIGN_REWARD` earning in `READY_FOR_PAYMENT` and queue the partner approval email (respecting email settings). Repeated approvals create no new earning or email. Retainer proof creates no earning; periods are approved separately *** ## Error Handling Common errors you may encounter: | Error | Cause | Solution | | - | - | - | | `NOT_FOUND` | Campaign, application, or period id is missing or belongs to another team | Verify the encoded id | | `VALIDATION_ERROR` | Missing retainer fields, has\_condition, or invalid amounts | Check required parameters for the reward type | | `CONFLICT` | Wrong status (for example switching to retainer with applications, or approving a non-pending period) | Refresh state and retry with a valid transition | | `PERMISSION_DENIED` | Missing required scope | Check your API key permissions | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.