API: POST Offer

Overview

Providers can send Banyan the details of the offer as far in advance of the offer beginning as desired. The offer is an independent object of the offer activation Offer details are the desired guardrails for the offer, such as how long the offer is good for, which products qualify, or how many times the offer can be used by the same offer activation.

Developers, please see the API reference for an interactive experience.

URL

api.banyan.com/rest/v1/offer

Body

Name	Description	Type	Required	Notes
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	Yes
name	The name given to the offer	String	No
byn_campaign_id	Banyan created unique ID for the campaign	String	Yes	See how to set up a campaign here
return_receipt_detail	Whether the offer redemption record delivered back to the FinX has full receipt details or simply the result	Boolean	No	Valid values are true, false. Default is true
byn_advertiser_id	Banyan created client/merchant ID that the campaign is advertising	String	Yes
amount_back_limit	The highest amount the customer can receive for the offer on a given transaction	String	No	Relevant when the offer is a % back of a purchase. If left null, there will be no limit. Banyan is not looking across transactions for this sum. It is analyzed per transaction.
amount_back_per_dollar	Rate of the reward per dollar	String	Yes	Examples noted below
amount_back_type	Whether the reward is dollars or points	String	Yes	Potential values: dollars, points, miles
start_ts	When the offer is valid to be redeemed	RFC3339	Yes	Should be sent in UTC
expiration_ts	When the offer ends	RFC3339	Yes	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. If no end_date is set it will default to 1/1/1970 which will throw an error since the start date will be after the end date.
currency	Alphabetic currency code associated with the value in ISO 4217 format	String	Yes	Use three character currency code, Default is USD
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	Yes	Default is false
prorate_qualified_spend	Whether all payments on the transaction count towards the offer criteria or only the payment that has the card activation	Boolean	Yes	Default is true
always_on	Whether an activation is needed for a consumer to qualify for an offer	Boolean	Yes	Default is false
activation_window_minutes	The number of minutes the offer is available to the consumer since activation.	String	No	To be used when the offer can only be redeemed within a window since activating. The lesser of the two will apply between expiration ts and the window calculation.
offer_criteria	Top level object	Object

offer.offer_criteria

Offer criteria is what is used to determine whether the receipt Banyan receives

Name	Description	Type	Required	Notes
order_types	Purchase method such as web, in_store, or phone	Array of strings	Yes	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	No
excl_tags	Key value pairs that represent item attributes that are invalid for the offer	Array of key value strings	No
incl_sku	SKUs that are included in the offer	Array of strings	No
excl_sku	SKUs that are excluded from the offer	Array of strings	No
amount_threshold	The amount of money that must be spent to qualify for the offer	String	No	Default is 0
fulfillment_count_limit	How many times can the offer be reused by the same card/account	String	No	0 means there is no limit

Example:

POST http://api.banyan.com/rest/v1/offer
Bearer: {token_id}
Content-Type: application/json
Accept: application/json

{
    "publisher_offer_id": "e99ea29a-e8d8-531b-9107-ddcd65de3c67",
    "campaign_id": "cf8f9c27-f1da-580f-9316-3350333d234c",
    "return_receipt_detail": true,
    "byn_advertiser_id": 106,
    "amount_back_limit": "10.00",
    "amount_back_per_dollar": "0.20",
    "amount_back_type": "DOLLAR",
    "start_ts": "2022-07-05T15:05:32Z",
    "expiration_ts": "2022-08-06T16:06:33Z",
  	"allow_activation_after_purchase":true,
  	"prorate_qualified_spend":true,
    "activation_window_minutes": "60",
    "always_on": true,
  	"currency": "USD",
    "offer_criteria": {
        "order_types": [
            "in_store"
        ],
        "incl_tags": [
            "category_description:|:BABY CARE"
        ],
        "excl_tags": [
            "brand:|:Pampers"
        ],
        "incl_sku": [],
        "excl_sku": [],
        "amount_threshold": "50.00",
        "fulillment_count_limit": 2
    }
}

Response

A successful call will return the same data back including the Banyan offer ID which will be helpful later if you want to use GET functionality within the API.

Name	Description	Type	Notes
id	Banyan created ID of the offer object.	String	Referred to in the offer redemption schema as byn_offer_id

{
    "data": [
        {
            "id": "6edcde44-f440-5dc2-ad20-5369303a27b0",
            "publisher_offer_id": "e99ea29a-e8d8-531b-9107-ddcd65de3c67",
            "campaign_id": "cf8f9c27-f1da-580f-9316-3350333d234c",
            "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",
          	"currency": "USD",
            "always_on": true,
            "offer_criteria": {
                "order_types": [
                    "in_store"
                ],
                "incl_tags": [
                    "category_description:|:BABY CARE"
                ],
                "excl_tags": [
                    "brand:|:Pampers"
                ],
                "incl_sku": [],
                "excl_sku": [],
                "amount_threshold": "50",
                "fulfillment_count_limit": 2
            },
            "created_ts": "2022-12-06T21:41:38.982506Z",
            "updated_ts": "2022-12-06T21:41:38.982506Z"
        }
    ],
    "errors": []
}

Errors

Error Code	Description	Examples
400	Bad Request	1. Sending in an end date before a start date in POST /offer 2. Including invalid values in POST /offer "order_type"
403	Forbidden
404	Not Found