Promo Code API

The Promo Code API extension helps with creation of promo codes from the API.

• Description
• Configuration
• Promo Sets
• Add/Edit/Delete Promo Set
• API requests
• Secure, Unique Generated Links

Description

PUQ Customization module WHMCS

 Order now | Download | FAQ

The 'Promo Code API' extension revolutionizes the creation of promo codes by offering advanced API configurations tailored to your needs. This extension includes:

1. Promo Code Template Creation: Effortlessly craft custom promo code templates perfectly suited to your promotional strategies. These templates serve as the foundation for generating promo codes using the API.
2. URL Generation for cURL Requests: Upon creating a promo code set, the extension generates a unique URL. By making a simple cURL request to this link you receive an automated response containing the generated promo code within your WHMCS platform.
3. Integration with Other Services: The extension allows seamless integration of the promo code creation process into your WHMCS system from external services using straightforward cURL requests. Now, you can easily generate promo codes within your WHMCS system from external sources with specifically cURL requests, streamlining the entire process for utmost convenience and speed.

The 'Promo Code API' extension streamlines the promo code generation process, empowering seamless integration with external systems. Generate promo codes effortlessly within your WHMCS system from external sources, facilitating a swift and efficient workflow.

Configuration

PUQ Customization module WHMCS

 Order now | Download | FAQ

Enabled - Enabling or disabling all custom functions of this extension affects the automation and visibility of its features in the client area. When extension disabled, the automation capabilities and related features provided by the extension will not be active or visible to clients. However, as an administrator, you will still have access to configure and utilize the extension's functionalities through the administration interface. This gives you the flexibility to control the visibility and automation aspects of the extension based on your specific needs and preferences.

Json Pretty Print - The "Json Pretty Print" option enables the JSON_PRETTY_PRINT function, which formats the response, following a CURL request, into a neatly organized JSON structure. When this option is activated, the output data received after the CURL request will be formatted considering the nested objects and arrays, making it easier to comprehend and analyze.

Promo Sets

PUQ Customization module WHMCS

 Order now | Download | FAQ

Add New Promo Set - upon clicking this button, a template for creating a Promo Set is opened. For more information about creating/editing/deleting promo sets, please refer to the following link: Click here

Table:

• ID: Promo Set ID
• Set Name/ API Ip Address: This cell contains the Promo Set name, API IP Address, and URL for cURL requests. 
• Promo Code Type: Indicates the types of promo codes that can be created in the future. These may include: Percentage, Fixed Amount, Price Override, Free Setup.
• Value: Specifies the value to be set in the created promo codes.
• Recurring: Indicates the discount will apply or not to renewal invoices. If enabled, specifies the frequency of use.
• Max Uses: Specifies the maximum number of times this promo code can be used, i.e., the number of clients who can use it.
• Start Date: The date when the promo code starts to be effective.
• Expiry Date: The date when the promo code expires.
• Notes: Admin notes.

To open the editing template, click on either the set name or the ID.

Add/Edit/Delete Promo Set

PUQ Customization module WHMCS

 Order now | Download | FAQ

Add Promo Set

Click Add new Promo Set at the top of the Promo Sets page.

Set Name: Enter a set name.

API Ip Address: Enter Ip adress for API connection.

Promo Code Type: Choose one of the four promotion types:

• Percentage — Discount by a percentage of the original price.
• Fixed Amount — Discount a specified amount from the original price.
• Price Override — Changes the product price to this value. Use this to offer a consistent discount across multiple billing cycles.
• Free Setup — Discount any setup fee from the original price.

Recurring: To have the discount only apply to the first invoice, do not check it. When you check this, the discount will apply to renewal invoices.

Set Recur For to 0 for all future renewals to discount, or enter a different number to specify how many cycles the discount lasts for. This is in addition to the initial invoice for the product. If you wish to provide a discount 6 times, enter 5 in the recurring box.

Value: enter the amount of the discount in positive numbers (up to 2 decimals) only.

Applies To: Select the products, addons, and domain TLDs that the promotion applies to and what billing cycles or registration periods the discount requires. These should match those of your products.

Your can press Ctrl+click to select multiple entries.

