Manage Affiliate Promo Codes with MCP

The affiliate_promo_codes tool in the AffiliateBase MCP server assigns an existing Stripe promotion code, or creates a new one, for a specific affiliate. This guide is for developers and AI-client users who call the tool through an MCP connector token. You do not need a campaign discount default. Stripe controls the customer discount, and 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 now. AffiliateBase shows it 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>. The X-Account-Id: <account_id> header is optional for connector tokens: when it is absent, AffiliateBase uses the token’s own account. If you send it, it must be the account the token belongs to, or the request is refused. 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.

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 affiliate ID. Stripe operations require an active affiliate in an active campaign and a working connection to the Stripe account that holds the code or discount.

The following JSON objects are arguments for the affiliate_promo_codes tool, not standalone HTTP request bodies. Replace the example IDs with IDs from 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 does not identify a code for assignment.

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 you review 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 qualifying redemptions from then on. AffiliateBase does not import earlier redemptions as historical sales. You cannot transfer a code to another affiliate or reactivate it after you stop it.

Preview and create a new code

First, list the 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 you review 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 in AffiliateBase. 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 kept as entered. 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. You can stop tracking even while Stripe is disconnected.

Responses, errors, and retries

Check structuredContent.ok. Failed calls contain error.code and error.message. A 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 operation, and reuse that 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 and choose Reconnect Stripe (or Connect Stripe if Stripe is not connected), 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.
HTTP 429: MCP requests are limited to 45 per 30 seconds per token and 180 per 30 seconds per IP address. Wait the number of seconds in Retry-After, then retry with the same key and payload.

Verify attribution

A successful assignment confirms configuration. Verify a qualifying paid checkout that redeems the assigned Stripe promotion code, then confirm its referral, sale, and commission in AffiliateBase. Code text 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. Use a test-mode connection for test payments. With a live-mode connection, verify during the next appropriate checkout instead of creating a live charge to complete setup.

Connect with promo-code permissions