Create Coupon - Add Discount Codes to Your Subscription Bot

Generate a new discount code for your subscription bot. Configure percentage or fixed-amount discounts, set auto-apply rules, restrict usage to specific plans or user types, and control whether the coupon applies to first payments only or renewals too.

POST/v2/projects/{project_id}/coupons

Authorization

Bearer TokenRequired

Path Parameters

project_idstringRequired

The unique identifier of the project.

Request Body

codestringRequired

The coupon code users will enter.

display_namestringRequired

Display name for the coupon.

descriptionstring

A description of the coupon.

coupon_typestringRequired

Type of discount: percentage or fixed.

percentagenumber

The discount percentage (required for percentage type).

amountnumber

The fixed discount amount (required for fixed type).

currencystring

Currency for fixed discounts (e.g., USD). Required for fixed type.

auto_applyboolean

Whether to auto-apply this coupon. Default: false

invitee_modestring

Who can use: all, new_users, existing_users. Default: all

renewal_constraintstring

When applicable: any, first_payment, renewals. Default: any

plan_scopestring

Which plans: all or specific. Default: all

metadataobject

Custom metadata for the coupon.

Request

curl -X POST "https://api.botsubscription.com/v2/projects/f47ac10b-58cc-4372-a567-0e02b2c3d479/coupons" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUMMER2024",
    "description": "Summer promotion discount",
    "discount_type": "percentage",
    "discount_value": 20,
    "max_redemptions": 100,
    "plan_ids": ["plan_abc123"],
    "valid_from": "2024-06-01T00:00:00.000Z",
    "valid_until": "2024-08-31T23:59:59.000Z"
  }'

const project_id = 'f47ac10b-58cc-4372-a567-0e02b2c3d479';
const response = await fetch(`https://api.botsubscription.com/v2/projects/${project_id}/coupons`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    code: 'SUMMER2024',
    description: 'Summer promotion discount',
    discount_type: 'percentage',
    discount_value: 20,
    max_redemptions: 100,
    plan_ids: ['plan_abc123'],
    valid_from: '2024-06-01T00:00:00.000Z',
    valid_until: '2024-08-31T23:59:59.000Z'
  })
});
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',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json'
    },
    json={
        'code': 'SUMMER2024',
        'description': 'Summer promotion discount',
        'discount_type': 'percentage',
        'discount_value': 20,
        'max_redemptions': 100,
        'plan_ids': ['plan_abc123'],
        'valid_from': '2024-06-01T00:00:00.000Z',
        'valid_until': '2024-08-31T23:59:59.000Z'
    }
)
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");
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',
    'description' => 'Summer promotion discount',
    'discount_type' => 'percentage',
    'discount_value' => 20,
    'max_redemptions' => 100,
    'plan_ids' => ['plan_abc123'],
    'valid_from' => '2024-06-01T00:00:00.000Z',
    'valid_until' => '2024-08-31T23:59:59.000Z'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

Coupon createdapplication/json

{
  "ok": true,
  "request_id": "11111111-1111-1111-1111-111111111111",
  "method": "POST",
  "path": "/v2/projects/YOUR_PROJECT_ID/coupons",
  "code": 201,
  "data": {
    "coupon_id": "11111111-1111-1111-1111-111111111111",
    "code": "SUMMER2024",
    "display_name": "Summer Sale",
    "description": "Summer promotion discount",
    "coupon_type": "percentage",
    "percentage": "20",
    "auto_apply": false,
    "status": "active",
    "total_redemptions": 0,
    "total_reservations": 0,
    "invitee_mode": "all",
    "renewal_constraint": "any",
    "payment_count_comparator": "any",
    "lifetime_revenue_comparator": "any",
    "plan_scope": "all",
    "created_at": "2024-05-15T10:00:00.000Z",
    "metadata": {}
  }
}

Validation errorapplication/json

{
  "ok": false,
  "request_id": "11111111-1111-1111-1111-111111111111",
  "method": "POST",
  "path": "/v2/projects/YOUR_PROJECT_ID/coupons",
  "code": 422,
  "errors": [
    {
      "message": "Invalid coupon_type: must be one of: percentage, fixed",
      "error_code": "VALIDATION_ERROR"
    }
  ]
}

Last updated: January 25, 2026

API Endpoint

Create Coupon - Add Discount Codes to Your Subscription Bot

Authorization

Path Parameters

Request Body