2. Requesting Offers From Hoox

This page explains the Request Offer API call

What is an Offer

Hoox offer is an object that represent a specific and personalized value proposition granted by a Hoox Partner to your customer (buyer). To get an offer without passing any personal information, you first need to encrypt pieces of data, typically an email address or a phone number using Hoox Encrypt API call . After a hash (or hashes) was created, you send them in the Hoox Request Offer body.

The response object of this call contains an array with one Offer object.

Im most cases, you will only present the offer banner to the user, so the images.web key in the response object is the only one that you'll need.

When Should You Send This Call

Just before you want to present the offer to the buyer, assuming you've already called Hoox Encrypt to generate the hashes (typically in the product page / check out page / cart page).

Request offers from Hoox.

post

Sent after the buyer's email address or phone number were hashed using Hoox encryptor (library or api call). The response is an array containing one offer to be presented to the buyer. If an offer is not granted, the array would be empty.

Body

Payload to be sent in the offer request body.

merchantIdstring · stringRequired

The Merchant ID provided by Hoox.

Example: mrC*gnU19683

branchIdstring · stringRequired

The branch ID provided by Hoox.

Example: ac@gnU121345

apiKeystringRequired

The API Key provided by Hoox.

Example: abc@ut654!

appIdstringOptional

Unique string representing a branch / merchant / website. Used by aggregators. Can also be used to differentiate between different endpoints.

Example: Ab1U82G34hba

storeNamestringOptional

The merchant's store name. Will reflect in Hoox reports.

Example: Times Square

keyPolicystringRequired

The Key Policy key provided by Hoox.

Example: hkp254768901

branchTransactionIdstringOptional

The merchant's transaction id or cart id.If present, it will be sent back in the response object.

Example: lpid24500312

totalAmountnumberRequired

The total amount of the transaction including tax.

Example: 144.4

transactionAmountnumberOptional

The total amount of the transaction without tax.

Example: 100

shippingAmountnumberOptional

The cost of shipping.

Example: 20

taxAmountnumberOptional

The total amount of taxes.

Example: 20.4

taxRatenumberOptional

The tax rate in percentage.

Example: 17

currencyCodestringRequired

ISO 4271 representing the curremcy code.

Example: USD

registeredUserbooleanOptional

True if the user is registered in the Merchants' website. Default is false.

Example: true

userHashesstring[]Required

Array of unique hashed emails and phone numbers representing the user - hashed by Hoox encryptor.

Example: ["mcBne!T$n&Ya"]

Responses

200

Offers Generated. The body contains an array with an offer object

application/json

400

Bad request: invalid input, object invalid

post

HTTPcURLJavaScriptPython

POST /offer HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 358

{
  "merchantId": "mrC*gnU19683",
  "branchId": "ac@gnU121345",
  "apiKey": "abc@ut654!",
  "appId": "Ab1U82G34hba",
  "storeName": "Times Square",
  "keyPolicy": "hkp254768901",
  "branchTransactionId": "lpid24500312",
  "totalAmount": 144.4,
  "transactionAmount": 100,
  "shippingAmount": 20,
  "taxAmount": 20.4,
  "taxRate": 17,
  "currencyCode": "USD",
  "registeredUser": true,
  "userHashes": [
    "mcBne!T$n&Ya"
  ]
}

[
  {
    "name": "Free Shipping",
    "description": "Pay with Mastercard and get free shipping",
    "localizedDescriptions": {
      "en": "Pay with Mastercard and get free shipping",
      "es": "paga con tu Mastercard y obtén envío gratis",
      "ro": "Plătește cu Mastercard și beneficiază de transport gratuit"
    },
    "images": {
      "mobile": "www.images.com/mobile",
      "web": "www.images.com/web",
      "kiosk": "www.images.com/kiosk",
      "terminal": "www.images.com/terminal"
    },
    "currencyCode": "USD",
    "value": 20,
    "hooxReference": "tgc-ima23-sdd345",
    "requestId": "so367i22d",
    "branchTransactionId": "lpid24500312",
    "hooxType": "discount",
    "offerId": "cc212Gre2345",
    "campaignId": "cdf156212Gre25"
  }
]

In case an offer was returned, you should use the images key to get the image url. This image should be presented to the user.

The response body might contain an empty array. In this case you should proceed normally without Hoox.