Create Discount

POST

discounts

import { Polar } from "@polar-sh/sdk";

const polar = new Polar({
  accessToken: process.env["POLAR_ACCESS_TOKEN"] ?? "",
});

async function run() {
  const result = await polar.discounts.create({
    duration: "once",
    type: "fixed",
    basisPoints: 449604,
    name: "<value>",
    organizationId: "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
  });

  // Handle the result
  console.log(result);
}

run();

{
  "duration": "once",
  "type": "fixed",
  "amount": 123,
  "currency": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "modified_at": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "metadata": {},
  "name": "<string>",
  "code": "<string>",
  "starts_at": "2023-11-07T05:31:56Z",
  "ends_at": "2023-11-07T05:31:56Z",
  "max_redemptions": 123,
  "redemptions_count": 123,
  "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
  "products": [
    {
      "metadata": {},
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "recurring_interval": "month",
      "is_recurring": true,
      "is_archived": true,
      "organization_id": "<string>"
    }
  ]
}

Authorizations

Authorization

string

header

required

You can generate an Organization Access Token from your organization's settings.

Body

application/json

Schema to create a fixed amount discount that is applied once or forever.

duration

enum<string>

required

Available options:

once,

forever,

repeating

type

enum<string>

required

Type of the discount.

Available options:

fixed,

percentage

amount

integer

required

Fixed amount to discount from the invoice total.

Required range: x >= 0

name

string

required

Name of the discount. Will be displayed to the customer when the discount is applied.

Minimum length: 1

currency

string

default:usd

The currency. Currently, only usd is supported.

metadata

object

Key-value object allowing you to store additional information.

The key must be a string with a maximum length of 40 characters. The value must be either:

A string with a maximum length of 500 characters
An integer
A floating-point number
A boolean

You can store up to 50 key-value pairs.

code

string | null

Code customers can use to apply the discount during checkout. Must be between 3 and 256 characters long and contain only alphanumeric characters.If not provided, the discount can only be applied via the API.

starts_at

string | null

Optional timestamp after which the discount is redeemable.

ends_at

string | null

Optional timestamp after which the discount is no longer redeemable.

max_redemptions

integer | null

Optional maximum number of times the discount can be redeemed.

Required range: x >= 1

products

string[] | null

List of product IDs the discount can be applied to.

organization_id

string | null

The ID of the organization owning the discount. Required unless you use an organization token. The organization ID.

Examples:

"1dbfc517-0bbf-4301-9ba8-555ca42b9737"

Schema to create a fixed amount discount that is applied once or forever.

duration

enum<string>

required

Available options:

once,

forever,

repeating

type

enum<string>

required

Type of the discount.

Available options:

fixed,

percentage

amount

integer

required

Fixed amount to discount from the invoice total.

Required range: x >= 0

name

string

required

Name of the discount. Will be displayed to the customer when the discount is applied.

Minimum length: 1

currency

string

default:usd

The currency. Currently, only usd is supported.

metadata

object

Key-value object allowing you to store additional information.

The key must be a string with a maximum length of 40 characters. The value must be either:

A string with a maximum length of 500 characters
An integer
A floating-point number
A boolean

You can store up to 50 key-value pairs.

code

string | null

starts_at

string | null

Optional timestamp after which the discount is redeemable.

ends_at

string | null

Optional timestamp after which the discount is no longer redeemable.

max_redemptions

integer | null

Optional maximum number of times the discount can be redeemed.

Required range: x >= 1

products

string[] | null

List of product IDs the discount can be applied to.

organization_id

string | null

The ID of the organization owning the discount. Required unless you use an organization token. The organization ID.

Examples:

"1dbfc517-0bbf-4301-9ba8-555ca42b9737"

Schema to create a fixed amount discount that is applied on every invoice for a certain number of months.

duration

enum<string>

required

Available options:

once,

forever,

repeating

duration_in_months

integer

required

Number of months the discount should be applied.

For this to work on yearly pricing, you should multiply this by 12. For example, to apply the discount for 2 years, set this to 24.

Required range: x >= 1

type

enum<string>

required

Type of the discount.

Available options:

fixed,

percentage

amount

integer

required

Fixed amount to discount from the invoice total.

Required range: x >= 0

name

string

required

Name of the discount. Will be displayed to the customer when the discount is applied.

Minimum length: 1

currency

string

default:usd

The currency. Currently, only usd is supported.

metadata

object

Key-value object allowing you to store additional information.

The key must be a string with a maximum length of 40 characters. The value must be either:

A string with a maximum length of 500 characters
An integer
A floating-point number
A boolean

You can store up to 50 key-value pairs.

code

string | null

starts_at

string | null

Optional timestamp after which the discount is redeemable.

