The Bidco coupon functionality allows a user to receive and manage coupons from within your app. They can then redeem coupons when making purchases to receive discounts.

The Coupon

Merchants use the Bidco Merchant API to create coupons that provide their customers with some form of discount.

The primary attributes of a PTKCoupon that will be of interest to the user are:

  • id - the identifier for the coupon.
  • MerchantID - the ID of the merchant who provisioned the coupon.
  • Name - the coupon name.
  • Description - a description of the discount being provided.
  • Promotion Code - the promotion code for the coupon.
  • Start Date - the date from which the coupon is valid.
  • End Date - the date the coupon expires.
  • Percentage OR Fixed Discount - The coupon either specify a fixed value discount OR a percentage discount, never both.
  • Usage Count - the number of times that the coupon can still be used.
  • imageUrl - a URL to the coupone image.
  • Products - When specified, this identifies a list of products that the discount applies to.
  • Categories - When specified, this identifies categories of products that the discount applies to.

Managing Profile Coupons

All coupons that have been delivered to the user are stored in the profile.
You can provide the following coupon management functions in your app:

Retrieving Profile Coupons

When a user would like to view the coupons in their profile the following steps are required.

  1. To retrieve all coupons from a user's profile:
PTKCouponManager *couponManager = [[PTKManagerFactory sharedManager] couponManager];
[couponManager allCouponsWithCompletion completion:^(NSOrderedSet coupons, NSError *error) {
	for (PTKCoupon *profileCoupon in coupons) {
		// Display all coupons to user showing coupon fields Name, Description, Promotion Code, Fixed Discount, Percentage Discount
	}    
}];

  1. To retrieve a single coupon from a user's profile using the couponId:
[couponManager couponForCouponId:couponId withCompletion:^(PTKCoupon *coupon, NSError *error) {
	// Display the coupon to user showing coupon fields Name, Description, Promotion Code, Fixed Discount, Percentage Discount and Date period 
}];

Deleting Coupons

[couponManager deleteCoupon:coupon withCompletion:^(NSError *error) {
	if (!error){}
		// Coupon has been removed from the profile
	}	
}];

Retrieving Triggered Coupons

The Bidco system has pre-defined events that trigger the delivery of coupons to users.
Merchants use the Bidco Merchant API to create coupons that they then associate to one of the events.

The following events will trigger the delivery of coupons:

  • Registration: On completion of a user profile registration. (See Profiles for an example)
  • Payment: After successfully paying for a basket of items. (See Payments for an example)
  • Act Scan: After scanning a Bidco tag associated with an Act. (See Acts for an example)
  • Product Scan: After scanning a Bidco tag associated with a Product. (See Products for an example)
  • Basket Scan: After scanning a Bidco tag associated with a Basket. (See Baskets for an example)
  • Catalog Scan: After scanning a Bidco tag associated with a Catalog. (See Catalogs for an example)

Note: The coupons returned during these events are not necessarily applicable to the activity the user is currently busy with. It is not mandatory for the user to redeem any of these coupons during their current purchase.

For each of these events, the coupons are automatically stored in the user's profile but also provided to you so that the coupons can be presented to the user.

The general steps to perform when receiving coupons are:

  1. Obtain the list of coupons:

Since most of the events involve workflows, we will use the example of retrieving coupons from a workflow.

// Scan a tag and retrieve the workflow
// Get the triggered coupons from the workflow
List<Coupon> coupons = workflow.getTriggeredCoupons();
if (!coupons.iSEmpty()) {
	// Display coupons to user
}

Redeeming Coupons

When it comes time to prepare a basket for checkout, the eligible coupons should be made available for selection by the user.

It is possible that a user's profile contains multiple coupons that are redeemable for a single basket. To complicate things, it's also possible to use coupons together in different combinations to provide distinct discounts.
To simplify this process, the Bidco SDK uses a Rules Engine to determine all discounts available for a basket based on the valid, distinct combination of coupons.

Get Available Discounts

Use the PTKCouponManager to obtain a list of possible discounts available for the basket. The PTKDiscount object stores a distinct combination of coupons that provide a specific saving.

[couponManager getApplicableDiscountsForECommBasket:basket coupons:coupons withCompletion:^(NSOrderedSet *discounts, NSError *error) {
    // Obtain the user's selection
}];

Obtain User Selection

A PTKCouponPicker is provided, that you can bind to your UI to simplify user selection of valid coupon combinations. Use the PTKCouponPicker to get a list of CouponState objects, one for each available coupon. The PTKCouponState is a wrapper that contains the Coupon and state information like whether it is currently selected or available for selection.

The user will select one coupon at a time. Each selection will update the picker so that only coupons that can be used in combination with previous selections are made available, until only one discount (coupon combination) has been chosen.


  1. Create a PTKCouponPicker
PTKCouponPicker *couponPicker = [PTKCouponPicker couponPickerWithAvailableCoupons:coupons discounts:discounts ];

  1. Get the list of coupons to display to the user:
NSArray<PTKCouponState> *couponChoices = [couponPicker.getDisplayable;
// Display the choices to the user
[self displayAvailableCouponChoices:couponChoices];

  1. To choose a coupon call the picker's select method:

This will update the state of the coupons based on the currently chosen coupon. The list is updated in-place so there is no need to get the list from the picker again.

[couponPicker selectCoupon:coupon];
// Display available coupons
[self displayAvailableCouponChoices:couponChoices];

  1. To de-select a coupon call the picker's deselect method:

This will update the state of the coupons based on the currently chosen coupon. The list is updated in-place so there is no need to get the list from the picker again.

[couponPicker deselectCoupon:coupon];
// Display available coupons
[self displayAvailableCouponChoices:couponChoices];

  1. To clear all chosen coupons:
// Resets all selected coupons.
couponPicker.resetSelection;
[self displayAvailableCouponChoices:couponChoices];

Checking if User Has Selected a Distinct Discount

To determine if a discount has been selected, you need to check if the user has selected an option for every choice.
The isOptionChosenForEveryChoice method returns 'true' once a single variant has been chosen:

Discount discount = couponPicker.getSelectedDiscount();
if (discount != null) {
	// A discount has been selected by the user and the coupon combination can be applided to the order
}

Apply The Selected Discount To the Basket

The next step is to apply the discount to the basket. See Baskets for how to finalise the basket.