Create a coupon

POST 
https://api.freemius.com/v1/products/{product_id}/coupons.json

Auth:Bearer TokenSCOPE: PRODUCT

Product-scoped API tokens allow you to operate on the product itself. This token usually allows read-only access to the product configuration and write access to several operations on subscriptions, customers, payments, and more. For most SaaS or app integrations, this is the token you will need.

1. Go to the Freemius Developer Dashboard.
2. Open the Settings page of the relevant product.
3. Click the API & Keys tab.
4. Copy the API Bearer Authorization Token from the UI.

---

Create a new coupon.

Alternatively, you can use the Freemius Developer Dashboard.

If you're creating coupon from your SaaS for some specific use case, please be sure to set the plans, redemptions_limit, end_date, and is_one_per_user properties to the appropriate values, to avoid misuse.

Request

Path Parameters

product_id integer<int64>required
The ID of the product.
Possible values: >= 1
Example: 1234

application/json

Bodyrequired

plansstringnullable
Comma separated IDs of plans the coupon would work for. If null, coupon supports all plans.
Example: 123,654,8757
licensesstringnullable
Comma separated licenses quota limits. If null, coupon supports all license limits. 0 is used for an unlimited-site license.
Example: 1,5,10,0
billing_cyclesstringnullable
Comma separated billing cycles. If null, coupon supports all billing cycles. 0 is used for lifetime billing cycle.
Example: 1,12
user_typestring

Default value: all

The user type the coupon is applicable to.

Possible values: [all, new, current, previous, customer, migrated]

codestring
The coupon code.
Example: BLACKFRIDAY2024
discountinteger

The discount amount.

discount_typestring

The type of the discount. "percentage" means the discount is a percentage of the price, "dollar" means the discount is a fixed amount.

Possible values: [dollar, percentage]

start_datestring<date-time>
Date and time from when the coupon will be activated.
Example: 2025-04-01 11:13:28
end_datestring<date-time>
Date and time, after which the coupon will be expired.
Example: 2025-04-30 19:17:21
redemptions_limitintegernullable

The total number of redemptions limit of this coupon.

has_renewals_discountboolean

Whether the coupon also supports discount for renewals or first payment only.

has_addons_discountboolean

Whether the coupon supports discount for add-ons or not.

is_one_per_userboolean

Whether to limit the coupon usage one per user.

is_activeboolean

Whether the coupon is active. Use this flag to temporarily disable the coupon.

Responses

201

The coupon is created.

application/json

Schema

idstring<int64>

The unique identifier of the entity.

Possible values: >= 1

Example: 123456

createdstring<date-time>

The date and time the entity was created, under UTC timezone.

Example: 2025-01-01 00:00:00

updatedstring<date-time>nullable

The date and time the entity was updated, under UTC timezone. If null then the entity was never updated since its creation.

Example: 2025-01-01 00:00:00

entity_idstring<int64>

The ID of the entity the coupon belongs to.

Possible values: >= 1

Example: 12345

entity_typestring

The type of the entity the coupon belongs to.

Possible values: [plugin, store, marketplace]

Example: plugin

plansstringnullable

Comma separated IDs of plans the coupon would work for. If null, coupon supports all plans.

Example: 123,654,8757

licensesstringnullable

Comma separated licenses quota limits. If null, coupon supports all license limits. 0 is used for an unlimited-site license.

Example: 1,5,10,0

billing_cyclesstringnullable

Comma separated billing cycles. If null, coupon supports all billing cycles. 0 is used for lifetime billing cycle.

Example: 1,12

codestring

The coupon code.

Example: BLACKFRIDAY2024

discountinteger

The discount amount.

discount_typestring

The type of the discount. "percentage" means the discount is a percentage of the price, "dollar" means the discount is a fixed amount.

Possible values: [dollar, percentage]

start_datestring<date-time>

Date and time from when the coupon will be activated.

Example: 2025-04-01 11:13:28

end_datestring<date-time>

Date and time, after which the coupon will be expired.

Example: 2025-04-30 19:17:21

redemptionsinteger

The total number of redemptions of this coupon.

redemptions_limitintegernullable

The total number of redemptions limit of this coupon.

has_renewals_discountboolean

Whether the coupon also supports discount for renewals or first payment only.

has_addons_discountboolean

Whether the coupon supports discount for add-ons or not.

is_one_per_userboolean

Whether to limit the coupon usage one per user.

is_activeboolean

Whether the coupon is active. Use this flag to temporarily disable the coupon.

user_typestring

Default value: all

The user type the coupon is applicable to.

Possible values: [all, new, current, previous, customer, migrated]

sourcenumber

The source of the migration data. To get support migrating from other platform please see our documentation.

• 0 - Freemius
• 1 - Other
• 2 - Easy Digital Downloads (EDD)
• 3 - WooCommerce (WC)
• 4 - Rating Widget
• 5 - Gumroad
• 6 - CodeCanyon
• 7 - ThemeForest
• 8 - AppSumo
• 9 - SendOwl
• 10 - WHMCS
• 11 - Lemon Squeezy

Possible values: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]

400

Bad request. The request could not be understood by the server due to malformed syntax or arguments.

application/json

Schema

pathstring

The API request path.

Example: :/products/product_id/users.json

error object

This object contains the error details.

typestring

The type of the error encountered by the server.

Example: UnauthorizedAccess

messagestring

The descriptive error message.

Example: Some error has occured.

codestring

The error code.

Example: unauthorized_access

httpinteger

The HTTP status code returned by the server.

Example: 401

timestampstring

Current timestamp.

Example: Thu, 11 May 2023 11:45:30 +0000

request object

This object sends back the request payload as received by the server (both from path and from body or query).

property name*any

This object sends back the request payload as received by the server (both from path and from body or query).

Example: {"beautify":true,"format":"json"}

401

Unauthorized access error. The request requires authentication but was not provided or the provided authentication does not satisfy the required permissions.

application/json

Schema

pathstring

The API request path.

Example: :/products/product_id/users.json

error object

This object contains the error details.

typestring

The type of the error encountered by the server.

Example: UnauthorizedAccess

messagestring

The descriptive error message.

Example: Some error has occured.

codestring

The error code.

Example: unauthorized_access

httpinteger

The HTTP status code returned by the server.

Example: 401

timestampstring

Current timestamp.

Example: Thu, 11 May 2023 11:45:30 +0000

request object

This object sends back the request payload as received by the server (both from path and from body or query).

property name*any

This object sends back the request payload as received by the server (both from path and from body or query).

Example: {"beautify":true,"format":"json"}

402

The request is missing the specified argument.

application/json

Schema

pathstring

The API request path.

Example: :/products/product_id/users.json

error object

This object contains the error details.

typestring

The type of the error encountered by the server.

Example: UnauthorizedAccess

messagestring

The descriptive error message.

Example: Some error has occured.

codestring

The error code.

Example: unauthorized_access

httpinteger

The HTTP status code returned by the server.

Example: 401

timestampstring

Current timestamp.

Example: Thu, 11 May 2023 11:45:30 +0000

request object

This object sends back the request payload as received by the server (both from path and from body or query).

property name*any

This object sends back the request payload as received by the server (both from path and from body or query).

Example: {"beautify":true,"format":"json"}