ends_at

string | null

Optional timestamp after which the discount is no longer redeemable.

max_redemptions

integer | null

Optional maximum number of times the discount can be redeemed.

Required range: x >= 1

products

string[] | null

List of product IDs the discount can be applied to.

organization_id

string | null

The ID of the organization owning the discount. Required unless you use an organization token. The organization ID.

Examples:

"1dbfc517-0bbf-4301-9ba8-555ca42b9737"

Schema to create a percentage discount that is applied once or forever.

duration

enum<string>

required

Available options:

once,

forever,

repeating

type

enum<string>

required

Type of the discount.

Available options:

fixed,

percentage

basis_points

integer

required

Discount percentage in basis points.

A basis point is 1/100th of a percent. For example, to create a 25.5% discount, set this to 2550.

Required range: 1 <= x <= 10000

name

string

required

Name of the discount. Will be displayed to the customer when the discount is applied.

Minimum length: 1

metadata

object

Key-value object allowing you to store additional information.

The key must be a string with a maximum length of 40 characters. The value must be either:

A string with a maximum length of 500 characters
An integer
A floating-point number
A boolean

You can store up to 50 key-value pairs.

code

string | null

starts_at

string | null

Optional timestamp after which the discount is redeemable.

ends_at

string | null

Optional timestamp after which the discount is no longer redeemable.

max_redemptions

integer | null

Optional maximum number of times the discount can be redeemed.

Required range: x >= 1

products

string[] | null

List of product IDs the discount can be applied to.

organization_id

string | null

The ID of the organization owning the discount. Required unless you use an organization token. The organization ID.

Examples:

"1dbfc517-0bbf-4301-9ba8-555ca42b9737"

Schema to create a percentage discount that is applied on every invoice for a certain number of months.

duration

enum<string>

required

Available options:

once,

forever,

repeating

duration_in_months

integer

required

Number of months the discount should be applied.

For this to work on yearly pricing, you should multiply this by 12. For example, to apply the discount for 2 years, set this to 24.

Required range: x >= 1

type

enum<string>

required

Type of the discount.

Available options:

fixed,

percentage

basis_points

integer

required

Discount percentage in basis points.

A basis point is 1/100th of a percent. For example, to create a 25.5% discount, set this to 2550.

Required range: 1 <= x <= 10000

name

string

required

Name of the discount. Will be displayed to the customer when the discount is applied.

Minimum length: 1

metadata

object

Key-value object allowing you to store additional information.

The key must be a string with a maximum length of 40 characters. The value must be either:

A string with a maximum length of 500 characters
An integer
A floating-point number
A boolean

You can store up to 50 key-value pairs.

code

string | null

starts_at

string | null

Optional timestamp after which the discount is redeemable.

ends_at

string | null

Optional timestamp after which the discount is no longer redeemable.

max_redemptions

integer | null

Optional maximum number of times the discount can be redeemed.

Required range: x >= 1

products

string[] | null

List of product IDs the discount can be applied to.

organization_id

string | null

The ID of the organization owning the discount. Required unless you use an organization token. The organization ID.

Examples:

"1dbfc517-0bbf-4301-9ba8-555ca42b9737"

Response

201

application/json

Discount created.

Schema for a fixed amount discount that is applied once or forever.

duration

enum<string>

required

Available options:

once,

forever,

repeating

type

enum<string>

required

Available options:

fixed,

percentage

amount

integer

required

currency

string

required

created_at

string

required

Creation timestamp of the object.

modified_at

string | null

required

Last modification timestamp of the object.

string

required

The ID of the object.

metadata

object

required

name

string

required

Name of the discount. Will be displayed to the customer when the discount is applied.

code

string | null

required

Code customers can use to apply the discount during checkout.

starts_at

string | null

required

Timestamp after which the discount is redeemable.

ends_at

string | null

required

Timestamp after which the discount is no longer redeemable.

max_redemptions

integer | null

required

Maximum number of times the discount can be redeemed.

redemptions_count

integer

required

Number of times the discount has been redeemed.

organization_id

string

required

The organization ID.

Examples:

"1dbfc517-0bbf-4301-9ba8-555ca42b9737"

products

DiscountProduct · object[]

required

Schema for a fixed amount discount that is applied once or forever.

duration

enum<string>

required

Available options:

once,

forever,

repeating

type

enum<string>

required

Available options:

fixed,

percentage

amount

integer

required

currency

string

required

created_at

string

required

Creation timestamp of the object.

modified_at

string | null

required

Last modification timestamp of the object.

string

required

The ID of the object.

metadata

object

required

name

string

required

Name of the discount. Will be displayed to the customer when the discount is applied.

code

string | null

required

Code customers can use to apply the discount during checkout.

