Overview

The Receipt Upload API allows members to upload their shopping receipts to claim offers listed under the Magic Receipts program. The API processes the uploaded receipt image, evaluates the eligibility for cashback, and returns the status of each claimed offer.

HTTP Request

curl \
-X POST https://receipts.bitlabs.ai/?cmd=mp-mr-api-upload-receipt&offerIDs=191405%2C143787&merchantID=7 \
-H "Authorization: Bearer <token>"

Request Parameters

Name	Type	Description
`merchantID`	integer	The ID of the merchant where the purchase was made (optional).
`offerIDs`	integer[]	An array of offer IDs that the member wants to claim.
`receipt`	string	The text representation of the receipt, if applicable. Defaults to empty.

Form Data Parameters

Name	Type	Description
`img0`	binary	The binary data of the receipt image.
`imgName0`	string	The file name of the receipt image.

Main Response

Name	Type	Description
`status`	integer	The HTTP status code of the response.
`data`	object	The main data object containing the details of the processed receipt.

Data Object Fields


Name	Type	Description
awardPending	object	Contains information about the offers that are now in an award pending state, i.e. they will be awarded in a couple of days unless CS rejects them.
confirmed	object	Contains information about the offers that were automatically awarded
confirmedAndAwardPending	object	Contains both offers there were confirmed + award pending
manualReview	object	Contains information about offers that require manual review. If an offer was rejected but it's eligible for manual review it will appear here. There's a request to request manual review and you would pull the eligible list from this object
rejected	object	Contains information about any offers that were rejected during processing.
pending	object	Contains information about offers that were automatically send to manual review. Sometimes this happens if you receipt was flagged for fraud. This offer will be manually approved / denied
barcodeScanEligibleDeviceCodes	array	An array of device codes that are eligible for barcode scanning.
barcodeScanEnabled	boolean	Indicates if barcode scanning is enabled for the receipt upload.

Rejected and Manual Review Objects

Name	Type	Description
`offers`	array	An array of offers with their respective processing status.
`awardBonuses`	array	Any bonus awards applicable to the receipt.
`unusedLineItems`	array	Line items on the receipt that were not used for any offers.
`totalAwardCashback`	string	The total cashback amount awarded for the receipt.
`totalAward`	string	The total award points (SB) earned for the receipt.

Offers Array Object

Name	Type	Description
`maxLinesForManualReview`	integer	The maximum number of lines allowed for manual review.
`offerID`	integer	The ID of the offer.
`imageUrl`	string	The URL of the image related to the offer.
`pendingDays`	integer	The number of days the offer is pending for.
`uploadOfferID`	integer	The ID of the uploaded offer.
`state`	string	The processing state of the offer (e.g., "rejected").
`award`	string	The award points (SB) for the offer.
`awardCashback`	string	The cashback amount for the offer.
`surveyUrl`	string	The URL to a survey related to the offer, if applicable.
`shortErrorStr`	string	A short description of any error encountered.
`errorStr`	string	A full description of the error.
`errorCode`	integer	A code representing the error encountered.
`isBarcodeScanEligible`	boolean	Indicates if the offer is eligible for barcode scanning.
`offerTitle`	string	The title of the offer.
`addedToList`	boolean	Indicates if the offer was added to the user's list.
`isUnselectedOffer`	boolean	Indicates if the offer was not originally selected by the user

Unused Line Items Object Fields

Name	Type	Description
`receiptLineID`	integer	The unique identifier for the line item on the receipt.
`rsd`	string	The recognized shopping description or item name extracted from the receipt.
`price`	decimal	The price of the item as captured from the receipt.

Error Handling

The method includes comprehensive error handling, providing clear error messages and codes for various failure scenarios such as invalid merchant ID, image count, offer IDs, receipt data, and upload progress state.
It also ensures that if a receipt upload is already in progress, it will not start another, preserving the integrity of the member's upload queue.

Sample Receipt Upload Request Display:

On the main screen there is a Submit Receipt button that allows the member to start the upload process

Clicking on that button makes a call to the merchants api above to retrieve all the merchants that a member could choose they shopped at for their receipt.

after selecting a merchant and clicking Continue a call is made to the offers-short api above with sortType=0 and merchantID=?? whatever the id of the merchant is, that will return to you all the offers relevant for this merchant that the member could upload for.

choose which offers are on your receipt and how many of them you bought for offers that have multiple goals (buying options) attached to them, i.e. buy 1 get this amount, buy 2 get this award.

After clicking Continue you’re taken to this screen that allows you to upload a file which is a picture of your receipt.

A member can attach multiple pictures to capture the entire receipt if it’s long

Then when clicking Submit Receipt we make the upload-receipt call to the api to do the validation, while we are validating we have an upload screen.

Depending on the result from the upload we display accordingly

there can be multiple reasons the offers were rejected, as can be seen here 3 different reasons: date, matching, duplicate

From there you can click Contact Customer Support to request manual review (see above API doc), or click Review Your Receipt Photos and either resubmit the same photo or choose different ones.