zendit Promotions

About Promotions

Mobile Carriers frequently run promotions to give extra value for a top up performed for some values during the period of a promotion. Zendit has added a new API endpoint to discover upcoming, active and expired promotions to help marketing efforts to drive traffic. Promotions are provided by the carrier at no extra cost.

The Promotion API

Head over to the zendit API to see the new endpoints for promotions. With just a _limit and _offset, you can retrieve the entire list of promotions.

Promotions can be filtered to narrow down the results to the following parameters:

• Brand: the mobile carrier for the promotion – example Tigo
• Country: the destination country for the promotion – example GT
• Language: the language to retrieve for the information about the promotion – example en
• Region: the region to search for the promotion – example Africa
• Status: the current status of the promotion – example pending

When using the filters to narrow in on specific promotions of interest, be mindful of the parameters being sent. Sending parameters that mismatch such as the region as Africa but the Country as GT will result in an empty list.

For the Language parameter, US English is the default language that will be returned. In some cases Spanish (es) may be available for the promotion. Sending a language that is not available will return US English for the description by default.

The Region parameter is currently case sensitive. Sending africa will result in an empty list but sending Africa will return the list of promotions in Africa.

The status of the promotion determines whether it’s upcoming, currently running or has expired. The statuses are as follows:

• Pending: the promotion details are available but the promotion has not started yet
• Active: the promotion is currently running
• Expired: the promotion has expired and is no longer available

Handling the Promotion Response

The promotion endpoint will provide the list of promotions (or an individual promotion if retrieving the promotion by ID) with the following information:

• Brand: the carrier for the promotion – e.g. Tigo
• Country: the destination for the promotion – e.g. GT
• CreatedAt: The date that the promotion was added into Zendit
• Description: The description of the promotion with a short description, language and the terms and conditions of the promotion set by the carrier
• EndAt: The date that the promotion is set to expire by the carrier, value is in UTC Time
• ID: The unique ID of the promotion in the promotion system and may be used to retrieve a specific promotion from the promo endpoint
• Offer Ids: the list of offers that the promotion will be applied to.
• smsBonusNumber: The number of bonus SMS messages included in an offer (if applicable)
• smsMultiplier: A multiplier to the base number of SMS messages in an offer (if applicable)
• valueBonus: A bonus amount added to the base value of an offer (if applicable)
• valueMultiplier: A multiplier to the base value in an offer (if applicable)
• voiceBonus: A bonus amount of minutes added to the base number of minutes in an offer (if applicable)
• voiceMultiplier: A multiplier to the base number of minutes in an offer (if applicable)
• dataBonusGB: A bonus amount of data (in GB) added to the base amount of data in an offer (if applicable)
• dataMultiplier: A multiplier to the base amount of data in an offer (if applicable)
• minValue: The minimum destination value required for the promo if applicable (for guidance on open range offers)
• maxValue: The maximum destination value required for the promo if applicable (for guidance on open range offers)
• Regions: The regions that the promotion is available in.
• StartAt: The date that the promotion is scheduled to start value is in UTC Time
• Status: The current status of the promotion
• UpdatedAt: The last date that information about the promotion was updated

The Description section contains the full information about the promotion. The description value contains a short text about the promotion such as “Double Value.” The terms parameter will contain the full information about the promotion including any bonuses that are delivered with the promotion, and if there are tiers in the promotion based on the value of the topup it will specify these different levels of bonuses. The language parameter will specify the language that the description and terms values are delivered in.

Additionally the offerIds parameter will list out all offers that the promotion applies to, simplifying identifying when a promotion will be applied.

Additional information in the value, voice, data, and SMS bonuses and multipliers will help identify how much from any of these categories the promo will contain.

On offers with open ranges included in a promo, the minValue will specify the amount that the recipient must receive as a minimum amount of their local currency for the promotion to apply. The maxValue will specify the maximum amount of local currency that the promotion will be applied to. Promotions with open range offers with minimums or maximums will include these values. Promotions with only fixed value offers will generally omit these values since the offerIds structure will contain all offers that the promotion is applied to.

Additional Information About Promotions

Zendit cannot guarantee that every product for a carrier and destination will qualify for the promotion and terms, the offer IDs on the promotion will identify which offers the promotion is applicable to.

Promotions are provided by the Mobile Carrier and not by Zendit. This service is for informational and marketing purposes only.