Magic Receipts Postbacks
This page describes how Magic Receipts postback works.
Intro
A user can upload an image of a receipt that contains purchases for multiple items, for example Chocolate and Apples. Use Magic Receipts postbacks to receive notifications on your server whenever the status of each offer item in the receipt changes.
There are four possible statuses:
AWARD_PENDING
APPROVED
REJECTED
MANUAL_REVIEW
Once an offer is APPROVED, it cannot transition to another status.
Setting Up a Postback
In order to receive postbacks for Magic Receipts events, you must set a URL that we should fire within the AdGate dashboard on the Postbacks page.
Log in to the AdGate dashboard and open the Postbacks page.
In the Offer-Specific Postbacks section, click Add Offer Postback and search for "397622", which is the "Shopper Marketing" offer ID.
Enter the URL you would like us to send postbacks to and press Submit.
Example Postback URL: http://yoururl.com/postback/?conversion_id={conversion_id}&user_id={s1}&point_value={points}&usd_value={payout}&shm_upload_id={shm_upload_id}&shm_upload_offer_id={shm_upload_offer_id}&shm_status={shm_status}&shm_event_id={shm_event_id}
The postback URL will be fired as a POST request.
We will replace all of the macros, such as {conversion_id}, with the actual value (such as "4d63afe33875ceeec17dd7eab41b8590a".) On your server, you will read the "conversion_id" GET variable to retrieve this macro's value.
Understanding IDs
Each receipt that is uploaded corresponds to a single Upload ID
Each Upload can have multiple Offer IDs associated with it
Each offer on the receipt has its own Upload Offer ID, which is unique to an Upload and Offer.
Whenever a status changes for an offer, there is a corresponding Event ID
A single Offer or Upload Offer may have multiple approvals or other statuses. For example, if an offer is for purchasing Apples, then 3 purchased apples result in one offer with multiple approval (and other) events.
Available Macros
You may add any of the following macros to your postback URLs. They will be replaced with the corresponding values.
{s1}
User ID
String or Integer
{points}
Number of points/credits the user should be rewarded with
Decimal or Integer
{payout}
Amount in USD that you earned for this event. It will be a positive number for APPROVED statuses.
Decimal
{state}
Provided only for APPROVED statuses. This is the state of the conversion. Possible values are:
approved - the conversion is approved
rejected - a conversion that was previously pending or approved was reversed
pending - the user has completed the offer but the conversion will be approved at a later date
If this macro is not present in your postback URL, postbacks will only be sent for approved conversions.
String
{s2},{s3},{s4},{s5}
Additional subID values that can be appended to your offer wall URL
String
{conversion_id}
Unique ID of the conversion generated by AdGate Media. Applicable only for the APPROVED status.
String
{session_ip}
IP address of the user that completed the offer
String
{date}
Date of the APPROVED status formatted as YYYY-MM-DD
String
{time}
Current time of conversion formatted as HH:MM:SS
String
{ran}
Randomly generated number
Integer
{country}
Two letter country code representing the user's location.
String
{delay}
Delay in minutes before the conversion is approved.
Integer
{shm_upload_id}
A unique ID for the uploaded receipt.
Integer
{shm_upload_offer_id}
A unique ID given for a specific offer found on a specific receipt (upload).
Integer
{shm_offer_id}
The global ID for the offer that was uploaded (e.g. for Apples)
Integer
{shm_offer_name}
The name of the offer that was uploaded (e.g. "Apples")
String
{shm_status}
The status of the Magic Receipt upload for an individual offer. Possible values are:
MANUAL_REVIEW - the upload is under review.
AWARD_PENDING - An award will likely awarded later, barring any fraud issues.
APPROVED - the upload is approved.
REJECTED - the upload is rejected.
String
{shm_event_id}
Unique ID for the status update.
Integer
{shm_reason_text}
The reason for the current status. For example, if a receipt is rejected, a reason might be "No Matching Offers".
String
{shm_datetime}
The datetime of the upload status update formatted as YYYY-MM-DD HH:MM:SS
String
All values are URL encoded.
With this postback, you can receive the receipt image URLs that can be retrieved from the POST request body. The image URLs have a limited lifetime of 7 days. The request body you can expect is a JSON object of this format:
Expected Response
AdGate Media's servers expect an HTTP Status Code 200 from your postback URL. If this response is not received from your URL, we will attempt to resend the postback up to 5 times. There is a 5 minute delay between each attempt.
Security Recommendations
To prevent tampering, it is important that the postback URL that is used is unique to AdGate Media.
For additional security, you may whitelist the following server IP: 52.42.57.125
Troubleshooting
To troubleshoot any postback issues, you may visit your Postback Reports page here: https://dash.adgatemedia.com/affiliate/reports/postbacks
This page will show a 30 day history of all postbacks on your account.
Last updated