Docs home

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/promocode
Create 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".

BodyJSONString
unique_code_countintegerrequired
How 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":

BodyJSONString
promo_code_typestringrequired
promo_code_discount (a normal promo code), promo_code_cashback (cashback code) or unique_code (a batch of single-use codes).
promo_code_textstringrequired
The code learners type, letters and digits only. For unique_code it is the prefix of the generated codes.
discountintegerrequired
Discount in percent, 0 to 100.
max_discount_amountintegerrequired
Maximum discount amount, in the organization's base currency.
Description shown with the code.
promo_code_start_timestringrequired
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.
promo_code_end_timestringrequired
Last valid day, same format. Valid until the end of that day.
mapping_detailsarrayOne of the two mappings
Courses and organizations the code applies to (fields below).
subscription_mapping_detailsarrayOne of the two mappings
Membership plans the code applies to (fields below).
Discount per currency for international selling: objects with currency_id, discount and max_discount_amount.
Discount in percent for USD prices. Default 0.
Maximum USD discount. Default 0.
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.
1 shows the code on the website checkout.
1 shows the code in the app checkout.
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.
Response200application/json
codeinteger
Example: 200
messagestring
Example: Success
promo_codesobject[]
Show child attributesHide child attributes
Example: 33581
Example: unique_code
Example: 9867
Example: 80
Example: DEMO UNIque Code
Example: 1671173789
Example: 16 Dec 2022
Example: 28 Dec 2022
Example: 80

Notes:

  • 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_visibility and app_visibility default to 0 for 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.

Updated yesterday

Ask AI