curl -X POST \
  'https://{YOUR_GRANT_AWARD_ENDPOINT}' \
  -H 'Content-Type: application/json' \
  -H 'x-publisher-token: <x-publisher-token>' \
  -H 'signature: <signature>' \
  -d '{
    "orderId": "12345678",
    "purchaseId": "abc123xyz789",
    "appChargePaymentId": "pay_9876543210",
    "purchaseDateAndTimeUtc": "2024-07-21T14:17:27.329Z",
    "playerId": "player_12345",
    "bundleName": "Starter Pack",
    "bundleId": "684044555ed01178ed2c0b3b",
    "sku": "starterpack",
    "products": [
      {
        "amount": 1000,
        "sku": "prod22224448763533",
        "name": "Gold Coins"
      }
    ],
    "priceInDollar": 999,
    "priceInCents": 999,
    "subTotal": 850,
    "tax": 149,
    "taxRate": 17.5,
    "taxInDollar": 149,
    "currency": "USD",
    "currencyExchangeCost": 0,
    "action": "purchase",
    "actionStatus": "completed",
    "originalPriceInDollar": 1499,
    "paymentPriceInDollar": 999,
    "paymentMethod": "card",
    "countryCode2": "US",
    "priceTotalInDollar": 1148,
    "playerEmail": "john.doe@example.com",
    "sessionMetadata": "{
      "userId": "12345",
      "level":10
    }",
    "receiptId": "receipt_abc123",
    "estimatedPublisherNetAmount": 850.50,
    "estimatedAppchargeFee": 148.50,
    "pricePointMetadata": 999,
    "createdByIp": "192.168.1.1",
    "zipCode": "10001",
    "awardFlow": "auto",
    "promoCodeName": "SUMMER2024",
    "discount": 100.0,
    "discountRatePoints": "10",
    "storeMetadata": {
      "productsSequenceIndex": 1,
      "offerType": "Bundle",
      "utms": {
        "utmSource": "Facebook",
        "utmMedium": "email",
        "utmCampaign": "spring_sale"
      }
    }
  }'

{
  "publisherPurchaseId": "222673459829966773354378"
}

Awards

Grant Award Callback

This is a callback API. Appcharge calls this endpoint on your server when specific events occur.

Notifies your system to grant an award to a customer.

Appcharge calls this endpoint after a customer payment is finalized or when a free offer is collected.

When your server responds with a valid publisherPurchaseId, Appcharge redirects the customer to the success page confirming their purchase.

Your server must return a valid publisherPurchaseId value to confirm the award has been sucessfully granted. If the property is missing or invalid, the award is marked as unsuccessful, and an alert is triggered.

POST

{YOUR_GRANT_AWARD_ENDPOINT}

curl -X POST \
  'https://{YOUR_GRANT_AWARD_ENDPOINT}' \
  -H 'Content-Type: application/json' \
  -H 'x-publisher-token: <x-publisher-token>' \
  -H 'signature: <signature>' \
  -d '{
    "orderId": "12345678",
    "purchaseId": "abc123xyz789",
    "appChargePaymentId": "pay_9876543210",
    "purchaseDateAndTimeUtc": "2024-07-21T14:17:27.329Z",
    "playerId": "player_12345",
    "bundleName": "Starter Pack",
    "bundleId": "684044555ed01178ed2c0b3b",
    "sku": "starterpack",
    "products": [
      {
        "amount": 1000,
        "sku": "prod22224448763533",
        "name": "Gold Coins"
      }
    ],
    "priceInDollar": 999,
    "priceInCents": 999,
    "subTotal": 850,
    "tax": 149,
    "taxRate": 17.5,
    "taxInDollar": 149,
    "currency": "USD",
    "currencyExchangeCost": 0,
    "action": "purchase",
    "actionStatus": "completed",
    "originalPriceInDollar": 1499,
    "paymentPriceInDollar": 999,
    "paymentMethod": "card",
    "countryCode2": "US",
    "priceTotalInDollar": 1148,
    "playerEmail": "john.doe@example.com",
    "sessionMetadata": "{
      "userId": "12345",
      "level":10
    }",
    "receiptId": "receipt_abc123",
    "estimatedPublisherNetAmount": 850.50,
    "estimatedAppchargeFee": 148.50,
    "pricePointMetadata": 999,
    "createdByIp": "192.168.1.1",
    "zipCode": "10001",
    "awardFlow": "auto",
    "promoCodeName": "SUMMER2024",
    "discount": 100.0,
    "discountRatePoints": "10",
    "storeMetadata": {
      "productsSequenceIndex": 1,
      "offerType": "Bundle",
      "utms": {
        "utmSource": "Facebook",
        "utmMedium": "email",
        "utmCampaign": "spring_sale"
      }
    }
  }'

{
  "publisherPurchaseId": "222673459829966773354378"
}

