api.botsubscription.com

GET/v1/endpoint

AuthenticationBearer

Token

Stays in this tab. Required for this endpoint — the value below is what gets sent.

Path parameters0

Query parameters0

BodyJSON

Mock

curl --request GET \
  --url https://api.botsubscription.com/v1/endpoint \
  --header 'Authorization: Bearer sk_live_•••'

Validate Coupon - Check Discount Code Eligibility via API

Check if a coupon code is valid for a specific user and purchase amount before applying it. The response shows whether the coupon is eligible, the calculated discount, and the final price—or the reasons why the coupon cannot be used.

POST/v2/projects/{project_id}/coupons/validate

Authorization

Bearer TokenRequired

Path Parameters

project_idstringrequired

The unique identifier of the project.

Request Body

coupon_idstring

Coupon UUID. Either coupon_id or code is required.

codestring

Coupon code (case-insensitive). Either code or coupon_id is required.

amountstringrequired

Order amount to evaluate against, as a decimal string.

currencystringrequired

The currency of the amount (e.g., USD).

user_idstring

The user ID, used to evaluate per-user limits and audience scope.

plan_idstring

Plan being purchased, used for plan_scope checks. Omit for top-up previews.

is_renewalboolean

Whether the purchase is a renewal, used for renewal_constraint.

is_churnedboolean

Whether the user is churned, used for renewal_constraint.

contextobject

Additional eligibility hints: is_invitee, is_new_user.

curl -X POST "https://api.botsubscription.com/v2/projects/f47ac10b-58cc-4372-a567-0e02b2c3d479/coupons/validate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUMMER2024",
    "user_id": "user_123456789",
    "amount": "29.99",
    "currency": "USD",
    "plan_id": "plan_abc123"
  }'

const project_id = 'f47ac10b-58cc-4372-a567-0e02b2c3d479';
const response = await fetch(`https://api.botsubscription.com/v2/projects/${project_id}/coupons/validate`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    code: 'SUMMER2024',
    user_id: 'user_123456789',
    amount: '29.99',
    currency: 'USD',
    plan_id: 'plan_abc123'
  })
});
const data = await response.json();

import requests
 
project_id = 'f47ac10b-58cc-4372-a567-0e02b2c3d479'
response = requests.post(
    f'https://api.botsubscription.com/v2/projects/{project_id}/coupons/validate',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json'
    },
    json={
        'code': 'SUMMER2024',
        'user_id': 'user_123456789',
        'amount': '29.99',
        'currency': 'USD',
        'plan_id': 'plan_abc123'
    }
)
data = response.json()

$project_id = 'f47ac10b-58cc-4372-a567-0e02b2c3d479';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.botsubscription.com/v2/projects/{$project_id}/coupons/validate");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_TOKEN',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'code' => 'SUMMER2024',
    'user_id' => 'user_123456789',
    'amount' => '29.99',
    'currency' => 'USD',
    'plan_id' => 'plan_abc123'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

Coupon eligibleapplication/json

{
  "ok": true,
  "request_id": "11111111-1111-1111-1111-111111111111",
  "method": "POST",
  "path": "/v2/projects/YOUR_PROJECT_ID/coupons/validate",
  "code": 200,
  "data": {
    "coupon_id": "11111111-1111-1111-1111-111111111111",
    "eligible": true,
    "reasons": [],
    "original_amount": "29.99",
    "applied_amount": "6",
    "final_amount": "23.99",
    "currency": "USD"
  }
}

Coupon not eligibleapplication/json

{
  "ok": true,
  "request_id": "11111111-1111-1111-1111-111111111111",
  "method": "POST",
  "path": "/v2/projects/YOUR_PROJECT_ID/coupons/validate",
  "code": 200,
  "data": {
    "coupon_id": "11111111-1111-1111-1111-111111111111",
    "eligible": false,
    "reasons": ["Coupon has expired"],
    "original_amount": "29.99",
    "applied_amount": null,
    "final_amount": "29.99",
    "currency": "USD"
  }
}

Coupon not foundapplication/json

{
  "ok": false,
  "request_id": "11111111-1111-1111-1111-111111111111",
  "method": "POST",
  "path": "/v2/projects/YOUR_PROJECT_ID/coupons/validate",
  "code": 404,
  "error": {
    "error_code": "NOT_FOUND",
    "message": "Requested resource could not be found"
  }
}

Last updated: July 8, 2026