Creating giveaway offers

To create giveaway rewards through API you can use either:

  • Simple giveaway offer: a quick solution that includes a claiming process with a single API method, this would still require webhook for validation purposes. For this approach the offer has to be configured without users input requirements, for example, t-shirt color, size or fit.

  • Giveaway Offers with multiple choices : this approach is for those who choose to create offers with multiple variants that require players input with selecting available options for example, a t-shirt reward would require size, color and gender options specified before claiming could be completed.

Request giveaway offer data from API

The giveaway offers data can be acquired through API Offers list endpoint or through Offers details endpoint.

The offers list data (see below) can be used to create a giveaway rewards list. You can check an online example at the React JS example game.

{
    "count": 11,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 973,
            "name": "Boost Day 5 retention by rewarding players with a free McFlurry by McDonald's",
            "offer_tag": "copy_394180C9_free_mccafe",
            "is_active": true,
            "claimable": true,
            "offer_thumbnail": "",
            "description": "\nYour progress will be updated within seconds of playing a game match. When you finish 5 game matches, you will be able to claim a free beverage from McDonald's.\n\n \n- Digital voucher.\n- Ready to use immediately.\n- Offer valid at participating McDonald's restaurants.",
            "description_html": "<meta charset=\"utf-8\">\n<p>Your progress will be updated within seconds of playing a game match. When you finish 5 game matches, you will be able to claim a free beverage from McDonald's.</p>\n<p><br><br></p>\n<p> </p>\n<p>- Digital voucher.</p>\n<p>- Ready to use immediately.</p>\n<p>- Offer valid at participating McDonald's restaurants.</p>",
            "category": "Brand rewards",
            "type": "Giveaway",
            "retail_value": null,
            "asset": {
                "title": "Congrats!",
                "asset_image": "https://image.themonetizr.com/offer_asset/2021/01/11/McFlurry.png"
            },
            "prices": [
                {
                    "amount": "0.00",
                    "currency_code": "USD",
                    "compare_amount": "0.00",
                    "compare_currency_code": ""
                }
            ]
        },.....
      ]
}
Offers list example. You can create this list in your game using the data returned from the offers apiOffers list example. You can create this list in your game using the data returned from the offers api

Offers list example. You can create this list in your game using the data returned from the offers api

The data acquired from Offers details endpoint can be used to create an offer view (more here).

