Basic Principles

Order API

The Order API is used to track transactions. All transactions will first register as a “pending” status. Pending transactions will need to be validated in order to grant cashback.

Order Process Flow

1. ShopBack will redirect to the merchant website with affiliate parameters such as utm_source=shopback. One key parameter is transaction_id. Merchants may choose to add or change any of the parameter names to suit their preferences.
   1. Example: www.shopback.my/merchantA -> www.merchantA.com/?utm_source=shopback&transaction_id=`{transaction_id}`
2. Merchant identifies the traffic coming from ShopBack and records transaction_id.
3. When users purchase, the merchant will call the Order API webhook and pass the transaction_id along with other parameters such as order_id, product_id, and purchase_amount.
4. The user cashback will be created by ShopBack and the order will be tracked as pending.
5. To approve or confirm the pending cashback, the merchant will have to go through the validation process.

📘

Server-to-server (S2S) Process Flow Diagram

📘

Recommended Precautions

Due to constant merchant updates, it is recommended that merchants store the transaction_id in the database to maintain a temporary transaction_id history. In the event of an Order API outage, the merchant is able to clawback the transaction_id from the order history and reinstate the Order API.

---

Validation API

The Validation API is used to validate Order API transactions with either rejected or approved statuses. Below are the cases of the 2 different statuses.

Transactions that are still in pending status will remain in pending status until a Validation API is given to that particular transaction.

Validation Process Flow

1. Users who transact under ShopBack will have the order_id recorded in the merchant database
2. When the product has been received by the customer and the order has passed the return policy or the customer has returned the product, the merchant may approve or reject the order_id by calling the Validation API.
3. This serves as a feedback loop to ShopBack that the order is applicable for cashback and ShopBack may be able to release the cashback to users or the transaction is rejected entirely.
4. For Item-tracking merchants, partial order approval and rejection are possible using the Validation API.

---

Tracking Methods

ShopBack provides 2 methods of tracking transactions.

Method 1 - Order Tracking

Basic tracking method that only tracks [order_id] and [sale_amount] including any shipping fees exclusion and coupon discounts.

In this method, the merchant only needs to provide the order id and amount values.

Method 2 - Line Item Tracking

ShopBack uses line-item tracking whereby each line item is captured in one line with the quantity amount and amount as line item subtotal amount.

---

For Regional Merchants

ShopBack works with merchants that have a regional presence with multiple websites. For regional merchants, ShopBack will allow customization to have either 1 merchant account or multiple merchant accounts. ShopBack API indicates merchant account as “offer id” and the main parameter is {order_offer_id}. See the examples below:

Example 1

Merchant_A operates www.testshopA.com which has a regional presence and offers customers from any location to purchase Merchant_A services. Therefore, 1 merchant account should suffice, and only 1 {order_offer_id} and 1 {validation_offer_id} will be assigned to Merchant_A.

Example 2

Merchant_B operates www.testshopB.com.my (MY), www.testshopB.sg (SG), www.testshopB.co.id (ID) that is independently operated by local entities. Merchant B then has the following options:

Option A

Merchant B HQ requests 3 merchant accounts and will be assigned 3 {order_offer_id} and 3 {validation_offer_id}. In this case, the 3 APIs can be configured to receive different information and are tailored for local currency and local timezone.

Option B

Merchant B HQ requests only have 1 merchant account with only 1 {order_offer_id} and 1 {validation_offer_id} for all 3 websites. In this case, the API will be configured to capture currency and a standardized timezone.

---

Currency Settings

ShopBack allows the ability to have a single currency account or multi-currency account when operating from 1 website. For example,

• www.testshopA.com allows customers to pay in any currency and therefore is configured as a multi-currency account.
• www.testshopB.com.my only allows customers to pay in MYR and therefore is configured as a single currency account.

The currency setting chosen is for data capturing purposes only and does not mean invoice payment has to be made in that currency. Please discuss this further with your ShopBack representative.

For single currency merchant account

ShopBack will configure the merchant account to accept the desired currency and all {sale_amount} captured will be tracked in that specific currency.

For multi-currency merchant account

ShopBack will configure the merchant account to accept the multi-currency and all {sale_amount} captured will be tracked as a number. The currency used will be determined by the parameter adv_sub5 in the postback.

---

Timezone and Datetime Settings

ShopBack API endpoints are designed to capture postbacks in real-time and are recommended for all merchants to allow ShopBack users to track the cashback with a shorter delay.

For regional merchants that operate multiple websites with a single account, ShopBack allows the merchant to standardize the datetime by adding the datetime parameter to the postback.

ShopBack only has 2 modes for controlling datetime of the conversion or postback.

Mode 1 - No datetime parameter is used in the postback

Mode 1 will track all postbacks in real time and according to the local time zone. This means the datetime captured when the postback is received by ShopBack. This mode is most suitable for local merchants operating a local website.

Example scenario

Transaction datetime = 12:00PM UTC+8

Postback sent datetime = 12:00PM UTC+8

ShopBack user cashback will be recorded as 12:00PM UTC+8

Mode 2 - A datetime parameter added in the postback

By adding the datetime parameter, ShopBack will record the conversion following the datetime value instead and NOT when the postback is received by ShopBack. To use Mode 2 effectively, the merchant should adjust the datetime value to UTC+0.

Example scenario

Transaction datetime = 2023-01-01 12:00PM UTC+8

Postback sent datetime = 2023-01-01 2:00PM UTC+10

In order to capture the transaction at the correct time, datetime=2023-01-01 04:00:00 is added to the postback as this is the correct time at UTC+0 when the transaction takes place.

Basically, if datetime is used, it has to be adjusted to UTC+0 timezone. Please see the below details.