Only one API call

The Luckycycle® flow boils down to only one API call made by the merchant store to the Luckycycle® server. We call it the "poke": it sends data about the current order (such as the order value, the client's name, etc.) in our backend.

Our patented algorithm calculates if the current client is a potential winner or loser.

The only thing to do is then to wait for the response form the API, which will provide a piece of HTML that needs to be inserted in the order confirmation page.

📘

Pokes can be refused

If payment or completion of the survey is not confirmed (e.g. cash on delivery), the user cannot participate to the Luckycycle® campaign. There can be many rules (set in the Luckycycle backend) that can block a "poke". In those cases the client will not see the Luckycycle content.

The "poke"

👍

Operation ID and API Key

If you don't have the Operation ID and API Key, ask your Luckycycle representative to give them to you. They are unique to your campaign and wil allow you to integrate the Luckycycle game securely.

Poke URL

In order to send a poke, send a POST request to this URL :

https://www.luckycycle.com/api/v1/operations/{OPERATION_ID}/poke

Mandatory header

Your API request won't work without this mandatory header:

X-LuckyApiKey: {API_KEY}

Mandatory payload data

The parameters of your request must contain informations about your client's order. These are the required variables:

The following variables are optional:

The cart

The content of the cart should also be sent in the API call whenever you want to apply a campaign on a selection of particular products and not on the whole catalog.

In the post data of the "poke", add an array called "cart" and loop through each product contained in the cart.

Here are the variables needed for each product in the cart:

👍

Cart

The only mandatory fields for a cart item are "price" and "quantity", but the filtering is usually made on product IDs or category IDs (e.g. target only products from category "diet coke").

Example of a JSON structure that can be sent with the "poke"

{
  	"firstname": "John",
  	"lastname": "Smith",
  	"email": "[email protected]",
    "language": "en",
    "user_uid": "U34566",
    "item_uid": "654345809",
  	"item_value": "45.99",
    "payment_method":"VISA",
    "segment":"A",
    "channel":"mobile",
    "cart": [
        {
            "price": "50.5",
            "quantity": "1",
            "product_id": "255645",
            "category_id": "3",
            "manufacturer_id": "Acme",
            "name":"iPhone 6S plus"
        },
        {
            "price": "30",
            "quantity": "2",
            "product_id": "265745",
            "category_id": "1",
            "manufacturer_id": "Big Kahuna",
            "name":"Kiteboard HXS88"
        },
        {
            "price": "11.99",
            "quantity": "3",
            "product_id": "2623423",
            "category_id": "2",
            "manufacturer_id": "Morley",
            "name":"Harley Davidson Iron 883"
        }
    ]
}

Response from the "poke"

If the "poke" was successful and the credentials (API key and operation ID) validated, the Luckycycle server will send back the following response:

{
  "can_play": true,
  "message": "OK",
  "item_uid": "683083",
  "user_uid": "514856",
  "computed_hash": "0fd5aebe2d1f5414ab29c313ad27435e",
  "poke_counter": 2,
  "cluster_id": null,
  "user_played": 1,
  "value_played":"50.00",
  "html_data":"{{HTML_CODE_TO_INSERT_INTO_THANK_YOU_PAGE}}",
  "email_data":"{{HTML_CODE_TO_INSERT_INTO_EMAIL}}",
  "box_visible": true
}

When you get this response, you need to display the content of the "html_data" variable on the order confirmation page template, usually just below the main confirmation message.

For example in PHP, you would write "echo html_data" in the order confirmation template.

This "html_data" will draw an iframe with the Luckycycle content. The content's layout can be changed in the operation dashboard on https://www.luckycycle.com.

In case of error, no iframe will be shown at all, and the JSON returned by the API will look like this:

{
    "message": "bad_api_key",
    "error": 600,
    "can_play": "false"
}

📘

Error codes

The full list of error code is available on this page.

The rest of the flow happens in the Luckycycle iframe, so at this point your job is done!