There’s a lot to break down when viewing the JSON Request Reference data. Consult the information below to help gain a better understanding of what you can glean from this information.
Underneath the JSON data, you’ll find the Campaign Results section. Rules that fired in the call will have a green checkmark while rules that did not fire will have a red x. This doesn’t indicate that the response was not as expected, it just means that the conditions for the rules with Xs were not met for that specific customer and API call.
This information shows identifying data that comes from the machine that sent this call, such as the POS, Virtual Terminal, etc. This will have information such as the brand, IP Address, etc. The information that displays here will vary based on how your brand is configured.
Note that although this section may not be useful for debugging campaigns, it can be useful for debugging API calls.
The header contains data from the fields provided as well as some fields supplied by Clutch. The four authentication headers: Authorization, Brand, Location, and Terminal are required for a successful call. The fields customRequestId and externalTransactionId are best practice requirements for POS and Ecommerce integrations.
The customRequestId used for idempotence and is generated on the brand side as a unique id for each transaction sent to Clutch.
The externalTransactionId is used as a cross reference between the brand’s system and the Clutch transaction. It’s most commonly provided as the POS check number or Ecommerce order ID.
Below is an example of Header Data for a checkout.
“X-Unique-ID”: “49A5DDDA:DA21_0AB50004:01BB_64301DEB_5883DEE:7914″
“Accept”: “*/*”
“User-Agent”: “PostmanRuntime/7.31.3″
“Connection”: “close”
“Host”: “api-stage.clutch.com”
“terminal”: “POSTM7402WS”
“Accept-Encoding”: “gzip, deflate, br”
“Authorization”: “*****”
“X-HAProxy-Forwarded-For”: “73.165.221.218″
“Cache-Control”: “no-cache”
“customRequestId”: “dfj435q4ruao-afdajeah-2343jefa”
“Postman-Token”: “e5296eb4-b4eb-402c-86c2-95cd776d939d”
“externalTransactionId”: “checkoutExample1″
“Content-Length”: “509″
“brand”: “Post7402″
“Location”: “PostmanCollection”
This information was sent to Clutch by the device that sent this call. Key factors to consider when reading the the Request Data include:
isSetup: false
This means that this is a final checkout, not a setup. If it were a setup call, the isSetup:true would be present instead.
returnBalanceMutations: true
This will result in Clutch sending back the campaign-determined balance changes.
returnBalances: true
This will result in Clutch returning any balances on card upon finalization (current balances).
cardNumber:
This is required for all “member or identified” checkouts, but can be null to send an anonymous checkout. The card number is how you can identify your customer.
{
“cardNumber”: “1118220109249362″,
“isSetup”: false,
“returnBalances”: true,
“returnBalanceMutations”: true,
“forcePinValidation”: false,
“products”: [
{
“sku”: “thing01”,
“amountPurchased”: 1,
“unitPrice”: 12,
“note”: “”
},
{
“sku”: “thing02”,
“amountPurchased”: 2,
“unitPrice”: 24,
“note”: “”
},
{
“sku”: “thing03”,
“amountPurchased”: 3,
“unitPrice”: 36,
“note”: “”
}
]
}
This information is what Clutch sends back to the device. Key factors to consider when reading the Response Data include:
checkoutTotalBeforeDiscount
This shows the total of the checkout before any discounts are applied.
totalDiscount
If a discount was applied, this shows what it was.
responseMessages
If any were present, the response message will display here.
balances
This shows all balances on the card at the time of the call. If the call is checkoutSetup, balances reflect the pre-finalization balance. If the call is a finalized checkout, the balances are post-finalization.
balanceMutations
Balance Mutations show any campaign results that change a balance whether for earn, burn, convert to reward, discount or choice options. If a balance mutation contains isDiscount: true, the order or item should be discounted by that amount. There may be more than one.
isDiscount: true
Discounts will be called out within the response and will stipulate isDiscount: true when applicable. When Clutch returns a balance mutation with the isDiscount: set to true, it indicates the sending system should adjust the check to apply the indicated discount.
{
“transactionId”: “4c8faf53-ee8e-4e08-92fd-4d65325f6205″,
“cardNumber”: “1118220109249362″,
“checkoutTotalBeforeDiscount”: 168.00000,
“totalDiscount”: 5.00000,
“responseMessages”: [],
“balances”: [],
“balanceMutations”: [
{
“campaignRevisionUUID”: “058d3b00-c299-11ed-8f27-7d9a4e3c65d9”,
“campaignUUID”: “f7bde238-2163-4314-854e-a5b2de6c4ec8”,
“campaignRuleUUID”: “d8e59111-3fac-4682-831e-0633323821b3”,
“campaignResultUUID”: “d9fa9dcc-18ab-47b2-ae57-c99f8dfb86a9”,
“campaignDescriptiveName”: “5 off 50”,
“amount”: 5.00000,
“isDiscount”: true
}
],
“issuedCouponIDs”: [],
“success”: true,
“requestRef”: “4c8faf53-ee8e-4e08-92fd-4d65325f6205”