Requires: By selecting products from Requires, you can stipulate which products or services the client must also have in their shopping cart before applying the discount. You can use this to offer "buy x get y half price" promotions.

Also allow existing products in account to qualify for promotion allows the system to include active products that the client already owns in the promotion criteria.

Billing Cycles: Selecting a billing cycle denotes that the promo code can be applied to products with specified billing cycles only.

Optionally, set the start and expiration dates. If you use one or both of these settings, the coupon will only start working after the start date and will stop working at expiration.

The expiry date must be a date in the future.
The expiry date must be later than the start date.

For Maximum Uses, enter the number of uses that you want to allow.

The number of times that customers have used the promotion will display below this setting.
For unlimited uses, enter 0.

Use the following checkboxes to specify who can use the promotion:

Lifetime Promotion: Discounted pricing is applied even on upgrade and downgrade orders in the future regardless of settings like max uses, expiry, etc;

Apply Once: Apply only once per order (even if multiple items qualify)

New Signups: Only new clients can use the promotion.

Apply Once / Client: If a client has an existing active order that uses this promotion, they will not be able to use the code a second time.

Existing Client: Only existing clients with one or more active orders can use the promotion.

Upgrades/Downgrades:

(For more info read a WHMCS documentation: Click here)

• Select Products/Services or Configurable Options as the Upgrade Type.
  

• Products/Services:

  • Select Products/Services as the Upgrade Type.

  • Use Type, Recurring, and Value fields to specify the value of the discount and how long it lasts.

  • Use Applies To to select which products to apply the promotional code to. The client will receive the discount when upgrading to this product.

  • For upgrades and downgrades, use Requires slightly differently. It restricts which products clients can upgrade. For example, they can upgrade from a selected product to this product and receive a discount, but not upgrade from an unselected product and receive a discount.

• Configurable Options
  • To offer discounts to clients for configurable options, select Configurable Options as the Upgrade Type.
  • Use Upgrade Discount to specify the discount value as a percentage or fixed amount for the configurable options.
  • Then, use Config Options Upgrades to select which option this discount applies to.
  • If you use the main Type, Recurring, and Value at the top of the page, the system will apply a discount to the parent product as well as to the configurable option. Leave this blank to only apply the discount to the configurable option.

Notes: In the admin notes section, add information that admins may need about the promotion.

Edit Promo Set

Clicking on the set name or ID opens a template for editing a Promo Set.

After opening the template for editing a Promo Set, you can reconfigure or amend the set.

It's important to note that any promo codes generated prior to these changes to the set of promo codes will not be altered.

 

Delete Promo Set

Clicking on the set name or ID opens a template for editing a Promo Set.

After opening the template for editing a Promo Set, you can click on "Delete Set" for deletion a set.

 

API requests

PUQ Customization module WHMCS

 Order now | Download | FAQ

To simply generate a promo code, use the link generated when creating a set to get the required promo code by invoking the cURL command:

• Clicking on the set name or ID opens a template for editing a Promo Set.

• Copy an URL next to IP Adress"

Method: POST

Example:

curl \
-X POST YOUR_URL_FROM_SET

Response example:

{
    "id": 61,
    "code": "XABKKA",
    "type": "Percentage",
    "recurring": 1,
    "value": "25.50",
    "cycles": "Quarterly,Semi-Annually,Annually,5Years,6Years,7Years",
    "appliesto": "12,40,18",
    "requires": "13,50,D.ua",
    "requiresexisting": 0,
    "startdate": "2024-01-01",
    "expirationdate": "2024-01-27",
    "maxuses": 11,
    "uses": 0,
    "lifetimepromo": 0,
    "applyonce": 1,
    "newsignups": 1,
    "existingclient": 0,
    "onceperclient": 0,
    "recurfor": 0,
    "upgrades": 1,
    "upgradeconfig": "a:4:{s:5:\"value\";s:2:\"11\";s:4:\"type\";s:7:\"product\";s:12:\"discounttype\";s:10:\"Percentage\";s:13:\"configoptions\";a:2:{i:0;s:2:\"11\";i:1;s:2:\"13\";}}",
    "notes": "TEST TEST"
}

 

