Payer Promotion Dialog

Get new payers for your game

The Payer Promotion dialog helps bring more payers to your game, by encouraging players to make their first purchase. Facebook sponsors this feature, enabling you to offer certain people a discount on your game's virtual currency or items.


Some of the benefits of implementing the Payer Promotion feature are:

  • Get more paying customers — a user who pays once is more likely to pay again in the future. In one case, 20% of people who made a first-time purchase came back to spend more within a month. Similar results have been seen in other scenarios where the discount was offered to users who hadn't spent in the last 30 days.
  • Facebook sponsors this promotion - you receive your revenue share just as in a regular purchase.
  • Easy to implement — with just a few simple steps, you can start converting more players of your game into payers.
  • The promotion dialog will be displayed in the same window as your game.
  • Players can use their PayPal credentials as an option to obtain the discount.
  • No authorization cost on the player's account.
A sample Payer Promotion dialog


Define a promotional item or bundle

First, you must implement either an item or virtual currency for sale within your game so that the promotion can be redeemed.

Make sure that you use discrete pricepoints ($1 or $0.99) for all the currencies supported on your game to increase conversion.

Example OG Object:

<head prefix="og: fb:">
  <meta property="og:type" content="og:product" />
  <meta property="og:locale" content="en_US" />
  <meta property="og:title" content=“30 Coins + 1 Bomb" />
  <meta property="og:plural_title" content=“30 Coins + 1 Bomb" />
  <meta property="og:image" content="" />
  <meta property="og:url" content="" />
  <meta property="og:description" content=“Free 30 Coins + 1 Bomb!” />
  <meta property="product:price:amount" content=“3.00"/>
  <meta property="product:price:currency" content="USD"/>
  <meta property="product:price:amount" content=“2.99"/>
  <meta property="product:price:currency" content="EUR"/>

Please note that the item or currency that is awarded in the promotion needs to have a maximum value of USD 3. If the value is greater than USD 3 or it's equivalent on other currencies, an error will be thrown.


Before displaying the payer promotion, you should determine if the player is eligible to get the promotion. By issuing an HTTP GET request to player's ID Graph API endpoint, specifying the is_eligible_promo field (/USER_ID?fields=is_eligible_promo) with a user access token you can obtain the player's eligibility.

An example API request:


This query returns the following data:

Parameter Type Value



The value 1 indicating the player is eligible; 0 if the player isn't eligible. The value will always return 1 for Payment Testers



The user id

Invoking the Promotion dialog

Assuming the player is eligible for the promotion, you can invoke the custom Promotion dialog. When a player clicks on your custom promotion button, invoke the dialog using the Facebook's SDK for JavaScript FB.ui function:

var params = {
  action: 'payer_promotion'
  method: 'payer_promotion',
  quantity: 1,
  product: 'http://currency.object.url',

var callback = function(e){ console.log(e) };

FB.ui(params, callback);
Parameter Type Description



The constant payer_promotion



The constant payer_promotion



(optional) Defines the number of units you'd like to reward the user with. Defaults to 1.



The URL to your OG product or currency



(optional) Developer-generated unique identifier for the transaction. If not provided at the time of invocation, it'll default to the string discount: plus the Unix timestamp.

Promotion Fulfillment

Once the player has gone through the flow, the Javascript callback will be fired. The object passed as a parameter to the callback will have information that will help you fulfill the offer.

In addition, you'll also receive a webhooks update once the promotion has been fulfilled upon which you must award the player with the corresponding amount of your in-game currency or item.

Below is an example JavaScript object that would be returned in the case of a successful purchase completion.

  payment_id: 495869257196092,
  amount: "5.00",
  currency: "USD",
  quantity: "1", 
  status: "completed",
  request_id: "discount:1435780382",
  signed_request: "7QYHzKqKByA7fjiqJUh2bxFvEdqdvn0n_y1zYiyN6tg.eyJhbGCJxdWFudGl0eSI6IjEiLCJzdGF0dXMiOiJjb21wbGV0ZWQifQ"
Parameter Type Description



The Facebook-generated unique identification number for this payment. Use this ID to query more details about the transaction through the Payment Graph API



The total amount paid by the player.



The currency in which the payment was made.



The quantity of the item the user purchase.



(Optional) The developer-generated unique identifier for the transaction. If not provided at the time of invocation, it'll default to the string discount: plus the Unix timestamp.



The status of the order. For the promotion dialog, this should always be set to completed on promotion redemption.



Contains extra information about the purchase. For more information on handling the signed request, please refer to the How-to: Local Currency Payments - Order Fulfillment doc.

Best Practices

Below are a few recommended best practices that have shown to work best in games that are using payer promotions.

Check Eligibility Early

Make sure that you check the player's eligibility while loading the game. This way you can offer the promotion when the player lands in the game.

Caesar's Casino

Adding an incentive

We've seen that the promotion drives the best results once it's paired with a give away of extra in-game items. This pairing could range from a free set of lives or energy to rare items and resources.

Diamond Dash

Display offer on game load

A prominent display when the player loads the game or after their first round will ensure that the player knows that they're eligible for the promotion.

Heart of Vegas

Context and Timing

Showing the promotion at a point in the game where premium currency can best improve a player's play experience could maximize the impact of your promotion. For example, showing the promotion alongside with a free extra life just after the player has run out of lives would maximize the impact of your offer.

Criminal Case

Add the offer to your current store

Adding the offer to your game's store will remind your players that they're eligible for the promotion when they open the store.

Top Eleven

Make a Personalized Offer

Personalized offers can yield more interest from your players. Giving a player different options to choose from will represent better conversion rates for the promotion.

Bingo Blitz