Overview
Benefits are perks granted to customers who purchase products. They can be license keys, downloadable files, Discord roles, GitHub repository access, and more.
The Benefit Object
Unique identifier for the benefit
Type: custom, discord, github_repository, downloadables, license_keys, ads, or feature_flag
Benefit description shown to customers
Type-specific configuration
Whether tax applies to this benefit
List Benefits
curl -X GET "https://api.polar.sh/v1/benefits" \
-H "Authorization: Bearer polar_pat_..."
Query Parameters
Exclude specific benefit IDs
Get Benefit
curl -X GET "https://api.polar.sh/v1/benefits/{id}" \
-H "Authorization: Bearer polar_pat_..."
Path Parameters
Create Benefit
curl -X POST "https://api.polar.sh/v1/benefits" \
-H "Authorization: Bearer polar_pat_..." \
-H "Content-Type: application/json" \
-d '{
"type": "custom",
"description": "Priority email support",
"organization_id": "org_123"
}'
Request Body
Description shown to customers
Organization ID (required unless using org token)
Type-specific properties (see examples below)
Update Benefit
curl -X PATCH "https://api.polar.sh/v1/benefits/{id}" \
-H "Authorization: Bearer polar_pat_..." \
-H "Content-Type: application/json" \
-d '{
"description": "24/7 Priority Support"
}'
Path Parameters
Request Body
Delete Benefit
curl -X DELETE "https://api.polar.sh/v1/benefits/{id}" \
-H "Authorization: Bearer polar_pat_..."
Path Parameters
Benefit Types
Custom Benefit
A generic benefit you manage manually:
{
"type": "custom",
"description": "Priority support",
"properties": {
"note": "Grant access in your system"
}
}
License Keys
Automatically generated license keys:
{
"type": "license_keys",
"description": "Software license",
"properties": {
"prefix": "PROD",
"expires": 31536000,
"activations": 3,
"limit_usage": true
}
}
Downloadables
Downloadable files:
{
"type": "downloadables",
"description": "Premium templates",
"properties": {
"files": ["file_123", "file_456"]
}
}
Discord Role
Automatic Discord role assignment:
{
"type": "discord",
"description": "VIP Discord role",
"properties": {
"guild_id": "123456789",
"role_id": "987654321"
}
}
GitHub Repository Access
Grant access to private repositories:
{
"type": "github_repository",
"description": "Access to private repo",
"properties": {
"repository_owner": "myorg",
"repository_name": "private-repo",
"permission": "pull"
}
}
Examples
Create License Key Benefit
curl -X POST "https://api.polar.sh/v1/benefits" \
-H "Authorization: Bearer polar_pat_..." \
-H "Content-Type: application/json" \
-d '{
"type": "license_keys",
"description": "Pro License Key",
"organization_id": "org_123",
"properties": {
"prefix": "PRO",
"expires": 31536000,
"activations": 5
}
}'
Create Downloadables Benefit
curl -X POST "https://api.polar.sh/v1/benefits" \
-H "Authorization: Bearer polar_pat_..." \
-H "Content-Type: application/json" \
-d '{
"type": "downloadables",
"description": "Premium Assets Pack",
"organization_id": "org_123",
"properties": {
"files": ["file_abc", "file_def"]
}
}'