{
    "data": {
        "productByHandle": {
            "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzYxNDYxNjE0MTAyNDQ=",
            "title": "Copy of Free McCafe by McDonald's",
            "description": "Your progress will be updated within seconds of playing a game match. When you finish 5 game matches, you will be able to claim a free beverage from McDonald's. - Digital voucher. - Ready to use immediately. - Offer valid at participating McDonald's restaurants.",
            "descriptionHtml": "<meta charset=\"utf-8\">\n<p>Your progress will be updated within seconds of playing a game match. When you finish 5 game matches, you will be able to claim a free beverage from McDonald's.</p>\n<p><br><br></p>\n<p> </p>\n<p>- Digital voucher.</p>\n<p>- Ready to use immediately.</p>\n<p>- Offer valid at participating McDonald's restaurants.</p>",
            "availableForSale": true,
            "onlineStoreUrl": "https://gear.themonetizr.com/products/copy-of-free-mccafe-by-mcdonalds-6",
            "options": [
                {
                    "name": "Title",
                    "values": [
                        "Default Title"
                    ]
                }
            ],
            "images": {
                "edges": [
                    {
                        "node": {
                            "transformedSrc": "https://cdn.shopify.com/s/files/1/0330/7788/7116/products/McFlurry-GIF_41642511-366f-4284-beae-f15220d947bb_350x350.gif?v=1610369472"
                        }
                    },
                ]
            },
            "variants": {
                "edges": [
                    {
                        "node": {
                            "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8zNzg2MTE1MTUwNjYyOA==",
                            "product": {
                                "title": "Copy of Free McCafe by McDonald's",
                                "description": "Your progress will be updated within seconds of playing a game match. When you finish 5 game matches, you will be able to claim a free beverage from McDonald's. - Digital voucher. - Ready to use immediately. - Offer valid at participating McDonald's restaurants.",
                                "descriptionHtml": "<meta charset=\"utf-8\">\n<p>Your progress will be updated within seconds of playing a game match. When you finish 5 game matches, you will be able to claim a free beverage from McDonald's.</p>\n<p><br><br></p>\n<p> </p>\n<p>- Digital voucher.</p>\n<p>- Ready to use immediately.</p>\n<p>- Offer valid at participating McDonald's restaurants.</p>",
                                "description_ios": "\nYour progress will be updated within seconds of playing a game match. When you finish 5 game matches, you will be able to claim a free beverage from McDonald's.\n\n \n- Digital voucher.\n- Ready to use immediately.\n- Offer valid at participating McDonald's restaurants."
                            },
                            "title": "Default Title",
                            "selectedOptions": [
                                {
                                    "name": "Title",
                                    "value": "Default Title"
                                }
                            ],
                            "priceV2": {
                                "currencyCode": "$",
                                "amount": "0.0",
                                "currency": "USD"
                            },
                            "compareAtPriceV2": null,
                            "image": {
                                "transformedSrc": "https://cdn.shopify.com/s/files/1/0330/7788/7116/products/McFlurry-GIF_41642511-366f-4284-beae-f15220d947bb_350x350.gif?v=1610369472"
                            }
                        }
                    }
                ]
            },
            "description_ios": "\nYour progress will be updated within seconds of playing a game match. When you finish 5 game matches, you will be able to claim a free beverage from McDonald's.\n\n \n- Digital voucher.\n- Ready to use immediately.\n- Offer valid at participating McDonald's restaurants.",
            "button_title": "Checkout",
            "claimable": false,
            "retail_value": null,
            "asset": {
                "title": "Congrats!",
                "asset_image": "https://image.themonetizr.com/offer_asset/2021/01/11/McFlurry.png"
            }
        }
    }
}

Submit giveaway offer with API

As described on top if this page, there are two ways of submitting giveaway offers to the API:

Simple claim

API simple claim method.
This process involves two steps:

Create a giveaway API request

This API method (Read more) requires four mandatory input parameters: client_id, client_secret, offer_tag and email. Email is the only parameter that is required from the player.

Remember that all of the giveaway requests requires as webhook for validation. The webhook is used to confirm that the giveaway request was made by legitimate player and is legitimate for your company. Webhook is not the only validation, we perform a secondary validation in fulfillment process.

Visit the API reference to test the simple claim request: https://docs.themonetizr.com/reference/claim

If your giveaway offer requires shipping then a fifth parameter, shipping_address is a mandatory as well. The shipping_address is a required for physical giveaway offers such as t-shirts, mugs, shovels etc. This approach is vest suited for those who want to integrate any digital reward or merchandise that does not require variant selection from players. Below is an example in multiple languages. The request can always be tested from the API reference: https://docs.themonetizr.com/reference/claim

curl --request POST \
  --url https://api3.themonetizr.com/api/claim \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '
{
  "offer_tag": "sample_shirt",
  "client_id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8yOTQxMzUzMzE4O",
  "client_secret": "XYVAZX*&KI(*(())+)*&^%$MJKNJGgbggAJJS",
  "email": "[email protected]"
}
'
import requests

url = "https://api3.themonetizr.com/api/claim"

payload = {
    "offer_tag": "sample_shirt",
    "client_id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8yOTQxMzUzMzE4O",
    "client_secret": "XYVAZX*&KI(*(())+)*&^%$MJKNJGgbggAJJS",
    "email": "[email protected]"
}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"offer_tag\":\"sample_shirt\",\"client_id\":\"Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8yOTQxMzUzMzE4O\",\"client_secret\":\"XYVAZX*&KI(*(())+)*&^%$MJKNJGgbggAJJS\",\"email\":\"[email protected]\"}");
Request request = new Request.Builder()
  .url("https://api3.themonetizr.com/api/claim")
  .post(body)
  .addHeader("Accept", "application/json")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();
