Redeem a coupon

POST /v1/cowork/coupon/redeem

Redeems a Cowork/Code coupon and grants the user a complimentary tier for the term set by the coupon at the platform's expense, with no charge to the Bitrix24 account.

The user and the account come from the key binding; there are no path parameters. The operation is irreversible: a redemption cannot be undone.

Request fields (body)

Examples

This endpoint supports only one authorization method: a Cowork/Code desktop key. Personal keys and application keys receive 403 INSUFFICIENT_SCOPE or 403 COWORK_DESKTOP_KEY_REQUIRED.

curl — Cowork/Code desktop key

curl -X POST https://vibecode.bitrix24.com/v1/cowork/coupon/redeem \
  -H "X-Api-Key: YOUR_COWORK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "PRAKTIKUM-7HKM4TQZ2RVW-45C80C", "action": "force"}'

JavaScript — Cowork/Code desktop key

const res = await fetch('https://vibecode.bitrix24.com/v1/cowork/coupon/redeem', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_COWORK_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    code: 'PRAKTIKUM-7HKM4TQZ2RVW-45C80C',
    action: 'force',
  }),
})

if (!res.ok) {
  const { error } = await res.json()
  if (error.code === 'CONCURRENT_REDEMPTION') {
    // The only error code to retry automatically.
  }
  console.error(error.code)
} else {
  const { data } = await res.json()
  if (data.accessGranted) {
    const months = data.grantedTermMonths
    console.log(`${data.grantedTier} for ${months} ${months === 1 ? 'month' : 'months'}`)
  } else {
    // The tier is granted, but there is no access yet — an access request has been sent to the account administrator.
    console.log(`${data.grantedTier} activated, waiting for the administrator's decision`)
  }
}

Response fields

Response example

{
  "success": true,
  "data": {
    "grantedTier": "PRO",
    "grantedTermMonths": 3,
    "accessGranted": true
  }
}

The tier is granted, but Cowork/Code access has not yet been enabled for the Bitrix24 account:

{
  "success": true,
  "data": {
    "grantedTier": "PRO",
    "grantedTermMonths": 3,
    "accessGranted": false
  }
}

Error response example

409 — this tier is already assigned to the user's seat:

{
  "success": false,
  "error": {
    "code": "COUPON_SEAT_ALREADY_ON_TIER",
    "message": "The coupon cannot be redeemed"
  }
}

Errors

Coupon-specific refusals return status 409, with error.code identifying the reason. The message text is the same for all such refusals; do not parse it — branch on the code.

See Errors for the full list of common API errors.

Known specifics

Using a generic success screen for accessGranted: false creates the costliest category of support requests. The operation looks successful to the user, yet they cannot launch Cowork/Code, which looks like a malfunction. This state needs a dedicated screen — "The tier is activated, and an access request has been sent to the administrator" — rather than a generic "Done".

The submitted action expresses intent, not permission. The seat may have changed between the check and redemption: the user may have paid for a tier in another tab, the administrator may have downgraded the seat, or a scheduled cancellation may have taken effect. The decision is recomputed from the current state. If the selected action is no longer available, the endpoint returns COUPON_ACTION_NOT_AVAILABLE — repeat the check and show the actions it currently returns.

Retry CONCURRENT_REDEMPTION; never retry any other coupon refusal. The coupon remains valid, the rules were satisfied, and the gift was not consumed: by the time the response arrives, the coupon is available again. Retry up to three times with a 300–800 ms delay and random jitter — without jitter, dozens of clients retry in lockstep and reproduce the same contention. Show the user a waiting state during that time, not an error. Automatically retrying any other coupon refusal exhausts the failure counter in seconds. 429 RATE_LIMITED is separate: it is not a coupon refusal, does not affect the failure counter, and may be retried after a delay.

The force action forfeits the remainder of the paid term with no refund. The coupon check returns the exact number of forfeited days in losesDays; do not recompute it on the client. The button label must include that number before the user clicks it — after redemption, the term cannot be restored.

A coupon is single-use per user, but not necessarily overall. Some coupons allow several activations by different people. The number of users who share a coupon is not disclosed and must not be mentioned in user-facing text.

The failed-attempt counter is shared with the coupon check. The coupon check describes the pair used as the counter key and its reset condition.

The platform-wide limit is 10 requests per minute for redemption and 20 requests per minute for the check. The effective values for your key are returned in the x-ratelimit-limit response header. They are lower than the platform-wide limits because those limits are divided across replicas.

Coupon issuance is intentionally unavailable to this key. The desktop key is stored on the user's machine, so granting it issuance rights would make the campaign cap ineffective. Programmatic issuance requires a different key class and is performed by the partner's server, not the application.

See also

• Check a coupon
• Cowork/Code subscription state
• Cowork/Code subscription summary
• Tier change preview
• Cowork/Code
• Errors