Manage Affiliate Promo Codes with MCP

Use the affiliate_promo_codes tool to assign an existing Stripe promotion code or create one for a specific affiliate. No campaign discount default is required. Stripe controls the customer discount; the affiliate’s campaign controls commission terms.

Open Settings → AI Connectors in AffiliateBase.
Enter a token name and expiry, select Allow promo-code management, then choose Create token.
Copy the token immediately; it is shown only once.
Copy the MCP client config into a compatible remote HTTP MCP client and replace its token placeholder with your new token.

The endpoint is https://app.affiliatebase.io/mcp. The client sends Authorization: Bearer <connector_token> and X-Account-Id: <account_id>. See AI Connectors and MCP for the complete config.

Existing tokens keep their current permissions. To enable promo-code management, create a new token with the option selected and update your client’s connection.

Actions	Required permission
`list`, `search`, `discounts`	`mcp.affiliate_coupons.read`
`assign`, `create`, `refresh`, `stop`, including previews	`mcp.affiliate_coupons.write`

The checkbox grants both permissions. REST API permissions use the separate v1.affiliate_coupons.read / v1.affiliate_coupons.write names.

Find the affiliate and code

Use list_affiliates to find the intended affiliate ID. Stripe operations require an active affiliate in an active campaign and a working connection to the Stripe account containing the code or discount.

The following JSON objects are arguments for the affiliate_promo_codes tool, not standalone HTTP request bodies. Replace example IDs with IDs returned for your account.

Search for an existing code:

{
  "affiliate_id": "<affiliate_id>",
  "action": "search",
  "code": "JAMIE-20"
}

Read the matching entry in candidates. Its id is the Stripe promotion-code ID to use as stripe_promotion_code_id. Review the discount, restrictions, expiry, account, mode and already_assigned status. Code text alone is not an assignment identifier.

Preview and assign an existing code

Preview without saving:

{
  "affiliate_id": "<affiliate_id>",
  "action": "assign",
  "stripe_promotion_code_id": "promo_EXAMPLE",
  "dry_run": true
}

After reviewing the preview, execute with the same affiliate and promotion-code IDs and a unique idempotency key for this operation:

{
  "affiliate_id": "<affiliate_id>",
  "action": "assign",
  "stripe_promotion_code_id": "promo_EXAMPLE",
  "dry_run": false,
  "idempotency_key": "assign-example-20260908-01"
}

Assignment saves the association in AffiliateBase without changing Stripe. It applies to new qualifying redemptions after assignment; earlier redemptions are not imported as historical sales. A code cannot be transferred to another affiliate or reactivated after stopping.

Preview and create a new code

First list available Stripe discounts:

{
  "affiliate_id": "<affiliate_id>",
  "action": "discounts"
}

Use a returned discount’s id as stripe_coupon_id. Preview the proposed code:

{
  "affiliate_id": "<affiliate_id>",
  "action": "create",
  "code": "JAMIE-NEW",
  "stripe_coupon_id": "<stripe_coupon_id>",
  "dry_run": true
}

After reviewing the code and discount, create and assign it:

{
  "affiliate_id": "<affiliate_id>",
  "action": "create",
  "code": "JAMIE-NEW",
  "stripe_coupon_id": "<stripe_coupon_id>",
  "dry_run": false,
  "idempotency_key": "create-example-20260908-01"
}

This creates a promotion code in the connected Stripe account and assigns it locally. The code uses an existing discount; it does not create a new underlying discount. Code text accepts 1–500 letters, numbers or dashes and is preserved. If the code already exists, use the search and assignment flow.

Read, refresh or stop an assignment

List up to 100 recent assignments, including stopped assignments:

{
  "affiliate_id": "<affiliate_id>",
  "action": "list"
}

For refresh and stop, use the returned AffiliateBase assignment id, not the Stripe promo_... ID. Preview a refresh:

{
  "affiliate_id": "<affiliate_id>",
  "action": "refresh",
  "id": "<assignment_id>",
  "dry_run": true
}

Repeat with dry_run: false to save the latest Stripe availability. Refreshing does not verify a payment.

Preview stopping attribution:

{
  "affiliate_id": "<affiliate_id>",
  "action": "stop",
  "id": "<assignment_id>",
  "dry_run": true
}

Repeat with dry_run: false to stop tracking new redemptions and remove the code from the affiliate’s shareable list. History and established customer commission rules remain. Stopping is local and keeps the code redeemable in Stripe; it remains available if Stripe is disconnected.

Responses and retries

Check structuredContent.ok. Failed calls contain error.code and error.message; successful assignment or creation returns the assignment id, display code, Stripe IDs, mode and provider status. Show customers code; tracking_token is an opaque compatibility identifier.

Writes default to dry_run: true. Assignment and creation require a nonblank idempotency key of at most 200 characters when executing. Use a new key for each intended operation and keep that same key and payload for retries.

Uncertain response or OPERATION_PENDING: retry the original call with the same key and payload. A completed operation returns the existing assignment rather than creating another code.
RECONCILIATION_REQUIRED: stop and review the original operation before another creation attempt. Do not switch keys to bypass the error.
IDEMPOTENCY_CONFLICT: the key was already used with different inputs. Check the original request before starting a separate operation.
forbidden: check the connector permissions. Previews of write actions also require write permission.
STRIPE_DISCONNECTED or STRIPE_IDENTITY_UNKNOWN: open Settings → Reconnect Stripe, complete the correct account connection, then retry. Replacing the MCP token alone does not reconnect Stripe.
CODE_EXISTS, unavailable or customer-restricted codes: search the existing code or select an active code that can be shared publicly.

Verify attribution

A successful assignment confirms configuration. Verify a qualifying paid checkout that actually redeems the assigned Stripe promotion code, then confirm its referral, sale and commission in AffiliateBase. Code text placed in metadata alone does not prove redemption. An individually assigned code on a zero-value invoice can establish a referral without a monetary commission; a later paid renewal can qualify under the campaign rules.

Use the connected Stripe account and mode. A test-mode connection is appropriate for test payments; with a live-mode connection, verify during the next appropriate checkout rather than creating a live charge just to complete setup.

Connect with promo-code permissions