Create Unique Code
Generates a batch of single-use unique codes that share a prefix, each giving the same discount on selected courses or membership plans. Use it to hand out one personal code per learner, partner or voucher.
POST
/promocodeCreate Unique Code
curl --request POST \
--url 'https://<your-api-host>/nuSource/api/v1/promocode' \
--header 'APIKEY: <your-api-key>' \
--header 'ORGID: <your-org-id>' \
--form 'JSONString={"promo_code_type":"unique_code","promo_code_text":"9867","discount":"80","max_discount_amount":"100","promo_code_description":"DEMO UNIque Code","mapping_details":[{"package_id":1370,"institution_ids":[],"organization_ids":[212]}],"promo_code_start_time":"16 Dec 2022","promo_code_end_time":"28 Dec 2022","usd_discount":"80","unique_code_count":"10"}'{
"code": 200,
"message": "Success",
"promo_codes": [
{
"promo_code_id": 33581,
"promo_code_type": "unique_code",
"promo_code_text": "9867",
"discount": "80",
"max_discount_amount": "100",
"promo_code_description": "DEMO UNIque Code",
"mapping_details": [
{
"package_id": 1370,
"institution_ids": [],
"organization_ids": [
212
]
}
],
"promo_code_creation_time": 1671173789,
"promo_code_start_time": "16 Dec 2022",
"promo_code_end_time": "28 Dec 2022",
"usd_discount": "80",
"max_usd_discount_amount": null
}
]
}Access: Institute admins, plus custom roles that can manage promo codes.
Request body: form-data with one field, JSONString, containing this JSON. Use promo_code_type: "unique_code".
Body
JSONStringHow many codes to generate, up to 10,000. Each code is the prefix (
promo_code_text) followed by a random 6-digit number, e.g. CODE794607.All other fields are the same as for "Create Promo Code":
Body
JSONStringpromo_code_discount (a normal promo code), promo_code_cashback (cashback code) or unique_code (a batch of single-use codes).The code learners type, letters and digits only. For
unique_code it is the prefix of the generated codes.Discount in percent, 0 to 100.
Maximum discount amount, in the organization's base currency.
Description shown with the code.
First valid day, as
DD Mon YYYY (e.g. 16 Dec 2022), in your account's time zone. Valid from the start of that day.Last valid day, same format. Valid until the end of that day.
Courses and organizations the code applies to (fields below).
Membership plans the code applies to (fields below).
currency_detailsarray
Discount per currency for international selling: objects with
currency_id, discount and max_discount_amount.usd_discountinteger
Discount in percent for USD prices. Default
0.max_usd_discount_amountinteger
Maximum USD discount. Default
0.system_usageinteger
Total number of times the code can be used.
0 means no limit.user_usageinteger
Times one learner can use it.
0 means no limit. Must not be more than system_usage.website_visibilityinteger
1 shows the code on the website checkout.app_visibilityinteger
1 shows the code in the app checkout.expiry_visibilityinteger
1 (default) shows the expiry date to learners.Fields in each mapping_details object:
| Name | Required | Type | Description |
|---|---|---|---|
| package_id | Yes | integer | Course ID (bundle_id). Get it from "Institution Course Bundles". |
| organization_ids | Yes | array of integers | Organizations where the code works for this course. |
Fields in each subscription_mapping_details object:
| Name | Required | Type | Description |
|---|---|---|---|
| subscription_plan_id | Yes | integer | Membership plan ID. |
| organization_ids | No | array of integers | Organizations where the code works. Defaults to every organization that offers the plan. |
Response
codeinteger
Example:
200messagestring
Example:
Successpromo_codesobject[]
Show child attributesHide child attributes
promo_codes.promo_code_idinteger
Example:
33581Example:
unique_codeExample:
9867promo_codes.discountstring
Example:
80Example:
100Example:
DEMO UNIque Codepromo_codes.mapping_detailsobject[]
Show child attributesHide child attributes
Example:
1370Example:
1671173789Example:
16 Dec 2022Example:
28 Dec 2022promo_codes.usd_discountstring
Example:
80Notes:
- Each unique code can be used once. A learner whose payment with the code is still pending can retry with the same code on the same course.
website_visibilityandapp_visibilitydefault to0for unique codes, so they are not advertised at checkout.- Fails with "Cant allocate Unique code range exhausted" if you ask for more than 10,000 codes or the prefix has run out of free numbers.
- Rate limit: 30 requests per minute; going over locks you out for 30 minutes.