API: GET Offer Redemption

Overview

Using the byn_transaction_id within the path, you are able to pull an offer redemption record using: api.banyan.com/rest/v1/offer/redemption/byn_transaction_id

The byn_transaction_id is found in the response to the POST transaction call. If you are sending data to Banyan via BATCH method and you don't have the byn_transaction_id readily available, you could also use the SEARCHendpoint using your own unique transaction id, AKA the finx_transaction_id.

The offer redemption has many objects within it:

  1. Offer Redemption Meta Data: elements about the offer redemption (id, timestamp, etc)
  2. Offer Result Information: elements about qualified items, amounts
  3. Offer Details: elements about the relevant offer
  4. Matching details: elements about the match itself (timestamp, id)
  5. Original transaction details: elements that were sent to Banyan by the FinX including some Banyan enrichments like location/category information
  6. Receipt details of the matched receipt: elements pertaining to the matched receipt including items and store information

Authentication and Authorization

Contact your Banyan representative to obtain an API key and Access ID to be used on the authorization end point. Once you have your key and ID, you will use the following curl call to obtain your token. Tokens expire every 30 minutes. Using a retired token will result in a 404 error response.

Offer redemptions that your transaction are tied to are available to be extracted from the Banyan platform. You will not be able to pull offer redemptions for transactions you do not own.

TOKEN=$(curl -s -X POST \
    -H 'Content-Type: application/json' \
    --data "{\"access_id\":\"$ACCESS_ID\",\"api_key\":\"$API_KEY\"}" \
    ${GATEWAY_URL}/token | jq -r .data[0])

Headers

Header NameDescriptionRequiredValues
BearerAccess TokenRequiredSee Authorization section
Content-TypeThe transaction format to sendOptionalapplication/JSON
AcceptThe response format sent backOptionalapplication/JSON

URL

api.banyan.com/rest/v1/offer/redemption/{{byn_transaction_id}} where byn_transaction_id is the transaction you want offer redemption information for.

Response

offer_redemption

NameDescriptionTypeNotes
idBanyan created ID of the offer redemption objectStringA new redemption record will be generated for every transaction at a merchant for a given account/card match
fulfillment_countCount of fulfilled redemptions for this offer mapping before this record was deliveredStringA fulfillment_count of 0 means that previous to this record, no fulfillments were recorded for this particular offer mapping

offer_redemption.campaign

NameDescriptionTypeNotes
idBanyan created ID to represent one or many offers that belong to the same marketing budgetString
byn_publisher_idBanyan client ID for the publisher/provider of the campaignString

offer_redemption.offer_mapping

NameDescriptionTypeNotes
byn_publisher_idThe ID given to your organization from BanyanNumericReach out to your Customer Support representative if you are unsure what your byn_publisher_id is
publisher_consumer_tokenThe unique ID your organization has for an accountString
cardsThe cards that are valid for the offerArray of strings

offer_redemption.offer

NameDescriptionTypeNotes
idBanyan created ID of the offer object.String
publisher_offer_idUnique ID provided by the publisher used to create the byn_offer_id as well as the key to tie Banyan data back to FinX internal dataString
byn_campaign_idBanyan created unique ID for the campaignString
return_receipt_detailWhether the offer redemption record delivered back to the FinX has full receipt details or simply the resultBooleanValid values are true, false. Default is true
byn_advertiser_idBanyan created client/merchant ID that the campaign is advertisingString
byn_publisher_idBanyan created client/finx ID that the campaign is fulfilled byString
amount_back_limitThe highest amount the customer can receive for the offerStringRelevant when the offer is a % back of a purchase. If left null, there will be no limit.
amount_back_per_dollarRate of the reward per dollarStringExamples noted below
amount_back_typeWhether the reward is dollars or pointsStringPotential values: dollars, points, miles
start_tsWhen the offer is valid to be redeemedRFC3339Should be sent in UTC
expiration_tsWhen the offer endsRFC3339Should be sent in UTC. If you want the offer to extend for a long period of time, choose a date far out in the future.
offer_criteriaTop level objectObject

offer_redemption.enriched_transaction

See enriched transaction schema here

offer_redemption.result

This object will tell you with the fulfilled field whether the attached receipt contents resulted in a reward for the card holder. In addition, the result offers some useful information for both payouts and customer support. This object will tell you the IDs of the items that qualified/did not qualify for the offer as well as the total amount of the qualified items.