curl -X POST \
  'https://{YOUR_GRANT_AWARD_ENDPOINT}' \
  -H 'Content-Type: application/json' \
  -H 'x-publisher-token: <x-publisher-token>' \
  -H 'signature: <signature>' \
  -d '{
    "orderId": "12345678",
    "purchaseId": "abc123xyz789",
    "appChargePaymentId": "pay_9876543210",
    "purchaseDateAndTimeUtc": "2024-07-21T14:17:27.329Z",
    "playerId": "player_12345",
    "bundleName": "Starter Pack",
    "bundleId": "684044555ed01178ed2c0b3b",
    "sku": "starterpack",
    "products": [
      {
        "amount": 1000,
        "sku": "prod22224448763533",
        "name": "Gold Coins"
      }
    ],
    "priceInDollar": 999,
    "priceInCents": 999,
    "subTotal": 850,
    "tax": 149,
    "taxRate": 17.5,
    "taxInDollar": 149,
    "currency": "USD",
    "currencyExchangeCost": 0,
    "action": "purchase",
    "actionStatus": "completed",
    "originalPriceInDollar": 1499,
    "paymentPriceInDollar": 999,
    "paymentMethod": "card",
    "countryCode2": "US",
    "priceTotalInDollar": 1148,
    "playerEmail": "john.doe@example.com",
    "sessionMetadata": "{
      "userId": "12345",
      "level":10
    }",
    "receiptId": "receipt_abc123",
    "estimatedPublisherNetAmount": 850.50,
    "estimatedAppchargeFee": 148.50,
    "pricePointMetadata": 999,
    "createdByIp": "192.168.1.1",
    "zipCode": "10001",
    "awardFlow": "auto",
    "promoCodeName": "SUMMER2024",
    "discount": 100.0,
    "discountRatePoints": "10",
    "storeMetadata": {
      "productsSequenceIndex": 1,
      "offerType": "Bundle",
      "utms": {
        "utmSource": "Facebook",
        "utmMedium": "email",
        "utmCampaign": "spring_sale"
      }
    }
  }'

{
  "publisherPurchaseId": "222673459829966773354378"
}

Headers

x-publisher-token

string

Publisher token.

signature

string

Signature.

Body

application/json

orderId

string

Order ID in the Publisher Dashboard.

Example:

"68e25eebdcb1278"

purchaseId

string

Purchase ID.

Example:

"pr_750b85591e1643685718e5443xyz789"

appChargePaymentId

string

Payment ID.

Example:

"68e25eebd76543210"

purchaseDateAndTimeUtc

string<date-time>

Date and time of the purchase in UTC.

Example:

"2024-07-21T14:17:27.329Z"

playerId

string

Player ID returned in the player authentication process.

Example:

"8533676467"

bundleName

string

Offer name.

Example:

"Starter Pack"

bundleId

string

Offer ID.

Example:

"684044555ed01178ed2c0b3b"

sku

string

Offer ID you provided.

Example:

"starterpack"

products

object[]

Product details.

Show child attributes

priceInDollar

integer

Price before taxes in US cents. Converted in real time.

Example:

999

priceInCents

integer

Total price paid in the lowest unit of the local currency.

Example:

999

subTotal

integer

Price paid before taxes in the lowest unit of the local currency.

Example:

850

tax

integer

Tax amount in the lowest unit of the local currency.

Example:

149

taxRate

number

Tax rate (percentage).

Example:

17.5

taxInDollar

integer

Tax amount in US cents.

Example:

149

currency

string

ISO 4217 currency code.

Example:

"USD"

currencyExchangeCost

number

Currency exchange cost in US cents.

Example:

0

action

enum<string>

Customer action.

Available options:

purchase,

bonus

Example:

"purchase"

actionStatus

enum<string>

Action status.

Available options:

completed,

failed

Example:

"completed"

originalPriceInDollar

integer

Base price of the offer in US cents. If pricePointMetadata is provided and you're using Appcharge's Web Store, its value overrides this one.

Example:

1499

paymentPriceInDollar

integer

Base price of the offer in US cents.

Example:

999

paymentMethod

string

Payment method.

Example:

"card"

countryCode2

string

Country code (2-letter).

Example:

"US"

priceTotalInDollar

integer

Price paid including taxes. Converted in real time to US cents.

Example:

1148

playerEmail

string

Email address.

Example:

"john.doe@example.com"

sessionMetadata

string

An object for passing data.

Example:

{ "userId": "12345", "level": 10 }

receiptId

string

Receipt ID.

Example:

"receipt_abc123"

estimatedPublisherNetAmount

number

Estimated Publisher net amount in US cents.

Example:

850.5

estimatedAppchargeFee

number

Estimated Appcharge fee in US cents.

Example:

148.5

pricePointMetadata

integer

Base price of the price point in US cents.

Example:

999

createdByIp

string

IP address from which the order was made.

Example:

"192.168.1.1"

zipCode

string | null

Zip code (US/Canada only).

Example:

"10001"

awardFlow

enum<string>

Award flow. Automatic or manual retry via the Publisher Dashboard.

Available options:

auto,

manual_retry

Example:

"auto"

Promo code name.

Example:

"SUMMER2024"

discount

number

Discount amount in the currency the order was placed in.

Example:

100

discountRatePoints

number

Discount rate (percentage).

Example:

"10"

storeMetadata

object

Details on offer-related metadata.

Show child attributes

Response

200 - application/json

Successfully granted award to customer.

publisherPurchaseId

string

required

Customer purchase ID.

Example:

"222673459829966773354378"

Introduction Initiate Refund

⌘I

Overview

What's New

Web Store

Checkout

Media

Events Center

Grant Award Callback

Headers

Body

Response