Docs home

Create Promo Code

Creates a promo code that gives learners a percentage discount on selected courses or membership plans for a date range. Use it to set up a campaign code such as `DIWALI20`.

POST/promocode
Create Promo 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":"promo_code_discount","promo_code_text":"PROMO212","discount":"40","max_discount_amount":"100","promo_code_description":"PROMOCode DESCRIPTION","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":"40"}'
{
  "code": 200,
  "message": "Success",
  "promo_codes": [
    {
      "promo_code_id": 33561,
      "promo_code_type": "promo_code_discount",
      "promo_code_text": "PROMO212",
      "discount": "40",
      "max_discount_amount": "100",
      "promo_code_description": "PROMOCode DESCRIPTION",
      "mapping_details": [
        {
          "package_id": 1370,
          "institution_ids": [],
          "organization_ids": [
            212
          ]
        }
      ],
      "promo_code_creation_time": 1671173542,
      "promo_code_start_time": "16 Dec 2022",
      "promo_code_end_time": "28 Dec 2022",
      "usd_discount": "40",
      "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: "promo_code_discount" for a normal 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: 33561
Example: promo_code_discount
Example: PROMO212
Example: 40
Example: PROMOCode DESCRIPTION
Example: 1671173542
Example: 16 Dec 2022
Example: 28 Dec 2022
Example: 40

Notes:

  • Errors: "This Promocode is already taken." (the text is already used in your institute), "Invalid discount value please put value between 0 to 100", "Invalid mapping details" (no course or membership mapping, or a course mapping without package_id and organizations), "System usage limit must be greater than or equal to per-user usage limit.".
  • website_visibility and app_visibility default to 1 for promo and cashback codes.
  • Rate limit: 30 requests per minute; going over locks you out for 30 minutes.

Updated yesterday

Ask AI