Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/polarsource/polar/llms.txt

Use this file to discover all available pages before exploring further.

Discount codes allow you to offer promotional pricing to your customers. They can be applied during checkout either by customers entering a code or programmatically via the API.

​
Discount Types

Polar supports two types of discounts:

Fixed Amount

Discount a specific amount in a given currency (e.g., $10 off)

Percentage

Discount a percentage of the total (e.g., 25% off)

​
Duration Options

For subscription products, you can control how long the discount applies:
  • Once: Applied only to the first invoice
  • Forever: Applied to every invoice for the lifetime of the subscription
  • Repeating: Applied for a specific number of months (e.g., 3 months)
For one-time purchases, discounts are always applied once.

​
Creating a Discount

1

Navigate to Discounts

Go to your organization dashboard and select Sales > Discounts.
2

Configure the Discount

Set the discount type, amount, and duration:
Example: 25% off for 3 months
{
  "name": "New Customer Promo",
  "code": "WELCOME25",
  "type": "percentage",
  "basis_points": 2500,
  "duration": "repeating",
  "duration_in_months": 3
}
3

Set Restrictions (Optional)

  • Products: Limit to specific products
  • Start Date: When the discount becomes active
  • End Date: When the discount expires
  • Max Redemptions: Limit total uses
4

Create the Discount

Click Create to make the discount code available.

​
Discount Codes

Discount codes must be:
  • Between 3 and 256 characters
  • Alphanumeric only (letters and numbers)
  • Case-insensitive (WELCOME25 = welcome25)
If you don’t provide a code, the discount can only be applied programmatically via the API.

​
Applying Discounts

​
At Checkout

Customers can enter discount codes in the checkout form. The discount is validated and applied automatically:
  • Product restrictions are checked
  • Currency compatibility is verified (for fixed amount discounts)
  • Redemption limits are enforced
  • Date restrictions are validated

​
Via API

Apply discounts programmatically when creating checkouts: 
const checkout = await polar.checkouts.create({
  productPriceId: 'price_xxx',
  discountId: 'discount_xxx',  // or
  discountCode: 'WELCOME25'
});

​
Redemption Tracking

Polar automatically tracks discount redemptions:
  • Redemptions Count: Total times the discount has been used
  • Max Redemptions: Optional limit on total uses
  • Concurrency Protection: Row-level locking prevents over-redemption
When a discount reaches its maximum redemptions, it automatically becomes unavailable.

​
Updating Discounts

You can update most discount properties after creation: ✅ Can Update:
  • Name
  • Code (if not duplicate)
  • Start/end dates
  • Max redemptions
  • Product restrictions
❌ Cannot Update:
  • Type (fixed vs percentage)
  • Duration (once/forever/repeating)
  • Amount/percentage (after first redemption)
Once a discount has been redeemed, you cannot change the discount amount to protect customer pricing consistency.

​
Metadata

Attach custom metadata to discounts for tracking: 
{
  "metadata": {
    "campaign": "summer_2024",
    "source": "email_newsletter"
  }
}

​
Basis Points Explained

Percentage discounts use basis points (1/100th of a percent):
  • 10% = 1000 basis points
  • 25.5% = 2550 basis points
  • 100% = 10000 basis points (maximum)
Example: 15% discount
{
  "type": "percentage",
  "basis_points": 1500
}

​
Fixed Amount Discounts

Fixed amount discounts require a currency:
Example: $10 off
{
  "type": "fixed",
  "amount": 1000,
  "currency": "usd"
}
Amounts are always in cents (or smallest currency unit). $10 = 1000 cents.

​
Currency Compatibility

Fixed amount discounts only apply to products with matching currency. If a customer’s checkout uses a different currency, the discount will not be valid.

​
Best Practices

Use Descriptive Codes

Make codes memorable and relevant: SUMMER2024, EARLYBIRD, STUDENT20

Set Expiration Dates

Create urgency with time-limited offers

Track with Metadata

Use metadata to track campaign performance

Limit Redemptions

Prevent abuse with max redemption limits

​
API Reference

See the full API documentation:

Build docs developers (and LLMs) love

Get started for freeTalk to us