Check a coupon

POST /v1/cowork/coupon/preview

Checks a Cowork/Code coupon and shows the tier and term it grants. The preview reads the user's seat without changing it, and the coupon remains unredeemed.

The user and the Bitrix24 account come from the key binding; there are no path parameters.

Request fields (body)

Examples

The endpoint supports only one authorization method: a Cowork/Code desktop key. A personal key or application key receives 403 INSUFFICIENT_SCOPE or 403 COWORK_DESKTOP_KEY_REQUIRED.

curl — Cowork/Code desktop key

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

JavaScript — Cowork/Code desktop key

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

if (!res.ok) {
  const { error } = await res.json()
  console.error(error.code)
} else {
  const { data } = await res.json()

  if (!data.valid) {
    // Select the user-facing text based on data.reason — see "Refusal reasons".
    console.log(data.reason)
  } else {
    console.log(`${data.grant.tier} for ${data.grant.termMonths} months`)
    console.log('What you can do:', data.decision.kind)
  }
}

Response fields

Decision types

The data.decision field describes what happens to the user's seat if the coupon is redeemed now.

The contents of facts in the choose decision:

The contents of an options element:

Refusal reasons

The values of the data.reason field when valid: false.

Response example

The coupon is valid and the user's seat is vacant:

{
  "success": true,
  "data": {
    "valid": true,
    "reason": null,
    "grant": {
      "tier": "PRO",
      "termMonths": 3,
      "campaignName": "Partner workshop, August"
    },
    "decision": { "kind": "apply" }
  }
}

The coupon is valid, but the seat is taken by a higher paid tier — the user chooses:

{
  "success": true,
  "data": {
    "valid": true,
    "reason": null,
    "grant": {
      "tier": "PRO",
      "termMonths": 3,
      "campaignName": "Partner workshop, August"
    },
    "decision": {
      "kind": "choose",
      "facts": {
        "currentTier": "MAX",
        "paidThroughAt": "2026-09-14T10:00:00.000Z",
        "isPaid": true,
        "cancellationScheduled": false,
        "grantTier": "PRO",
        "grantTermMonths": 3
      },
      "options": [
        { "kind": "force", "losesDays": 24, "losesTier": "MAX" }
      ]
    }
  }
}

The coupon is invalid, but the endpoint still returns 200, and the body has no decision field:

{
  "success": true,
  "data": {
    "valid": false,
    "reason": "COUPON_INVALID",
    "grant": null
  }
}

Error response example

400 — a body with no code field:

{
  "success": false,
  "error": {
    "code": "INVALID_CODE",
    "message": "Field `code` is required"
  }
}

Errors

See Errors for the full list of common API errors.

A refusal of the coupon itself is not an error; it is returned with status 200 and data.valid: false.

Known specifics

The preview does not answer the question "will redemption succeed?" The data.valid field checks only the coupon and campaign: the code is active, it has not expired, the campaign is open, and neither the per-user nor the per-account limit is exhausted. The separate data.decision field covers the seat conditions, but it is not a guarantee either: the campaign's overall redemption cap is checked only during redemption, and the seat may change between the two calls. Prepare a refusal screen for the redemption step even after a successful preview.

The preview reads the seat but does not create one. Redemption creates a free seat for the user before checking the rules; the preview does not, because previewing a coupon must not change state. For a user without a seat, the decision therefore resolves to apply rather than an empty value.

Failed attempts count against the same counter as redemption. The count is keyed by the account–user pair, so one person's attempts do not affect their colleagues on the account. After ten failures within an hour, further attempts are blocked for thirty minutes. A successful redemption resets the counter.

A typo does not consume an attempt. The final segment of the coupon is a checksum over the prefix and body. Input that fails the checksum never reaches the database, so copying a code from a handout or reading it over the phone does not consume an attempt.

Do not call the preview endpoint on every keystroke. Because preview is cheaper and repeatable, it poses a greater brute-force risk than redemption. Bind the call to a button or use a delay of at least 500 ms after the last keystroke.

Seven different refusals are deliberately collapsed into COUPON_INVALID; clients do not need to distinguish them. A separate reason for each case would tell someone guessing codes which prefixes are active: receiving a "limit is exhausted" response would prove that the submitted code belongs to a real campaign. Do not add branches for "the code was revoked" or "the limit is exhausted" — those values never appear in the response.

A refusal takes at least four hundred milliseconds. The response is padded to a minimum duration so that timing cannot distinguish "there is no such code" from "the code exists but was revoked". A response that naturally takes longer is not shortened.

Deferred application is not supported. The action "apply the gift at the end of the paid term" never appears in options. If such an option appears, it indicates a bug on our side, not a signal to render a button for it.

See also

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