Skip to main content

​
Overview

Products represent the items you sell through Polar. They can be one-time purchases or recurring subscriptions, with flexible pricing options including fixed, custom (pay-what-you-want), free, seat-based, and metered billing.

​
The Product Object

​
id
string
required
Unique identifier for the product
​
name
string
required
The name of the product (3-64 characters)
​
description
string
The description of the product
​
visibility
enum
Product visibility: public, private, or archived
​
is_recurring
boolean
required
Whether the product is a subscription
​
recurring_interval
enum
For subscriptions: month or year. null for one-time products
​
recurring_interval_count
integer
Number of intervals between charges (e.g., 1 = monthly, 2 = every 2 months)
​
is_archived
boolean
required
Whether the product is archived
​
organization_id
string
required
ID of the organization owning the product
​
prices
array
required
List of available prices for this product
​
benefits
array
required
List of benefits granted by this product
​
medias
array
List of media files (images) associated with the product
​
attached_custom_fields
array
Custom fields attached to the product
​
metadata
object
Custom metadata key-value pairs
​
created_at
string
required
Timestamp of when the product was created
​
updated_at
string
required
Timestamp of when the product was last updated

​
List Products

curl -X GET "https://api.polar.sh/v1/products" \
  -H "Authorization: Bearer polar_pat_..."

​
Query Parameters

​
page
integer
default:"1"
Page number
​
limit
integer
default:"20"
Number of items per page (max 100)
​
organization_id
string
Filter by organization ID
​
id
string
Filter by product ID(s). Supports multiple values
​
query
string
Filter by product name
​
is_archived
boolean
Filter archived products
​
is_recurring
boolean
Filter by recurring (subscriptions) vs one-time products
​
benefit_id
string
Filter products granting a specific benefit
​
visibility
array
Filter by visibility: public, private
​
sorting
array
default:"-created_at"
Sort by: created_at, name, -created_at, -name
​
metadata
object
Filter by metadata (e.g., metadata.key=value)

​
Response

​
items
array
required
Array of product objects
​
pagination
object
required

​
Get Product

curl -X GET "https://api.polar.sh/v1/products/{id}" \
  -H "Authorization: Bearer polar_pat_..."

​
Path Parameters

​
id
string
required
Product ID

​
Response

Returns a product object.

​
Errors

​
404
Not Found
Product not found

​
Create Product

curl -X POST "https://api.polar.sh/v1/products" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Plan",
    "description": "Full access to all features",
    "visibility": "public",
    "recurring_interval": "month",
    "recurring_interval_count": 1,
    "prices": [
      {
        "amount_type": "fixed",
        "price_amount": 2999,
        "price_currency": "USD"
      }
    ],
    "organization_id": "org_123"
  }'

​
Request Body

​
name
string
required
Product name (3-64 characters)
​
description
string
Product description
​
visibility
enum
default:"public"
Product visibility: public or private
​
recurring_interval
enum
For subscriptions: month or year. Omit or set to null for one-time products
​
recurring_interval_count
integer
default:"1"
Number of intervals (1-999). E.g., 1 = monthly, 2 = every 2 months
​
prices
array
required
List of prices. Must include at least one price.
​
medias
array
Array of file IDs for product images
​
attached_custom_fields
array
Custom fields to attach to the product
​
organization_id
string
Organization ID (required unless using organization token)
​
metadata
object
Custom metadata (key-value pairs)

​
Response

​
201
Created
Returns the created product object

​
Update Product

curl -X PATCH "https://api.polar.sh/v1/products/{id}" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Plan Updated",
    "is_archived": false
  }'

​
Path Parameters

​
id
string
required
Product ID

​
Request Body

All fields are optional. Only include fields you want to update.
​
name
string
Product name (3-64 characters)
​
description
string
Product description
​
visibility
enum
Product visibility: public or private
​
is_archived
boolean
Archive or unarchive the product
​
prices
array
Update prices. Include existing price IDs to keep them, or add new price objects
​
medias
array
Update product images (file IDs)
​
attached_custom_fields
array
Update attached custom fields
​
metadata
object
Update metadata

​
Response

Returns the updated product object.

​
Errors

​
403
Forbidden
You don’t have permission to update this product
​
404
Not Found
Product not found

​
Update Product Benefits

curl -X POST "https://api.polar.sh/v1/products/{id}/benefits" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "benefits": ["benefit_123", "benefit_456"]
  }'

​
Path Parameters

​
id
string
required
Product ID

​
Request Body

​
benefits
array
required
Array of benefit IDs to grant with this product

​
Response

Returns the updated product object with the new benefits.

​
Errors

​
403
Forbidden
You don’t have permission to update this product
​
404
Not Found
Product not found

​
Price Types

​
Fixed Price

A standard fixed price: 
{
  "amount_type": "fixed",
  "price_amount": 2999,
  "price_currency": "USD"
}

​
Custom Price (Pay What You Want)

Let customers choose their price: 
{
  "amount_type": "custom",
  "minimum_amount": 500,
  "maximum_amount": 10000,
  "preset_amount": 2999,
  "price_currency": "USD"
}

​
Free Price

Completely free: 
{
  "amount_type": "free",
  "price_currency": "USD"
}

​
Seat-Based Price

Per-seat pricing with volume tiers: 
{
  "amount_type": "seat_based",
  "seat_tiers": [
    {
      "min_seats": 1,
      "max_seats": 5,
      "price_per_seat": 1000
    },
    {
      "min_seats": 6,
      "max_seats": 20,
      "price_per_seat": 800
    },
    {
      "min_seats": 21,
      "max_seats": null,
      "price_per_seat": 600
    }
  ],
  "price_currency": "USD"
}

​
Metered Unit Price

Usage-based pricing: 
{
  "amount_type": "metered_unit",
  "meter_id": "meter_123",
  "unit_amount": 0.05,
  "cap_amount": 10000,
  "price_currency": "USD"
}

​
Examples

​
Create a Monthly Subscription

curl -X POST "https://api.polar.sh/v1/products" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Plan",
    "description": "Professional features",
    "recurring_interval": "month",
    "prices": [
      {
        "amount_type": "fixed",
        "price_amount": 4999,
        "price_currency": "USD"
      }
    ],
    "organization_id": "org_123"
  }'

​
Create a One-Time Product

curl -X POST "https://api.polar.sh/v1/products" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lifetime Access",
    "recurring_interval": null,
    "prices": [
      {
        "amount_type": "fixed",
        "price_amount": 29900,
        "price_currency": "USD"
      }
    ],
    "organization_id": "org_123"
  }'

​
Archive a Product

curl -X PATCH "https://api.polar.sh/v1/products/prod_123" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{"is_archived": true}'

Build docs developers (and LLMs) love

Get started for freeTalk to us