NameDescriptionTypeNotes
qualified_item_total_amountTotal amount of the items that are included in the offer criteriaStringCurrently only in USD
fulfilledIf true, the offer is fulfilled. If false, the offer is not fulfilledBoolean
qualified_itemsThe Banyan given IDs of the items that are included in the offer criteriaString
unqualified_itemsThe Banyan given IDs of the items that are not included in the offer criteriaString

Example unfulfilled offer:

{
    "data": [
        {
            "id": "674c413b-a1b8-4472-badb-b360fc8c5842",
            "campaign": {
                "id": "7fce69a6-5033-5cec-851d-6e934b784a8d",
                "byn_publisher_id": 106,
                "created_ts": "2022-12-09T20:55:31.996242Z"
            },
            "offer_mapping": {
                "id": "cbfc7004-bdf3-503b-a563-e9ea0eaf7a92",
                "byn_publisher_id": 106,
                "publisher_consumer_token": "1de6f2e0-d266-48fc-97a7-8e65cb8b1a47",
                "cards": [
                    "5715"
                ],
                "created_ts": "2022-12-09T20:55:42.25514Z",
                "updated_ts": "2022-12-09T20:55:42.25514Z"
            },
            "offer": {
                "id": "fbf4cf8c-5637-5033-a821-de917e51a748",
                "publisher_offer_id": "1b0b4b5d-b900-502d-b308-fd16e1d2b45e",
                "return_receipt_detail": true,
                "byn_advertiser_id": 106,
                "byn_publisher_id": 106,
                "amount_back_limit": "10",
                "amount_back_per_dollar": "0.2",
                "amount_back_type": "DOLLAR",
                "start_ts": "2022-07-05T15:05:32Z",
                "expiration_ts": "2022-08-06T16:06:33Z",
                "offer_criteria": {
                    "order_types": [
                        "in_store"
                    ],
                    "incl_tags": [
                        "category_description:|:BABY CARE"
                    ],
                    "excl_tags": [
                        "brand:|:Pampers"
                    ],
                    "incl_sku": [],
                    "excl_sku": [],
                    "amount_threshold": "50",
                    "repeat_amount": 2
                },
                "created_ts": "2022-12-09T20:55:36.319707Z",
                "updated_ts": "2022-12-09T20:55:36.319707Z"
            },
            "enriched_transaction": {
                "id": "cd716090-f5c9-514b-911a-792a40b9b560",
                "match_timestamp": "2022-12-09T20:55:57.867Z",
                "receipt": {
                    "id": "19d73267-b802-5306-9090-f2f04dde4bd8",
                    "byn_partner_id": 106,
                    "merchant_receipt_id": "0eee35c4-fcef-4923-ba45-65a59f3cb8e5",
                    "purchase_ts": "2022-08-04T12:32:53.676Z",
                    "received_ts": "2022-12-09T20:55:57.29Z",
                    "merchant": {
                        "name": "Rite Aid",
                        "display_name": "Rite Aid",
                        "created_ts": "2022-08-06T11:37:31Z"
                    },
                    "location": {
                        "name": "Rite Aid Schmittown",
                        "display_name": "Rite Aid",
                        "phone_number": "827-889-2490",
                        "address": {
                            "address_line_one": "76536 Fords borough",
                            "city": "Schmitttown",
                            "state": "Texas",
                            "country": "USA",
                            "postal_code": "98471",
                            "created_ts": "2022-08-06T11:37:31Z"
                        },
                        "byn_partner_id": 106,
                        "created_ts": "2022-08-06T11:37:31Z"
                    },
                    "order_type": "in_store",
                    "fulfillment_type": "",
                    "currency": "usd",
                    "merchant_total_amount": "75.2",
                    "payments": [
                        {
                            "id": "2cc5a534-932a-5ed3-ad35-bb0e6787e694",
                            "total_amount": "75.2",
                            "payment_type": "credit",
                            "scheme": "VI",
                            "card_last_four": "5715",
                            "auth_code": "822333",
                            "arn": "918390183993",
                            "subtotal_amount": "68.98",
                            "tip_amount": "0",
                            "tax_amount": "6.22",
                            "cash_back_amount": "0"
                        }
                    ],
                    "items": [
                        {
                            "id": "032f840a-9c4b-5483-b6d0-284c5ea4a6e7",
                            "merchant_item_id": "747640",
                            "upc": "297070388426",
                            "brand": "Huggies",
                            "description": "Nighttime Diapers Size 4 16 ct",
                            "amount_paid": "13.34",
                            "full_price_per_unit": "13.34",
                            "discount_price_per_unit": "0",
                            "quantity": "1",
                            "tags": [
                                "category_description:|:BABY CARE",
                                "brand:|:Huggies",
                                "subclass_desc:|:BABY - DIAPERS"
                            ]
                        },
                        {
                            "id": "7e09721c-1f61-525c-97f0-3a300c8ed8ca",
                            "merchant_item_id": "893268",
                            "upc": "282185527608",
                            "brand": "Little Remedies",
                            "description": "Saline Spray 6 oz",
                            "amount_paid": "19.3",
                            "full_price_per_unit": "6.43",
                            "discount_price_per_unit": "6.43",
                            "quantity": "3",
                            "tags": [
                                "category_description:|:BABY CARE",
                                "brand:|:Little Remedies",
                                "subclass_desc:|:BABY - MISC"
                            ]
                        },
                        {
                            "id": "fb080674-ead9-54cb-9eac-bed7a190a02f",
                            "merchant_item_id": "627290",
                            "upc": "072140636081",
                            "brand": "Eucerin",
                            "description": "Baby Aquaphor 8oz Tub",
                            "amount_paid": "36.34",
                            "full_price_per_unit": "19.99",
                            "discount_price_per_unit": "18.17",
                            "quantity": "2",
                            "tags": [
                                "category_description:|:BABY CARE",
                                "brand:|:Eucerin",
                                "subclass_desc:|:BABY - OINTMENT"
                            ]
                        },
                        {
                            "id": "fb080674-ead9-54cb-9eac-bed7a190a02f",
                            "merchant_item_id": "382902",
                            "upc": "072140636081",
                            "brand": "Pampers",
                            "description": "Sensitive Skin Wipes 48 ct",
                            "amount_paid": "2.79",
                            "full_price_per_unit": "2.79",
                            "discount_price_per_unit": "2.79",
                            "quantity": "2",
                            "tags": [
                                "category_description:|:BABY CARE",
                                "brand:|:Pampers",
                                "subclass_desc:|:BABY - DIAPERS"
                            ]
                        }
                    ],
                    "merchant_consumer_token": "12980970980998",
                    "image_url": "https://riteaid.com/receipt/images/b33097d4-58d4-4247-8f63-5c7793b2dccf",
                    "barcode_url": "https://riteaid.com/receipt/barcodes/b33097d4-58d4-4247-8f63-5c7793b2dccf",
                    "PeartreeVersion": "b99e4e1"
                },
                "transaction": {
                    "id": "e9425c04-973d-5967-aaa4-a264e6993690",
                    "purchase_ts": "2022-08-04T12:32:53.676Z",
                    "received_ts": "2022-12-09T20:55:54.761Z",
                    "byn_partner_id": 106,
                    "merchant": {
                        "name": "Rite Aid",
                        "display_name": "Rite Aid",
                        "created_ts": "2022-08-06T11:37:31Z"
                    },
                    "location": {
                        "name": "Rite Aid",
                        "display_name": "Rite Aid",
                        "phone_number": "827-889-2490",
                        "address": {
                            "address_line_one": "76536 Fords borough",
                            "city": "Schmitttown",
                            "state": "Texas",
                            "country": "USA",
                            "postal_code": "98471",
                            "created_ts": "2022-08-06T11:37:31Z"
                        },
                        "byn_partner_id": 106,
                        "created_ts": "2022-08-06T11:37:31Z"
                    },
                    "payment": {
                        "payment_type": "credit",
                        "scheme": "VI",
                        "card_last_four": "5715",
                        "bin": "81923112",
                        "auth_code": "822333",
                        "arn": "918390183993",
                        "total_amount": "75.2",
                        "currency": "USD",
                        "finx_mid": "8Ae9KaYSe4bFLHKBHnGhMK"
                    },
                    "order_type": "in_store",
                    "description": "lakdjflajdflj",
                    "finx_transaction_id": "6297246",
                    "finx_consumer_token": "1de6f2e0-d266-48fc-97a7-8e65cb8b1a47",
                    "schema_version": "2022-01-27",
                    "PeartreeVersion": "b99e4e1"
                }
            },
            "result": {
                "qualified_item_total_amount": "68.98",
                "fulfilled": false,
                "qualified_items": [
                    "032f840a-9c4b-5483-b6d0-284c5ea4a6e7",
                    "7e09721c-1f61-525c-97f0-3a300c8ed8ca",
                    "fb080674-ead9-54cb-9eac-bed7a190a02f"
                ],
                "unqualified_items": [
                    "fb080674-ead9-54cb-9eac-bed7a190a02f"
                ],
                "amount_back": "0"
            },
            "fulfillment_count": 1,
            "created_ts": "2022-12-09T20:55:58.378729471Z"
        }
    ],
    "errors": []
}