Guides

Offer Segmentation

Suggest Edits

You may want to show different offers to different users or user segments based on their account details.

  • Certain offers might only be applicable to certain users (e.g. users over a certain level, or a VIP user segment).
  • Other offers might only be available to a specific user or user segment for a limited amount of time (e.g. a start-of-season bonus).
  • You may want to prevent users from buying more than a certain quantity of an offer (e.g. season passes, limited to one per user).

This guide covers how we handle these restrictions in your live storefront.

(Note: this guide covers setting up per-user restrictions. You can also set up time limits for offers for all users, even if they're not logged in, by setting time limits on the offer. See here for more details.)

Configure your offer for targeting

By default, offers are available for purchase to all users. Offers must be marked with isTargetedOffer: true for any restrictions to be applied.

If an offer is restricted, but you'd still like to have it displayed in the store, you can set shouldPreviewTargetedOffer: true. The offer will be shown, but marked as not yet unlocked.

Offers marked as isTargetedOffer: false will always be shown (and any returned purchase limits will be ignored).

Setting isTargetedOffer: true and shouldPreviewTargetedOffer: true will also show the offer to users who have not yet logged in, but will prompt them to log in before proceeding.

See here for more on configuring these values.

Send inventory limits

When a user logs in to the store with their in-game account, we send the account.getInventory callback to your server. (See Webhooks and Callbacks for more on callbacks and setting up an event listener.) Note that we set a time limit of five seconds for the request, since we need a response from your servers before we can display the storefront to the user.

The callback has the user's unique account ID attached to the request, which you can use to determine the appropriate inventory restrictions for that user's account. Here's an example request we'll make to your server:

curl --request POST \
     --url <your callback URL> \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     # see https://docs.neonpay.com/docs/webhooks-and-callbacks#validate-request-signature
     --header 'X-Neon-Digest: <Neon digest>'
     --data '
{
	"account": "abcd1234efgh5678"
}
'

Your response should contain a list of inventory restrictions, with the following format:

  • sku: the SKU of the offer being restricted
  • purchased: the quantity of this offer the user has already purchased
  • limit: the total amount of this offer the user is eligible to purchase
  • startTime and durationInSeconds (optional): the time (as an ISO timestamp) after which this offer should be made available for purchase, and the duration (in seconds) after startTime for which the offer should be available

To summarize:

  • If isTargetedOffer: false, the offer is shown.
  • If isTargetedOffer: true:
    • If the offer is not returned in the callback response, and shouldPreviewTargetedOffer: false, it is not shown. If shouldPreviewTargetedOffer: true, the offer is shown, but marked as not yet unlocked.
    • If the offer is returned with a startTime and durationInSeconds, but the current time is not between startDate and startDate + durationInSeconds, the offer is not shown.
    • If the offer is returned, but purchased >= limit, the offer is shown, but unavailable for purchase and marked as already purchased.
    • Otherwise, the offer is shown and purchasable.

Here's an example response:

[
  {
    "sku": "LEGENDARY_BUNDLE",
    "purchased": 0,
    "limit": 1
  },
  {
    "sku": "NOT_AS_LEGENDARY_BUNDLE",
    "purchased": 1,
    "limit": 1
  },
  {
    "sku": "ARGUABLY_MORE_LEGENDARY_BUNDLE",
    "purchased": 0,
    "limit": 1,
    "startTime": "2023-12-09T00:00:00.000Z",
    "durationInSeconds": 432000
  }
]

The resulting storefront would be as follows:

  • LEGENDARY_BUNDLE is shown as an ordinary offer, and is available for purchase.
  • NOT_AS_LEGENDARY_BUNDLE is shown as greyed-out and unavailable to purchase (with an explanation that the purchase limit has been reached).
  • ARGUABLY_MORE_LEGENDARY_BUNDLE is hidden before 2023-12-09 at midnight UTC, shown and available for purchase between 2023-12-09 and 2023-12-14 at midnight (i.e., 5 days after the start time), and hidden afterwards.
  • EVEN_LESS_LEGENDARY_BUNDLE, which is not returned in the response, is hidden altogether. However, if the offer has shouldPreviewTargetedOffer: true, the offer is shown, but marked as not yet unlocked.

Updated over 1 year ago