Guides

Receive Offers and Cashback data

Suggest Edits

The Mthmr Cashback API allows you to retrieve the data for:

  • Cashback payments
  • All active offers

This page will explain how to do so in more detail in the following sections.

Retrieve cashback payments

You can also retrieve a list of all cashback payments processed within a specific date range using the Get Cashback Payments endpoint. This is a useful feature for accounting since the response will deliver details about the payments, such as the customer and the amount of cashback.

Use the date_from and date_to query-params to inform the date range, just as in the code block below:

curl --request GET \
     --url 'https://bank-api.mthmr.com/cashback-payments' \
     --header 'accept: application/json' \
     --header 'current_page: 1' \
     --header 'date_from: 2024-01-01' \
     --header 'date_to: 2025-01-01' \
     --header 'page_size: 10'

{
    "total_count": 11,
    "current_page": 1,
    "page_size": 2,
    "date_from": "2024-07-05",
    "date_to": "2024-08-05",
    "transactions": [
        {
            "transaction_id": "q1356753453dd5453g13kq1q14qq11q3",
            "country": "KSA",
            "city": "Ryiadh",
            "date": "2024-07-05T10:27:03.987662",
            "cashback_amount": 200.1,
            "offer_id": 336,
            "customer_id": "a8de52aa-49e7-4e5c-bb66-1c82ac1d"
        },
        {
            "transaction_id": "q1356753453dd5453g13kq1q14qq11q3432",
            "country": "KSA",
            "city": "Ryiadh",
            "date": "2024-07-05T10:27:03.987662",
            "cashback_amount": 33.3,
            "offer_id": 336,
            "customer_id": "a8de52aa-49e7-4e5c-bb66-1c82ac1e"
        }
      ]
}

The response body will present a list of payments. Each payment will have the following parameters:

  • total_count: The total amount of the transactions .
  • current_page: The current page.
  • page_size: The total amount of transactions per page.
  • date_from: The date from of the requested transactions.
  • date_to: The date to of the requested transactions.
  • transactions: The list of the transactions.

The transaction object. Each transaction will have the following parameters:

  • transaction_id: The unique identifier for the transaction.
  • country: The country of the transaction.
  • city: The city of the transaction.
  • date: The date of the cashback payment.
  • cashback_amount: The amount of the cashback payment.
  • offer_id: The unique identifier for the offer.
  • customer_id: The unique identifier for the customer.

Retrieve all offers

Using the Get All Active Offers endpoint, you can retrieve the list of all Offers available to present to your customers.

The request only requires you to input the authenticationtoken in its headers. The following code block presents an example of the request and the response.

curl --request GET \
     --url https://bank-api.mthmr.com/active-offers \
     --header 'Token: <Your token>' \
     --header 'accept: application/json'

[
  {
        "offer_id": 336,
        "name": "Eid 36+ male",
        "merchant_name": "MTHMR",
        "merchant_logo": "https://axcroydp3nk5.objectstorage.me-jeddah-1.oci.customer-oci.com/n/axcroydp3nk5/b/cashback-app-bucket/o/brand/1775468_logo_1518417565_n_(1)_wPugNPbX.png",
        "warranty": 5,
        "age": [
            "36–45",
            "46–60",
            "61+"
        ],
        "gender": [
            "Male"
        ],
        "category_name": "Family",
        "discount": 40.0,
        "valid_from": "2024-08-06",
        "valid_to": "2024-09-06"
    },
    {
        "offer_id": 337,
        "name": "Eid",
        "merchant_name": "MTHMR",
        "merchant_logo": "https://axcroydp3nk5.objectstorage.me-jeddah-1.oci.customer-oci.com/n/axcroydp3nk5/b/cashback-app-bucket/o/brand/1775468_logo_1518417565_n_(1)_wPugNPbX.png",
        "warranty": 10,
        "age": [
            "0-18",
            "19-24",
            "25-35",
            "36–45",
            "46–60",
            "61+"
        ],
        "gender": [
            "Male",
            "Female"
        ],
        "category_name": "Family",
        "discount": 40.0,
        "valid_from": "2024-08-06",
        "valid_to": "2024-09-06"
    }
]

The response body may contain one or more offers. Each offer will be described by a JSON object composed of the following parameters:

  • offer_id: The unique identifier of the offer.
  • name: The name of the offer.
  • merchant_name: The name of the merchant.
  • merchant_logo: URL of the merchant's logo.
  • warranty: Warranty refers to the days the payout is delayed, as customers can return the purchase until the warranty lasts.
  • age: The array of age groups specifies the eligible age ranges for the offer.
  • gender: The array of genders specifies the eligible gender categories for the offer.
  • category_name: The category name of the offer.
  • discount: The discount percentage of the offer.
  • valid_from: Start date of the offer validity.
  • valid_to: End date of the offer validity.

Webhook Updates for Offer Changes

If an offer is updated or its status changes (e.g., active: false/true), the updated offer information is automatically sent to your registered webhook. This ensures that your system always has the latest data about the offers.

  • Trigger: An update or status change in an offer.
  • Data Sent: The entire updated offer object, similar to the structure provided above.
  • Webhook URL: The URL where the updated offer data is sent should be configured during the initial setup of your system.

Updated 3 months ago