import Foundation

let headers = [
  "Accept": "application/json",
  "Content-Type": "application/json"
]
let parameters = [
  "offer_tag": "sample_shirt",
  "client_id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8yOTQxMzUzMzE4O",
  "client_secret": "XYVAZX*&KI(*(())+)*&^%$MJKNJGgbggAJJS",
  "email": "[email protected]"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api3.themonetizr.com/api/claim")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
const options = {
  method: 'POST',
  headers: {Accept: 'application/json', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    offer_tag: 'sample_shirt',
    client_id: 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFWFudC8yOTQxMzUzMzE4O',
    client_secret: 'XYVAZX*&KI(*(())+)*&$MJKNJGgbggAJJS',
    email: '[email protected]'
  })
};

fetch('https://api3.themonetizr.com/api/claim', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

If you request requires a shipping_address from a player, then you will need to acquire the shipping address from your player is some way. The API giveaway claim request will require shipping address as a mandatory field as well. See the request examples below:

curl --request POST \
  --url https://api3.themonetizr.com/api/claim \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '
{
  "shipping_address": {
    "firstName": "John",
    "lastName": "Doe",
    "address1": "c/o Example LLC",
    "address2": "900 Amphitheatre drive",
    "city": "Westminster",
    "country": "US",
    "zip": "90100",
    "province": "CA"
  },
  "offer_tag": "sample_shirt",
  "client_id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8yOTQxMzUzMzE4O",
  "client_secret": "XYVAZX*&KI(*(())+)*&^%$MJKNJGgbggAJJS",
  "email": "[email protected]"
}
'
import requests

url = "https://api3.themonetizr.com/api/claim"

payload = {
    "shipping_address": {
        "firstName": "John",
        "lastName": "Doe",
        "address1": "c/o Example LLC",
        "address2": "900 Amphitheatre drive",
        "city": "Westminster",
        "country": "US",
        "zip": "90100",
        "province": "CA"
    },
    "offer_tag": "sample_shirt",
    "client_id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8yOTQxMzUzMzE4O",
    "client_secret": "XYVAZX*&KI(*(())+)*&^%$MJKNJGgbggAJJS",
    "email": "[email protected]"
}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"shipping_address\":{\"firstName\":\"John\",\"lastName\":\"Doe\",\"address1\":\"c/o Example LLC\",\"address2\":\"900 Amphitheatre drive\",\"city\":\"Westminster\",\"country\":\"US\",\"zip\":\"90100\",\"province\":\"CA\"},\"offer_tag\":\"sample_shirt\",\"client_id\":\"Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8yOTQxMzUzMzE4O\",\"client_secret\":\"XYVAZX*&KI(*(())+)*&^%$MJKNJGgbggAJJS\",\"email\":\"[email protected]\"}");
Request request = new Request.Builder()
  .url("https://api3.themonetizr.com/api/claim")
  .post(body)
  .addHeader("Accept", "application/json")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();
import Foundation

let headers = [
  "Accept": "application/json",
  "Content-Type": "application/json"
]
let parameters = [
  "shipping_address": [
    "firstName": "John",
    "lastName": "Doe",
    "address1": "c/o Example LLC",
    "address2": "900 Amphitheatre drive",
    "city": "Westminster",
    "country": "US",
    "zip": "90100",
    "province": "CA"
  ],
  "offer_tag": "sample_shirt",
  "client_id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8yOTQxMzUzMzE4O",
  "client_secret": "XYVAZX*&KI(*(())+)*&^%$MJKNJGgbggAJJS",
  "email": "[email protected]"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api3.themonetizr.com/api/claim")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
const options = {
  method: 'POST',
  headers: {Accept: 'application/json', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    shipping_address: {
      firstName: 'John',
      lastName: 'Doe',
      address1: 'c/o Example LLC',
      address2: '900 Amphitheatre drive',
      city: 'Westminster',
      country: 'US',
      zip: '90100',
      province: 'CA'
    },
    offer_tag: 'sample_shirt',
    client_id: 'Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8yOTQxMzUzMzE4O',
    client_secret: 'XYVAZX*&KI(*(())+)*&^%$MJKNJGgbggAJJS',
    email: '[email protected]'
  })
};

