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_•••'

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.

percentagestring

Discount percentage as a decimal string, greater than 0 and at most 100 (required for percentage type).

amountstring

Fixed discount amount as a decimal string (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

usage_limitinteger

Total redemptions allowed across all users.

per_user_limitinteger

Redemptions allowed per user.

invitee_modestring

Who can use: all, inviteesOnly, nonInvitees. Default: all

renewal_constraintstring

When applicable: any, renewalOnly, churnedOnly. Default: any

plan_scopestring

Which plans: all, include, exclude. Default: all (plan_ids required when include or exclude).

plan_idsarray

Plan UUIDs to include or exclude, per plan_scope.

starts_atnumber | string

Validity start: Unix milliseconds or ISO-8601 string.

ends_atnumber | string

Validity end: Unix milliseconds or ISO-8601 string. Must be after starts_at.

metadataobject

Custom metadata for the coupon.

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",
    "display_name": "Summer Sale",
    "description": "Summer promotion discount",
    "coupon_type": "percentage",
    "percentage": "20",
    "usage_limit": 100,
    "plan_scope": "include",
    "plan_ids": ["b2c9f6f0-7a47-4c2e-9a0e-4a4fa1d8c1c4"],
    "starts_at": 1717200000000,
    "ends_at": 1725148799000
  }'

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',
    display_name: 'Summer Sale',
    description: 'Summer promotion discount',
    coupon_type: 'percentage',
    percentage: '20',
    usage_limit: 100,
    plan_scope: 'include',
    plan_ids: ['b2c9f6f0-7a47-4c2e-9a0e-4a4fa1d8c1c4'],
    starts_at: 1717200000000,
    ends_at: 1725148799000
  })
});
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',
        'display_name': 'Summer Sale',
        'description': 'Summer promotion discount',
        'coupon_type': 'percentage',
        'percentage': '20',
        'usage_limit': 100,
        'plan_scope': 'include',
        'plan_ids': ['b2c9f6f0-7a47-4c2e-9a0e-4a4fa1d8c1c4'],
        'starts_at': 1717200000000,
        'ends_at': 1725148799000
    }
)
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',
    'display_name' => 'Summer Sale',
    'description' => 'Summer promotion discount',
    'coupon_type' => 'percentage',
    'percentage' => '20',
    'usage_limit' => 100,
    'plan_scope' => 'include',
    'plan_ids' => ['b2c9f6f0-7a47-4c2e-9a0e-4a4fa1d8c1c4'],
    'starts_at' => 1717200000000,
    'ends_at' => 1725148799000
]));
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": 1715767200000,
    "archived_at": null,
    "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: July 8, 2026