PUQ Mautic

Promo Code API

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

Description

 Order now | Dowload | 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

Order now | Dowload | FAQ

config.png

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

Promo Code Sets.png

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:

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

Add/Edit/Delete Promo Set

Promo Code Sets Add.png

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:

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)

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.

edit promo set.png

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.

edit.png

 

Delete Promo Set

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

edit promo set.png

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

promo delete.png

 

API requests

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:

edit promo set.png

promo url 3.png

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:

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

To get a generated link:

edit promo set.png

promo url 3.png

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.