Promo Codes

Create promotional discounts with percentage or fixed amounts, usage limits, date ranges, and plan-specific targeting.

Promo codes let you offer discounts to customers during enrollment or as ongoing promotions. Codes support percentage and fixed-amount discounts, usage limits, date restrictions, and plan-specific targeting.

Field	Description
`code`	The code customers enter (e.g., "SUMMER25")
`discount_type`	`percent` or `fixed`
`discount_value`	Discount amount — percentage (e.g., 25 for 25%) or cents (e.g., 1000 for $10.00)
`max_uses`	Maximum number of times the code can be redeemed (null = unlimited)
`current_uses`	How many times it has been used
`valid_from`	Start date for the promotion (null = immediately valid)
`valid_until`	Expiration date (null = no expiration)
`applies_to_plan_ids_json`	JSON array of plan IDs this code applies to (empty = all plans)
`is_active`	Whether the code is currently redeemable

Discount Types

Percentage Discount

Reduces the plan price by a percentage:

Discounted price = price_cents × (1 - discount_value / 100)

Example: Code "SAVE20" with discount_type: "percent" and discount_value: 20

Plan price: $35.00
Discount: $7.00 (20%)
Customer pays: $28.00

Fixed Amount Discount

Reduces the plan price by a fixed dollar amount:

Discounted price = price_cents - discount_value

Example: Code "10OFF" with discount_type: "fixed" and discount_value: 1000

Plan price: $35.00
Discount: $10.00
Customer pays: $25.00

Usage Limits

Set max_uses to control how many times a code can be redeemed:

max_uses: 100 — first 100 customers to use the code
max_uses: 1 — single-use code (e.g., for a specific customer)
max_uses: null — unlimited uses

The current_uses counter increments each time the code is applied to a customer.

Date Restrictions

Use valid_from and valid_until to create time-limited promotions:

Seasonal promotion: valid_from: "2026-06-01", valid_until: "2026-08-31"
Flash sale: valid_from: "2026-03-24", valid_until: "2026-03-25"
Ongoing: Leave both null

Plan-Specific Promos

The applies_to_plan_ids_json field restricts a code to specific service plans:

["plan_abc123", "plan_def456"]

If empty ([]), the code applies to all plans. Use this to offer discounts only on specific service tiers or frequencies.

From the Dashboard

Go to Billing > Promo Codes (or Marketing > Promos)
Click Add Promo Code
Enter the code, discount type, and value
Set optional limits (max uses, date range, plan restrictions)
Save

From the API

POST https://api.nextroute.app/api/promos
Authorization: Bearer <token>
Content-Type: application/json

{
  "code": "SUMMER25",
  "discount_type": "percent",
  "discount_value": 25,
  "max_uses": 100,
  "valid_from": "2026-06-01",
  "valid_until": "2026-08-31",
  "applies_to_plan_ids_json": []
}

Promo codes can be applied:

During customer enrollment (via the enrollment form or portal)
When creating a customer in the dashboard (set promo_code_id on the customer)
Via the pricing widget on your website

The discount is applied to the customer's invoices for the duration of the promotion.

Service Plans — the plans promo codes apply to
Customer Portal — where customers can enter promo codes
Enrollment — promo codes during self-service signup

On this page