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..

The offer redemption has many objects within it:

Offer Redemption Meta Data: elements about the offer redemption (id, timestamp, etc)
Offer Result Information: elements about qualified items, amounts
Offer Details: elements about the relevant offer
Matching details: elements about the match itself (timestamp, id)
Original transaction details: elements that were sent to Banyan by the FinX including some Banyan enrichments like location/category information
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 Name	Description	Required	Values
Bearer	Access Token	Required	See Authorization section
Content-Type	The transaction format to send	Optional	application/JSON
Accept	The response format sent back	Optional	application/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

Name	Description	Type	Notes
id	Banyan created ID of the offer redemption object	String	A new redemption record will be generated for every transaction at a merchant for a given account/card match
fulfillment_count	Count of fulfilled redemptions for this offer activation before this record was delivered	String	A fulfillment_count of 0 means that previous to this record, no fulfillments were recorded for this particular offer activation

offer_redemption.campaign

Name	Description	Type	Notes
id	Banyan created ID to represent one or many offers that belong to the same marketing budget	String
name	User generated name for the campaign	String	Can be updated at any time
byn_publisher_id	Banyan client ID for the publisher/provider of the campaign	String
created_ts	When the campaign was created in UTC	RFC3339
updated_ts	When a campaign was updated last	RFC3339

offer_redemption.offer_activation

Name	Description	Type	Notes
byn_publisher_id	The ID given to your organization from Banyan	Numeric	Reach out to your Customer Support representative if you are unsure what your byn_publisher_id is
publisher_consumer_token	The unique ID your organization has for an account	String
cards	The cards that are valid for the offer	Array of strings
created_ts	When an activation was created	RFC3339
updated_ts	When an activation was last updated	RFC3339

offer_redemption.offer

Name	Description	Type	Notes
byn_offer_id	Banyan created ID of the offer object.	String
publisher_offer_id	Unique 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 data	String
name	User generated offer name	String
byn_campaign_id	Banyan created unique ID for the campaign	String
return_receipt_detail	Whether the offer redemption record delivered back to the FinX has full receipt details or simply the result	Boolean	Valid values are true, false. Default is true
byn_advertiser_id	Banyan created client/merchant ID that the campaign is advertising	String
byn_publisher_id	Banyan created client/finx ID that the campaign is fulfilled by	String
amount_back_limit	The highest amount the customer can receive for the offer	String	Relevant when the offer is a % back of a purchase. If left null, there will be no limit.
amount_back_per_dollar	Rate of the reward per dollar	String	Examples noted below
amount_back_type	Whether the reward is dollars or points	String	Potential values: dollars, points, miles
start_ts	When the offer is valid to be redeemed	RFC3339	Should be sent in UTC
expiration_ts	When the offer ends	RFC3339	Should 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_on	Whether it is an always on offer	Boolean
offer_criteria	Top level object	Object
currency	Currency of the amount back limit and amount threshold	String	All amounts must be in the same currency
allow_activation_after_purchase	Whether opting into the offer has to happen before the purchase of the qualified items for it to fulfill the reward criteria	Boolean
prorate_qualified_spend	Whether all payments on the transaction count towards the offer criteria or only the payment that has the card activation	Boolean

offer_redemption.offer.offer_criteria

Name	Description	Type	Notes
order_types	Purchase method such as web, in_store, or phone	Array of Strings	There is no default, but if you do not add any values here, no offer redemptions will be created
incl_tags	Key value pairs that represent item attributes that are valid for the offer	Array of key value strings
excl_tags	Key value pairs that represent item attributes that are invalid for the offer	Array of key value strings
include_sku	SKUs that are included in the offer	Array of Strings
exclude_sku	SKUs that are excluded from the offer	Array of Strings
amount_threshold	The amount of money that must be spent to qualify for the offer	String
fulfillment_count_limit	How many times can the offer be reused by the same card/account	String	0 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.

Name	Description	Type	Notes
items.qualified_total_amount	Total amount of the items that are included in the offer criteria	String	Currently only in USD
fulfilled	If true, the offer is fulfilled. If false, the offer is not fulfilled	Boolean
items.qualified_ids	The Banyan given IDs of the items that are included in the offer criteria	String
items.unqualified_ids	The Banyan given IDs of the items that are not included in the offer criteria	String
amount_back	The calculated amount the user receives based on their spend and offer criteria	String
fulfillment_count	The number of times a reward has been redeemed by the same finx consumer token and card not including the offer redemption it is part of	String	Example: The first time the offer is fulfilled the repeat_amount will show "0", the next time will show "1", and so on

Example unfulfilled offer:

{
  "data": [
    {
      "id": "a90b6501-3587-4946-995f-e246c0330d04",
      "campaign": {
        "byn_campaign_id": "75ffa112-1ee4-57ae-b887-73061ae94b74",
        "name": "July 2024 Gas Promotion",
        "byn_publisher_id": 000,
        "created_ts": "2024-06-26T16:58:24.450235Z",
        "updated_ts": "2024-06-26T16:58:24.450235Z"
      },
      "offer_activation": {
        "id": "552b71fc-99be-50bd-b1cf-bc8620684087",
        "byn_publisher_id": 000,
        "publisher_consumer_token": "55555555555",
        "cards": [
          "5718"
        ],
        "created_ts": "2024-07-15T16:08:18.515494Z",
        "updated_ts": "2024-07-15T16:08:18.515494Z"
      },
      "offer": {
        "byn_offer_id": "3d147491-467c-5d84-800c-66e376361d0a",
        "name": "NON WOW July 2024 Gas Offer",
        "publisher_offer_id": "555555",
        "return_receipt_detail": true,
        "always_on": false,
        "byn_advertiser_id": 001,
        "byn_publisher_id": 000,
        "amount_back_limit": "5",
        "amount_back_per_dollar": "0.2",
        "amount_back_type": "DOLLAR",
        "start_ts": "2024-07-01T04:00:00Z",
        "expiration_ts": "2024-07-09T03:59:00Z",
        "offer_criteria": {
          "order_types": [
            "any"
          ],
          "incl_tags": [
            "category_name:|:UNEADED PREMIUM\t",
            "category_name:|:E85 FUEL",
            "category_name:|:UNLEADED MID GRADE",
            "category_name:|:ETHANOL FREE FUEL",
            "category_name:|:UNLEADED REGULAR",
            "category_name:|:DIESEL",
            "fuel_prepay:|:True"
          ],
          "excl_tags": [],
          "incl_sku": [],
          "excl_sku": [],
          "amount_threshold": "0",
          "fulfillment_count_limit": 1
        },
        "offer_hotel_criteria": null,
        "created_ts": "2024-06-26T17:08:37.841888Z",
        "updated_ts": "2024-06-26T17:08:37.841888Z",
        "currency": "",
        "allow_activation_after_purchase": true,
        "prorate_qualified_spend": true,
        "card_issuer": "",
        "card_types": null
      },
      "result": {
        "items": {
          "qualified_total_amount": "29.14",
          "qualified_ids": [
            "e0bd7473-8961-5b27-9a8d-768e9a2e97ca"
          ],
          "unqualified_ids": []
        },
        "fulfilled": true,
        "cumulative_qualified_total_amount": "29.14",
        "amount_back": "5.83",
        "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": 0,
      "created_ts": "2024-07-15T16:34:30.840992882Z",
      "enriched_transaction": {
        "byn_etx_id": "197ca460-63bc-5854-a1f8-9b2cbc013b29",
        "match_ts": "2024-07-15T16:32:03.263Z",
        "transaction": {
          "byn_transaction_id": "8a3653c4-121b-5426-afe9-8b4966df4778",
          "purchase_ts": "2024-07-07T21:13:59.502Z",
          "received_ts": "2024-07-15T16:31:57.687Z",
          "authorization_ts": "2024-07-07T21:13:59.502Z",
          "merchant": {
            "name": "USA GAS"
          },
          "location": {
            "merchant_store_id": "",
            "name": "USA GAS #3691",
            "card_acceptor_names": null,
            "display_name": "",
            "phone_number": "",
            "address": {
              "address_line_one": "",
              "address_line_two": "",
              "city": "GIBSONIA",
              "state": "PA",
              "country": "",
              "postal_code": ""
            }
          },
          "payment": {
            "payment_type": "",
            "scheme": "",
            "card_last_four": "0000",
            "bin": "",
            "auth_code": "000054",
            "arn": "",
            "total_amount": "29.14",
            "currency": "USD",
            "finx_mid": "938293920329439",
            "virtual_card_last_four": "",
            "card_issuer": "",
            "card_type": ""
          },
          "order_type": "",
          "description": "",
          "finx_transaction_id": "9999999201583112",
          "finx_consumer_token": "55555555555",
          "custom_fields": null
        },
        "receipt": {
          "byn_receipt_id": "df9b1b4c-feff-56e5-b9bd-0a3a86746ccf",
          "hotel": null,
          "merchant_receipt_id": "3691-215-29-20240707171300",
          "merchant_mid": "",
          "purchase_ts": "2024-07-07T21:13:00Z",
          "order_ts": "",
          "received_ts": "2024-07-11T17:13:16.827Z",
          "merchant": {
            "name": "GAS USA"
          },
          "location": {
            "merchant_store_id": "3691",
            "name": "GAS USA GIBSONIA",
            "card_acceptor_names": null,
            "display_name": "",
            "phone_number": "",
            "address": {
              "address_line_one": "4099 Grandview Drive",
              "address_line_two": "",
              "city": "Gibsonia",
              "state": "PA",
              "country": "US",
              "postal_code": "15044"
            }
          },
          "order_type": "in_store",
          "fulfillment_type": "in_store",
          "currency": "USD",
          "merchant_total_amount": "29.14",
          "items": [
            {
              "byn_item_id": "e0bd7473-8961-5b27-9a8d-768e9a2e97ca",
              "merchant_item_id": "",
              "upc": "030034925017",
              "sku": "163745194",
              "image_url": "",
              "brand": "",
              "description": "FUEL STATION/REGULAR UNLEADED",
              "amount_paid": "29.14",
              "full_price_per_unit": "0.01",
              "discount_price_per_unit": "3.54",
              "quantity": "8.23",
              "unit_type": "gallon",
              "tags": [
                "department_name:|:Reg Unleaded",
                "department_id:|:84",
                "category_name:|:UNLEADED REGULAR",
                "category_id:|:7520"
              ]
            }
          ],
          "image_url": "",
          "barcode_url": "",
          "custom_fields": null,
          "payment": {
            "total_amount": "29.14",
            "payment_type": "CREDIT",
            "scheme": "MC",
            "shipping_amount": null,
            "subtotal_amount": "29.14",
            "tip_amount": "0",
            "tax_amount": "0",
            "other_positive_amounts": null,
            "other_negative_amounts": null,
            "cash_back_amount": "0",
            "is_virtual_card": null,
            "card_issuer": ""
          }
        },
        "byn_match_id": "c6909118-95a0-5a1e-805f-f3d5f00405c9"
      }
    }
  ],
  "errors": [],
  "request_id": "57b82203-ca08-4845-9a91-74fa530603b7"
}