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 | |
| byn_publisher_id | Banyan client ID for the publisher/provider of the campaign | String |
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 |
offer_redemption.offer
| Name | Description | Type | Notes |
|---|---|---|---|
| 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 | |
| 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. |
| offer_criteria | Top level object | Object |
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 |
|---|---|---|---|
| qualified_item_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 | |
| qualified_items | The Banyan given IDs of the items that are included in the offer criteria | String | |
| unqualified_items | The Banyan given IDs of the items that are not included in the offer criteria | String |
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_activation": {
"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": []
}
Updated about 1 month ago