You can also include some additional data if needed:

name - Adds the beginning of the promo code for clarity regarding its set association.

value - Specifies the value for promo codes.

promo_code_type - Specifies the discount type for promo codes, which can be:

• Percentage
• Fixed Amount
• Price Override
• Free Setup

start_date - Specifies the promo code's access start date.

expiry_date - Specifies the promo code's access end date.

notes - Adds notes from the author.

Method: POST

Example:

curl \
-X POST YOUR_URL_FROM_SET \
-d "name=puqcloud.com&\
value=50&\
promo_code_type=Fixed Amount&\
start_date=2024-01-01&\
expiry_date=2024-12-30&\
notes=TEST FOR DOCUMENTATION"

Response example:

{
    "id": 66,
    "code": "puqcloud.com-PFC",
    "type": "Fixed Amount",
    "recurring": 1,
    "value": "50.00",
    "cycles": "Quarterly,Semi-Annually,Annually,5Years,6Years,7Years",
    "appliesto": "12,40,18",
    "requires": "13,50,D.ua",
    "requiresexisting": 0,
    "startdate": "2024-01-01",
    "expirationdate": "2024-12-30",
    "maxuses": 11,
    "uses": 0,
    "lifetimepromo": 0,
    "applyonce": 1,
    "newsignups": 1,
    "existingclient": 0,
    "onceperclient": 0,
    "recurfor": 0,
    "upgrades": 1,
    "upgradeconfig": "a:4:{s:5:\"value\";s:2:\"11\";s:4:\"type\";s:7:\"product\";s:12:\"discounttype\";s:10:\"Percentage\";s:13:\"configoptions\";a:2:{i:0;s:2:\"11\";i:1;s:2:\"13\";}}",
    "notes": "TEST FOR DOCUMENTATION"
}

Errors:

- The expiry date must be a date in the future.
- The expiry date must be later than the start date.

 

If you send a request using the GET method, it will return information about the network:

Method: GET

Example:

curl \
-X GET YOUR_URL_FROM_SET

Response example:

{
    "id": 1,
    "name": "test",
    "api_ip_address": "77.87.125.4",
    "api_key": "XJCRRFKY9GZ55CDR9H98NFJND",
    "promo_code_type": "Percentage",
    "recurring": 1,
    "recur_for": 0,
    "promo_value": 25.5,
    "applies_to": [
        "12",
        "40",
        "18"
    ],
    "requires": [
        "13",
        "50",
        "D.ua"
    ],
    "requires_existing": 0,
    "cycles": [
        "Quarterly",
        "Semi-Annually",
        "Annually",
        "5Years",
        "6Years",
        "7Years"
    ],
    "start_date": "2024-01-01",
    "expiration_date": "2024-01-27",
    "max_uses": 11,
    "lifetime_promo": 0,
    "apply_once": 1,
    "new_signups": 1,
    "once_per_client": 0,
    "existing_client": 0,
    "upgrades": 1,
    "upgrade_type": "product",
    "upgrade_discount_type": "Percentage",
    "upgrade_value": "11",
    "config_option_upgrades": [
        "11",
        "13"
    ],
    "notes": "TEST TEST",
    "url": "XJCRRFKY9GZ55CDR9H98NFJND-1-7dc8108e1a78c37c136732d464208a22"
}

Secure, Unique Generated Links

PUQ Customization module WHMCS

 Order now | Download | FAQ

To get a generated link:

• Clicking on the set name or ID opens a template for editing a Promo Set.

• Copy an URL next to IP Adress"

Link Security and Uniqueness Basics

The uniqueness and security of the generated links lie in their generation process. The link is created using an API key generated upon set creation, the set's ID, and a special key generated from your unique WHMCS code, the set's API key, and the IP address you specified during set creation.

Furthermore, a verification code is also generated using the unique WHMCS code, the set's ID, the set's API key, and the IP address.

Due to this complex combination of parameters, each link generated for every set is unique and is tied to the specific WHMCS instance, ensuring both individuality and security.

Also this ensures that only users with the designated IP address can access the link associated with their set, enhancing its security measures.