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

NameDescriptionTypeRequiredNotes
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 dataStringYes
nameThe name given to the offerStringNo
byn_campaign_idBanyan created unique ID for the campaignStringYesSee how to set up a campaign here
return_receipt_detailWhether the offer redemption record delivered back to the FinX has full receipt details or simply the resultBooleanNoValid values are true, false. Default is true
byn_advertiser_idBanyan created client/merchant ID that the campaign is advertisingStringYes
amount_back_limitThe highest amount the customer can receive for the offer on a given transactionStringNoRelevant 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_dollarRate of the reward per dollarStringYesExamples noted below
amount_back_typeWhether the reward is dollars or pointsStringYesPotential values: dollars, points, miles
start_tsWhen the offer is valid to be redeemedRFC3339YesShould be sent in UTC
expiration_tsWhen the offer endsRFC3339YesShould 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.
currencyAlphabetic currency code associated with the value in ISO 4217 formatStringYesUse three character currency code, Default is USD
allow_activation_after_purchaseWhether opting into the offer has to happen before the purchase of the qualified items for it to fulfill the reward criteriaBooleanYesDefault is false
prorate_qualified_spendWhether all payments on the transaction count towards the offer criteria or only the payment that has the card activationBooleanYesDefault is true
always_onWhether an activation is needed for a consumer to qualify for an offerBooleanYesDefault is false
offer_criteriaTop level objectObject

offer.offer_criteria

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

NameDescriptionTypeRequiredNotes
order_typesPurchase method such as web, in_store, or phoneArray of stringsYesThere is no default, but if you do not add any values here, no offer redemptions will be created
incl_tagsKey value pairs that represent item attributes that are valid for the offerArray of key value stringsNo
excl_tagsKey value pairs that represent item attributes that are invalid for the offerArray of key value stringsNo
incl_skuSKUs that are included in the offerArray of stringsNo
excl_skuSKUs that are excluded from the offerArray of stringsNo
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 is not a valid value

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

NameDescriptionTypeNotes
idBanyan created ID of the offer object.StringReferred 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 CodeDescriptionExamples
400Bad Request1. Sending in an end date before a start date in POST /offer
2. Including invalid values in POST /offer "order_type"
403Forbidden
404Not Found