Overview of the Magic Receipts API

Magic Receipts allows users to snap pictures of their grocery receipts and earn awards when their purchases contain promoted products (offers). Offers have specified restrictions such as expiration date, price minimum, store, quantity, and varietal limitations ( must match specific UPCs).

Physical receipt submissions must include a clear photo that contains the entire receipt: Store Name, Date, Product, and Sub-Totals. Receipts must be original and not previously used for another incentivized shopping program.

Upon submission, members will be informed of success or failure. A success will initiate an Award Pending status. A failure we yield an accompanying Error Code (reason) with an option to resubmit for success or request “Manual Review” (2-3 business days processing time)

There are four possible statuses:

• PENDING
• COMPLETE
• RECONCILED
• REVIEWING

Once an offer is COMPLETE, it cannot transition to another status. However, a status of the other 3 can be transitioned to another status.

📘

The API does only return magic receipts offers for US and CA.

Core Functionality

A successful Magic Receipts Integration will allow:

• Retrieve current available offers and metadata to display to users
• Retrieve list of supported merchants and associated available offers
• Retrieve list of categories and associated available offers
• MY List - retrieve list of offers that member has indicated as interested in.
• Receipt Upload - Send call to BitLabs with photo, offers indicated, store indicated
  • Offer Upload Response
  • Offer Status Changes

List of all Magic Receipt Endpoints

• Get access token for magic receipts endpoint requests
• OFFERS LIST: instore-offers-short
• OFFER DETAILS: instore-Offer-Details
• CATEGORIES: Get-Category-Types
• Get-Instore-Merchants
• [Clip Offer Endpoint](Clip Offer Endpoint)
• In-Store-Receipt-Validation
• Post Offers (My List) Endpoint
• In-Store-Manual-Review

Callbacks and rewarding users

To process the earnings of magic receipts, please read about our callback system.

Enabling test mode

To test some of the endpoints, we advise using the magic receipts test mode.

Enable the magic receipt test mode on the BitLabs Dashboard -> Apps -> Select your app -> Demand Settings -> Magic Receipts -> Test mode:

You might need to wait up to 5 minutes because of caching. Then you can generate a new authentication token:

curl \
 -X GET https://api.bitlabs.ai/v1/client/magic-receipts/access-token \
 -H "X-Api-Token: $API_KEY" \
 -H "X-User-Id: {USERID}"

And for the endpoint URLs you would be required to use https://qa-receipts.bitlabs.ai/ and later in production change them to https://receipts.bitlabs.ai.

Using custom parameters

In case you want to pass in your own dynamic data to get them in the callbacks, we advise using custom parameters or tags. You can find a comprehensive guide here.