starts_at

string | null

required

Timestamp after which the discount is redeemable.

ends_at

string | null

required

Timestamp after which the discount is no longer redeemable.

max_redemptions

integer | null

required

Maximum number of times the discount can be redeemed.

redemptions_count

integer

required

Number of times the discount has been redeemed.

organization_id

string

required

The organization ID.

Examples:

"1dbfc517-0bbf-4301-9ba8-555ca42b9737"

products

DiscountProduct · object[]

required

Schema for a fixed amount discount that is applied on every invoice for a certain number of months.

duration

enum<string>

required

Available options:

once,

forever,

repeating

duration_in_months

integer

required

type

enum<string>

required

Available options:

fixed,

percentage

amount

integer

required

currency

string

required

created_at

string

required

Creation timestamp of the object.

modified_at

string | null

required

Last modification timestamp of the object.

string

required

The ID of the object.

metadata

object

required

name

string

required

Name of the discount. Will be displayed to the customer when the discount is applied.

code

string | null

required

Code customers can use to apply the discount during checkout.

starts_at

string | null

required

Timestamp after which the discount is redeemable.

ends_at

string | null

required

Timestamp after which the discount is no longer redeemable.

max_redemptions

integer | null

required

Maximum number of times the discount can be redeemed.

redemptions_count

integer

required

Number of times the discount has been redeemed.

organization_id

string

required

The organization ID.

Examples:

"1dbfc517-0bbf-4301-9ba8-555ca42b9737"

products

DiscountProduct · object[]

required

Schema for a percentage discount that is applied once or forever.

duration

enum<string>

required

Available options:

once,

forever,

repeating

type

enum<string>

required

Available options:

fixed,

percentage

basis_points

integer

required

created_at

string

required

Creation timestamp of the object.

modified_at

string | null

required

Last modification timestamp of the object.

string

required

The ID of the object.

metadata

object

required

name

string

required

Name of the discount. Will be displayed to the customer when the discount is applied.

code

string | null

required

Code customers can use to apply the discount during checkout.

starts_at

string | null

required

Timestamp after which the discount is redeemable.

ends_at

string | null

required

Timestamp after which the discount is no longer redeemable.

max_redemptions

integer | null

required

Maximum number of times the discount can be redeemed.

redemptions_count

integer

required

Number of times the discount has been redeemed.

organization_id

string

required

The organization ID.

Examples:

"1dbfc517-0bbf-4301-9ba8-555ca42b9737"

products

DiscountProduct · object[]

required

Schema for a percentage discount that is applied on every invoice for a certain number of months.

duration

enum<string>

required

Available options:

once,

forever,

repeating

duration_in_months

integer

required

type

enum<string>

required

Available options:

fixed,

percentage

basis_points

integer

required

created_at

string

required

Creation timestamp of the object.

modified_at

string | null

required

Last modification timestamp of the object.

string

required

The ID of the object.

metadata

object

required

name

string

required

Name of the discount. Will be displayed to the customer when the discount is applied.

code

string | null

required

Code customers can use to apply the discount during checkout.

starts_at

string | null

required

Timestamp after which the discount is redeemable.

ends_at

string | null

required

Timestamp after which the discount is no longer redeemable.

max_redemptions

integer | null

required

Maximum number of times the discount can be redeemed.

redemptions_count

integer

required

Number of times the discount has been redeemed.

organization_id

string

required

The organization ID.

Examples:

"1dbfc517-0bbf-4301-9ba8-555ca42b9737"

products

DiscountProduct · object[]

required

List Discounts

Update Discount

import { Polar } from "@polar-sh/sdk";

const polar = new Polar({
  accessToken: process.env["POLAR_ACCESS_TOKEN"] ?? "",
});

async function run() {
  const result = await polar.discounts.create({
    duration: "once",
    type: "fixed",
    basisPoints: 449604,
    name: "<value>",
    organizationId: "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
  });

  // Handle the result
  console.log(result);
}

run();

{
  "duration": "once",
  "type": "fixed",
  "amount": 123,
  "currency": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "modified_at": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "metadata": {},
  "name": "<string>",
  "code": "<string>",
  "starts_at": "2023-11-07T05:31:56Z",
  "ends_at": "2023-11-07T05:31:56Z",
  "max_redemptions": 123,
  "redemptions_count": 123,
  "organization_id": "1dbfc517-0bbf-4301-9ba8-555ca42b9737",
  "products": [
    {
      "metadata": {},
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "recurring_interval": "month",
      "is_recurring": true,
      "is_archived": true,
      "organization_id": "<string>"
    }
  ]
}

General

Core API

Customer Portal API

Webhook Events

OAuth 2.0 API

Create Discount

Authorizations

Body

Response