{{domainAddress}}/promoCode/test
This function will validate the promo code that the user enters, and, if valid, will respond with campaign details. The app will need to inspect these details to decide if a valid promo code is applicable (can be used) on the UI in which it was entered.
Revisions:
- On March 30, 2020:
- There is a minimum credit card charge that Stripe will allow to be processed. That minimum is $1.00 total. If a discounted sale price reduces the final charge to less than $1.00, the charge will be rejected.
- To compensate for this, we have created these rules to follow when calculating taxes and fees on discounted sales.
- if the sale price = $0.00; no fees are to be charged.
- if the sale price > $0.00 and sale price + taxes + fees < $1.00 then reduce sale price to $0.00 and follow rule 1.
- otherwise, continue to charge taxes and fees (as applicable) as we currently do.
- On July 1, 2024, we altered the required headers for each post. Please see the updated documentation for authentication.
Headers
| Header | Content |
| Content Type | application/json |
| Authorization | Bearer {{ID token}} |
| App-Id | {{API key provided by Mosaic}} |
| Device-Id | {{Advertising ID from the initial installation of this app}} |
| Request-Date | {{ISO 8601 date and time format in UTC}} |
Body
Variable Contents
| Parameter | Description |
{{clientId}} | Is provided by CWF for the app project and will be consistent throughout all API calls that require this ID. Type: String; Required |
{{promoCode}} | Provided by the app input form. Type: String; Required ; Max Length: 10 chars |
{{userId}} | Available from getUser() response data.Type: String; Required |
{{locationId}} | This optional parameter is needed only when testing from the checkout screen. Our API needs to know where the product is being purchased, in order to ensure validation on the server side. Type: String; Optional This parameter is not required from registration or profile screens. |
{
"clientId":"{{clientId}}",
"promoCode":"{{promoCode}}",
"userId":"{{userId}}",
"locationId": "{{locationId}}",
}
Example
Headers
App-Id: 5***9-d**3-4**8-b**1-b3***dac
Device-Id: a4***cb-d***5-4***f-8***c-84***75
Request-Date: 2024-07-02T19:59:20.815Z
Content-Type: application/json
Authorization: Bearer eyJraWQiO...aLxlc6PCgQ
Body
{
"clientId":"1f6w1jh6ls3mb",
"promoCode":"SL838F22",
"userId":"03af191d-70d2-472e-9ac0-149cx2437f9d",
"locationId":"asldkfje83lsjf"
}
Response
{
"errors": [],
"warnings": [
"Validator: 3 values were removed from the provided request data"
],
"notices": [],
"data": {
"valid": true,
"promoCodeToken": "TOKEN_GOES_HERE",
"campaign": {
"active": true,
"activatedBy": "3132067a-1105-4961-bd73-e3eefec65b6e",
"data": {
"offer": false,
"adminUI": "single-wash-discount",
"notification": {
"receiver": "A message to the person who applies the promo code to their account",
"sharer": "A message to the sharer, for promos that are assigned to customers"
},
"criteria": [],
"offerDetails": {},
"name": "Dollar Discount Single Sale Test 1",
"description": "This promo code provides a dollar discount, and has no limits: unlimited client use; unlimited customer use; same promo code can be used by all customers.",
"appUIs": [
"checkout"
],
"participating": [
"cwc4r1jmrzem8w",
"byg0ly1k19a5c6b",
"1i4lr07k76ctbyh",
"cwc91jmi2ku5y" ],
"promoCode": {
"perUser": false,
"customerUseageQty": 0,
"campaignUseageQty": 0,
"type": "global"
},
"type": "single_wash_discount",
"rewards": {
"receiver": {
"payout": {
"persistence": 1,
"applies": [
"directSale3",
"directSale2",
"directSale4",
"directSale5"
],
"type": "discount-dollar",
"value": "5.00",
"rewardQty": 0
}
}
}
},
"activationDate": 1584704210493,
"offer": false,
"archive": false,
"name": "Dollar Discount Single Sale Test 1",
"campaignId": "sampleId-000006",
"clientId": "d7dkq1jnxfa52o",
"type": "promo_code"
}
}
Developer:
New:data.promoCodeToken must be included as a parameter when submitting a transact request that includes a promoCode value.
Keep in mind that promo code types will vary, and that some promo codes can only be used on registration/profile screens, and others can only be used at the time of purchase. Where a promo code can be used will be defined within the data.appUIs array. Options are:
- “register”
- “profile”
- “checkout”
The data.valid value will determine if the promo code entered is valid. If it is not valid, an error will be provided with a message to present to the user.
Determining where a promo code can be used will require design descriptions.
Payout Variations
Within the rewards.sender and rewards.receiver objects, the payout object type and structure will vary. These are the variations your team can expect to see.
Developer: payout object type may change, but for each type, the object structure will be consistent.
Loyalty Point Rewards
If the recipient is to receive loyalty points as a reward, the payout object will specify “loyalty” as the type of reward, and will include:
- the number of loyalty points to add to the customer’s account (“value”);
- the loyalty program that should be updated (“program”);
- how many times the customer can use the code(s) from this campaign (“rewardQty”).
"payout": {
"type": "loyalty",
"value": "5000",
"program": "loyaltyProgram1",
"rewardQty": 1
}
Dollar Discount Reward
If the recipient is to receive a dollar value discount, the payout object will specify “discount-dollar” as the type of reward, and will include:
- the dollar value to be deducted from the sale price (“value”);
- a list of sale items to which the discount may be applied (“applies”);
- how many pay cycles the discount will be applied in the event of a subscription purchase (“persistence”).
- a value of 0 (zero) will represent a never ending discount;
- revision: if this is a never ending discount, the persistence property will not exist in the object.
- if persistence = 0, this is an error on the payout object creation from the front end, and the value should be changed to 1.
- how many times the customer can use the code(s) from this campaign (“rewardQty”).
"payout": {
"type": "discount-dollar",
"value": "5.00",
"applies":[
"singleSale1",
"singleSale2",
"subscriptionSale1"
],
"persistence": 1,
"rewardQty": 1
}
Percentage Discount Reward
If the recipient is to receive a percentage discount, the payout object will specify “discount-percent” as the type of reward, and will include:
- the percentage to be deducted from the sale price (“value”);
- a list of sale items to which the discount may be applied (“applies”);
- how many pay cycles the discount will be applied in the event of a subscription purchase (“persistence”).
- a value of 0 (zero) will represent a never ending discount;
- revision: if this is a never ending discount, the persistence property will not exist in the object.
- if persistence = 0, this is an error on the payout object creation from the front end, and the value should be changed to 1.
- how many times the customer can use the code(s) from this campaign (“rewardQty”).
"payout": {
"type": "discount-percent",
"value": "5.0",
"applies":[
"singleSale1",
"singleSale2",
"subscriptionSale1"
],
"persistence": 1,
"rewardQty": 1
}
Free Product Reward
If the recipient is to receive a free product, the payout object will specify “product” as the type of reward, and will include:
- the sale ID of the free item (“value”);
- how many of the items to deliver to the customer account (“productQty”);
- a list of backup saleIDs that are to be tested in sequence in the event a location does not offer the primary reward (“alternates”);
- how many times the customer can use the code(s) from this campaign (“rewardQty”).
"payout": {
"type": "product",
"value": "directSale1",
"productQty": 1,
"alternates": [
"directSale3",
"directSale4"
],
"rewardQty": 1
}
