Apply a promotion code to your subscription

Applies a promotion code the brand published to the signed-in customer's subscription: its coupon becomes a discount of the subscription from now, for the coupon's duration. The code's own rules apply: it must be active and unexpired with redemptions left, and meet its restrictions (this customer only, first-time customers only, a minimum amount). Not while a cancellation is scheduled. Customer portal only (portal:write).

At a glance

REST: POST /api/v1/portal/me/subscriptions/{subscriptionId}/promotion_code
MCP tool: portal_subscriptions_apply_promotion_code
Operation ID: portal.subscriptions.apply_promotion_code
Scope: Brand
Permission: portal:write
Risk tier: financial
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: A customer signed in to the customer portal (API keys can't call it)
Since: M9

Request

Path parameters

Field	Type	Description
`subscriptionId`	`sub_…` ID	One of your subscriptions (`sub_…`).

Body

A JSON object (Content-Type: application/json):

Field	Type	Required	Description
`promotionCode`	string	Yes	A promotion code as the customer typed it (case doesn't matter).

Response

200 OK with a JSON object:

Field	Type	Description
`id`	`sub_…` ID
`object`	`"portal_subscription"`
`status`	one of `incomplete`, `incomplete_expired`, `trialing`, `active`, `past_due`, `unpaid`, `paused`, `canceled`
`currency`	string
`items`	array of object
`items[].priceId`	`price_…` ID
`items[].productId`	`prod_…` ID
`items[].productName`	string
`items[].priceName`	string or null	The price's nickname, e.g. “Pro, monthly”.
`items[].interval`	object
`items[].interval.interval`	one of `day`, `week`, `month`, `year`
`items[].interval.intervalCount`	integer
`items[].usageType`	one of `licensed`, `metered`
`items[].unitAmount`	money or null	A per-unit price's amount per unit and period (null for tiered and metered prices).
`items[].taxBehavior`	one of `inclusive`, `exclusive`	`exclusive`: tax is added on the invoice.
`items[].id`	`si_…` ID
`items[].quantity`	integer
`items[].amount`	money or null	The item's full-period amount at its quantity, before discounts (null for metered items).
`collectionMethod`	one of `charge_automatically`, `send_invoice`	`charge_automatically` (your card is charged) or `send_invoice` (paid by bank transfer).
`paymentMethodId`	`pm_…` ID or null	The card this subscription charges (null: your default card).
`currentPeriodStart`	date-time
`currentPeriodEnd`	date-time
`trialEnd`	date-time or null
`cancelAtPeriodEnd`	boolean
`cancelAt`	date-time or null
`canceledAt`	date-time or null
`endedAt`	date-time or null
`cancellation`	object or null
`discounts`	array of object
`discounts[].id`	`disc_…` ID
`discounts[].name`	string	The coupon's name.
`discounts[].percentOffPpm`	string or null	Parts per million as a string (20% = "200000").
`discounts[].amountOff`	money or null
`discounts[].start`	date-time
`discounts[].end`	date-time or null	When it stops applying (null: for as long as the subscription runs).
`scheduledChange`	object or null	A change that applies at `effectiveAt` (a downgrade waits for the period end).
`actions`	object	What you can do with this subscription now, as the brand's portal settings allow.
`actions.switch_plan`	boolean
`actions.change_quantity`	boolean
`actions.apply_promotion_code`	boolean
`actions.cancel`	boolean
`actions.reactivate`	boolean
`actions.change_payment_method`	boolean
`cancelBehavior`	one of `period_end`, `immediate`	How cancelling here ends the subscription.
`collectCancelReason`	boolean	Cancelling asks why (optional answers).
`version`	integer	Send it back as `expectedVersion` to change what you saw.
`createdAt`	date-time

Examples

20% off for three months

HTTP

POST /api/v1/portal/me/subscriptions/sub_01m4tx5nj8emwbyf7y9vcf48c0/promotion_code
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "promotionCode": "AUTUMN20"
}

Response (200):

JSON

{
  "id": "sub_01m4tx5nj8emwbyf7y9vcf48c0",
  "object": "portal_subscription",
  "status": "active",
  "currency": "EUR",
  "items": [
    {
      "priceId": "price_01m4tx5nj8emwbyf7y9vcf48c2",
      "productId": "prod_01m4tx5nj8emwbyf7y9vcf48c4",
      "productName": "Genno Plus",
      "priceName": "Plus, monthly",
      "interval": {
        "interval": "month",
        "intervalCount": 1
      },
      "usageType": "licensed",
      "unitAmount": {
        "amount": "9000000",
        "currency": "EUR"
      },
      "taxBehavior": "inclusive",
      "id": "si_01m4tx5nj8emwbyf7y9vcf48c1",
      "quantity": 1,
      "amount": {
        "amount": "9000000",
        "currency": "EUR"
      }
    }
  ],
  "collectionMethod": "charge_automatically",
  "paymentMethodId": null,
  "currentPeriodStart": "2026-10-20T09:00:00.000Z",
  "currentPeriodEnd": "2026-11-20T10:00:00.000Z",
  "trialEnd": null,
  "cancelAtPeriodEnd": false,
  "cancelAt": null,
  "canceledAt": null,
  "endedAt": null,
  "cancellation": null,
  "discounts": [
    {
      "id": "disc_01m4tx5nj8emwbyf7y9vcf48c6",
      "name": "Autumn 20%",
      "percentOffPpm": "200000",
      "amountOff": null,
      "start": "2026-11-05T09:30:00.000Z",
      "end": "2027-02-20T10:00:00.000Z"
    }
  ],
  "scheduledChange": null,
  "actions": {
    "switch_plan": true,
    "change_quantity": false,
    "apply_promotion_code": true,
    "cancel": true,
    "reactivate": false,
    "change_payment_method": true
  },
  "cancelBehavior": "period_end",
  "collectCancelReason": true,
  "version": 5,
  "createdAt": "2026-09-20T09:00:00.000Z"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	The code is empty or too long.	Fix the fields listed in `details.issues` and send the request again.
`resource_not_found`	404	You have no such subscription (another customer's reads the same), or the brand has no such code (`param: promotionCode`).	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`portal_action_not_allowed`	403	The brand's portal settings or the subscription's state don't allow promotion codes now (a cancellation is scheduled, or the subscription can't change) (`details.action`).	The brand's portal settings don't allow it for this subscription now (`details.action`): contact the brand.
`promotion_code_not_redeemable`	409	The code is archived, has expired or is used up, is for another customer or first-time customers only, or the plan doesn't reach its minimum (`details.reason`).	Check `details.reason` and tell the customer: the code may have expired, be used up, belong to another customer, need a larger purchase or be for first-time customers only.
`discount_already_applied`	409	This code's coupon already applies to the subscription.	End the existing discount first (`discounts.delete`), or apply a different coupon. The same coupon doesn't stack with itself.
`subscription_status_invalid`	409	The subscription can't change in its status.	Check `details.status`: items change only while trialing, active or past due; pausing needs an active subscription and resuming a paused one; reactivating needs a cancellation scheduled for the period end; canceled and expired subscriptions don't change.
`livemode_not_allowed`	403	The portal session is in the other mode than the request.	Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin.
`permission_denied`	403	The caller isn't a customer signed in to this brand's portal (operators and API keys use the subscription and wallet operations).	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, scope_required, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

20% off for three months#

Errors#