Grant Award Callback

Note: 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.

Warning: The playerEmail, createdByIp, and zipCode properties are deprecated. They will continue to be included in callback payloads for backward compatibility until November 27, 2026, but we recommend removing any logic that reads or stores these values as soon as possible. After this date, these properties will be removed from the payload and won’t be supported or accessible.

POST /{YOUR_GRANT_AWARD_ENDPOINT}

Grant Award - Paid Order

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": "[e-mail]",
    "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"
      }
    }
  }'

Grant Award - Paid Order

{
  "publisherPurchaseId": "222673459829966773354378"
}

Grant Award - Paid Order

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": "[e-mail]",
    "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"
      }
    }
  }'

Grant Award - Paid Order

{
  "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. Temporary identifier assigned before the orderId is credited, typically for troubleshooting failed orders.

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<int32>

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

Example:

999

priceInCents · integer<int32>

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

Example:

999

subTotal · integer<int32>

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

Example:

850

tax · integer<int32>

Tax amount in the lowest unit of the local currency.

Example:

149

taxRate · number<float>

Tax rate (percentage).

Example:

17.5

taxInDollar · integer<int32>

Tax amount in USD cents.

Example:

149

currency · string

ISO 4217 currency code.

Example:

"USD"

currencyExchangeCost · number<float>

Currency exchange cost in USD cents.

Example:

0

action · enum<string>

Customer action.

Available options: purchase, bonus

Example:

"purchase"

actionStatus · enum<string>

Action status.

Available options: completed

Example:

"completed"

originalPriceInDollar · integer<int32>

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

Example:

1499

paymentPriceInDollar · integer<int32>

Base price of the offer in USD cents.

Example:

999

paymentMethod · string

Payment method.

Example:

"card"

countryCode2 · string

Two-letter country code in ISO-3166 alpha-2 format. Required if playerIp is not provided. Example: US.

Example:

"US"

playerIp · string

Player IP address in IPv4 format. Required if countryCode2 is not provided. Example: 192.0.2.1.

priceTotalInDollar · integer<int32>

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

Example:

1148

playerEmail · string · deprecated

Deprecated. Player's email address.

Example:

"[e-mail]"

sessionMetadata · string

An object for passing data.

Example:

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

receiptId · string

Receipt ID.

Example:

"receipt_abc123"

estimatedPublisherNetAmount · number<float>

Estimated Publisher net amount in USD cents.

Example:

850.5

estimatedAppchargeFee · number<float>

Estimated Appcharge fee in USD cents.

Example:

148.5

pricePointMetadata · integer<int32>

Base price of the price point in USD cents.

Example:

999

createdByIp · string · deprecated

Deprecated. IP address in IPv4 format from which the order was made.

Example:

"192.168.1.1"

zipCode · string | null · deprecated

Deprecated. 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"

promoCodeName · string

Promo code name.

Example:

"SUMMER2024"

discount · number<float>

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

Publisher purchase ID for this transaction. Return this value after granting the award so Appcharge can confirm fulfillment and pair it with the Appcharge orderId for reconciliation. Learn more in Before you begin.

Example:

"222673459829966773354378"