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/v1/offer/byn_transaction_id/redemption

The byn_transaction_id is found in the response to the POST transaction call..

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 activation before this record was deliveredStringA fulfillment_count of 0 means that previous to this record, no fulfillments were recorded for this particular offer activation
split_tenderWhether the transaction in the offer redemption is only a part of the full receipt tender setBooleantrue, false
byn_match_idBanyan generated ID of the match between receipt and transactionString
fulfillment_countThe number of times a reward has been redeemed by the same finx consumer token and card not including the offer redemption it is part ofStringExample: The first time the offer is fulfilled the repeat_amount will show "0", the next time will show "1", and so on

offer_redemption.campaign

NameDescriptionTypeNotes
byn_campaign_idBanyan created ID to represent one or many offers that belong to the same marketing budgetString
nameUser generated name for the campaignStringCan be updated at any time
byn_publisher_idBanyan client ID for the publisher/provider of the campaignString
created_tsWhen the campaign was created in UTCRFC3339
updated_tsWhen a campaign was updated lastRFC3339
budgetBudget of the campaignNumeric

offer_redemption.offer_activation

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
created_tsWhen an activation was createdRFC3339
updated_tsWhen an activation was last updatedRFC3339

offer_redemption.offer

NameDescriptionTypeNotes
byn_offer_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
nameUser generated offer nameString
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_typeWhether the reward is dollars or pointsStringPotential values: dollars, points, miles
amount_back_per_dollarRate of the reward per dollar if using percent economicsStringEither amount_back_per_dollar OR amount_back_per_limit needs to be set on the offer. Both cannot be set at the same time.
amount_back_per_unitRate of the reward if using unit economicsStringEither amount_back_per_dollar OR amount_back_per_limit needs to be set on the offer. Both cannot be set at the same time.
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.
always_onWhether it is an always on offerBoolean
offer_criteriaTop level objectObject
currencyCurrency of the amount back limit and amount thresholdStringAll amounts must be in the same currency
allow_activation_after_purchaseWhether opting into the offer has to happen before the purchase of the qualified items for it to fulfill the reward criteriaBoolean
prorate_qualified_spendWhether all payments on the transaction count towards the offer criteria or only the payment that has the card activationBoolean
card_issuerIssuer of the card that should be filtered on for the rewardString
card_typesCard types that qualify for the rewardArray of strings

offer_redemption.offer.offer_criteria

NameDescriptionTypeNotes
order_typesPurchase method such as web, in_store, or phoneArray of StringsThere is no default, but if you do not add any values here, no offer redemptions will be created
item_qualification_expressionKey value pairs that represent item attributes that are valid for the offerArray of key value strings
item_disqualification_expressionKey value pairs that represent item attributes that are invalid for the offerArray of key value strings
include_skuSKUs that are included in the offerArray of Strings
exclude_skuSKUs that are excluded from the offerArray of Strings
amount_thresholdThe amount of money that must be spent to qualify for the offerStringNoDefault is 0
fulfillment_count_limitHow many times can the offer be reused by the same card/accountStringNo0 means there is no limit

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
items.qualified_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
items.qualified_idsThe Banyan given IDs of the items that are included in the offer criteriaString
items.unqualified_idsThe Banyan given IDs of the items that are not included in the offer criteriaString
amount_backThe calculated amount the user receives based on their spend and offer criteriaString

Example of a fulfilled offer:

{
  "data": [
    {
      "id": "0e23fcbe-ec4e-445e-9891-ee14e816a4f2",
      "campaign": {
        "byn_campaign_id": "10591c64-b1b3-5466-b215-37f47b6d7856",
        "name": "Walgreens Test",
        "budget": 200000,
        "byn_publisher_id": 334,
        "created_ts": "2024-11-13T16:37:32.205708Z",
        "updated_ts": "2024-11-13T16:37:32.205708Z"
      },
      "offer_activation": {
        "id": "9775430d-ed86-5a3f-9cca-6949299dc45f",
        "byn_publisher_id": 334,
        "publisher_consumer_token": "c5602241-63df-42ce-a0e8-ea10474979cc::00091000",
        "cards": [
          "4240"
        ],
        "created_ts": "2024-12-09T15:02:41.445658Z",
        "updated_ts": "2024-12-09T15:02:41.445658Z"
      },
      "offer": {
        "byn_offer_id": "109eef2a-6315-5d12-8b1e-b0a3c061214d",
        "name": "Walgreens Test",
        "publisher_offer_id": "55",
        "return_receipt_detail": false,
        "always_on": false,
        "byn_advertiser_id": 327,
        "byn_publisher_id": 334,
        "amount_back_limit": "0",
        "amount_back_per_dollar": "0.12",
        "amount_back_per_unit": "0",
        "amount_back_type": "DOLLAR",
        "start_ts": "2024-11-18T05:00:00Z",
        "expiration_ts": "2025-03-16T03:59:00Z",
        "offer_criteria": {
          "order_types": [
            "in_store"
          ],
          "item_qualification_expression": "",
          "item_disqualification_expression": "\"excluded:|:excluded item\"",
          "incl_tags": null,
          "excl_tags": null,
          "incl_sku": null,
          "excl_sku": null,
          "amount_threshold": "0",
          "fulfillment_count_limit": 0
        },
        "offer_hotel_criteria": null,
        "created_ts": "2024-11-13T17:06:08.782595Z",
        "updated_ts": "2025-03-13T18:54:39.765905Z",
        "currency": "",
        "allow_activation_after_purchase": true,
        "prorate_qualified_spend": true,
        "card_issuer": "",
        "card_types": [],
        "activation_window_minutes": null,
        "budget": 0
      },
      "result": {
        "items": {
          "qualified_total_amount": "37.26",
          "qualified_ids": null,
          "unqualified_ids": null
        },
        "fulfilled": true,
        "cumulative_qualified_total_amount": "37.26",
        "amount_back": "4.47",
        "hotel": {
          "qualified_dining_charges": null,
          "unqualified_dining_charges": null,
          "total_qualified_dining_spend": "0",
          "qualified_room_charges": null,
          "unqualified_room_charges": null,
          "total_qualified_room_spend": "0"
        }
      },
      "fulfillment_count": 10,
      "created_ts": "2025-04-02T16:56:28.152958685Z",
      "enriched_transaction": {
        "byn_etx_id": "0797bf76-0d95-555b-9b0f-311089a48096",
        "match_ts": "2025-04-02T16:56:27.8Z",
        "confidence_interval": null,
        "transaction": {
          "byn_transaction_id": "facc8f9e-2df1-5c80-ad0d-3453fcc099f4",
          "purchase_ts": "2025-03-16T09:07:01Z",
          "received_ts": "2025-04-02T16:56:27.716Z",
          "authorization_ts": "2025-03-15T14:50:15Z",
          "merchant": {
            "name": "WALGREENS"
          },
          "location": {
            "merchant_store_id": "1315",
            "name": "WALGREENS",
            "card_acceptor_names": null,
            "display_name": "",
            "phone_number": "",
            "address": {
              "address_line_one": "",
              "address_line_two": "",
              "city": "TOMS RIVER",
              "state": "NJ",
              "country": "US",
              "postal_code": ""
            }
          },
          "payment": {
            "payment_type": "",
            "scheme": "",
            "card_last_four": "5555",
            "bin": "",
            "auth_code": "555006",
            "arn": "",
            "total_amount": "38.87",
            "currency": "",
            "finx_mid": "",
            "virtual_card_last_four": "",
            "card_issuer": "",
            "card_type": "",
            "payment_account_reference": ""
          },
          "order_type": "",
          "description": "WALGREENS #1315",
          "finx_transaction_id": "32f95059-44e6-4a43-84e8-6f14b9efa0da::00091000",
          "finx_consumer_token": "c5602241-63df-42ce-a0e8-ea10474979cc::00091000",
          "custom_fields": {
            "issuerId": "00091000",
            "transactionId": "32f95059-44e6-4a43-84e8-6f14b9efa0da"
          }
        },
        "split_tender": false,
        "byn_match_id": "cf334072-133d-5503-9345-5f09a48c0f2c"
      }
    }
  ],
  "errors": [],
  "request_id": "15a9c8cae5347ff7c5cedc5ad206159f"
}