fetch('https://api3.themonetizr.com/api/claim', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

The request returns a JSON format response. The response includes the details about the performed claim request. The response can return three types of HTTP status codes, see below.

{
    "status": "success",
    "message": "Your order has been sent out",
    "checkout_id": "a291dC8xNzJkNjFlZmFmNzQ5OWJlOGQxNGQwNzhkYmU5NjVlMz9rZXk9NWFmNzhjOThiOWI3OTYyZDc1ZmRhYjUyYTVWY5ODI=",
    "web_url": "https://monetizr-development-store.com/25159794739/checkouts/172d61efaf7499b4d078dbe965e3?key=5af78c98b9b7962dab52a5baf982",
    "ready": true,
    "assets": {
      "title": "You have unlocked the secret treasure",
      "image": "https://image.themonetizr.com/offers/1234565432/13456789765432_o.png"
    }
}
{
"status":"Error"
"message":"This request is missing a webhook for validation!"
}
{
"status":"error"
"message":"The specified information was not found!"
}

Giveaway Offers with multiple choices

Read more: Giveaway offers with multiple choices.

This approach is for those who choose to create offers with multiple variants that require players input with selecting available options for example, a t-shirt reward would require size, color and gender options specified before claiming could be completed.

In this case a simple giveaway claiming will not be possible as this requires input from players such as choosing appropriate size and color as well as choosing from available shipping options. For those giveaway offers you will have to follow the merchandise approach - https://docs.themonetizr.com/docs/creating-offer-view and then you will have to create a purchase offer with multiple choices (read more).

Checking the giveaway status

After you have created a valid claim request for giveaway offer, you can check for the status using another API method: ref:checkoutstatus and using response data from giveaway claim request as input. You will need to acquire checkout_id from giveaway claim request (see the request above or visit claim request api reference).

curl --request POST \
  --url https://api3.themonetizr.com/api/products/checkoutstatus \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '
{
  "checkoutId": "Z2lkOvcGlmeS9Qcm9kdWN0VmFyaWFudC8yOTQxMzUzMzE4ODExOQ=="
}
'
import requests

url = "https://api3.themonetizr.com/api/products/checkoutstatus"

payload = {"checkoutId": "Z2lkOvcGlmeS9Qcm9kdWN0VmFyaWFudMzUzMzE4ODExOQ=="}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"checkoutId\":\"Z2lkOvcGWN0VmFyaWFudC8yOTQxMzUzMzE4ODExOQ==\"}");
Request request = new Request.Builder()
  .url("https://api3.themonetizr.com/api/products/checkoutstatus")
  .post(body)
  .addHeader("Accept", "application/json")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();
import Foundation

let headers = [
  "Accept": "application/json",
  "Content-Type": "application/json"
]
let parameters = ["checkoutId": "Z2lkOvcGlmeS9Qcm9C8yOTQxMzUzMzE4ODExOQ=="] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api3.themonetizr.com/api/products/checkoutstatus")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
const options = {
  method: 'POST',
  headers: {Accept: 'application/json', 'Content-Type': 'application/json'},
  body: JSON.stringify({checkoutId: 'Z2lkOvcGlmeS9QcaWFudC8yOTQxMzUzMzE4ODExOQ=='})
};

fetch('https://api3.themonetizr.com/api/products/checkoutstatus', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Until now, the player has already received an order confirmation email with the information. This giveaway status request can be used to show customized in-game message for the player or it can be used to create your own registers with orders. The response can be seen below and in api reference: https://docs.themonetizr.com/reference/offers#checkoutstatus

{
"status":"success"
"message":"Order has been received"
"order_number":"#BL9754",
"fulfillment_status": "Processing",
"tracking_number": "#267700",
"tracking_url:"https://example.com"
}

Did this page help you?