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

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

Country code (2-letter).

Example:

"US"

priceTotalInDollar

integer<int32>

Price paid including taxes. Converted in real time to USD 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<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

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

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"

Introduction Introduction

⌘I