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

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
byn_campaign_idBanyan created unique ID for the campaignStringYes
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
byn_publisher_idBanyan created client/finx ID that the campaign is fulfilled byStringYes
amount_back_limitThe highest amount the customer can receive for the offerStringNoRelevant when the offer is a % back of a purchase. If left null, there will be no limit.
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.
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
repeat_amountHow many times can the offer be reused by the same card/accountStringNoDefault is 0. A 0 value means that the offer can only be used 1 time

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,
    "byn_publisher_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",
    "offer_criteria": {
        "order_types": [
            "in_store"
        ],
        "incl_tags": [
            "category_description:|:BABY CARE"
        ],
        "excl_tags": [
            "brand:|:Pampers"
        ],
        "incl_sku": [],
        "excl_sku": [],
        "amount_threshold": "50.00",
        "repeat_amount": 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",
            "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-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