---
title: "POST /{YOUR_GRANT_AWARD_ENDPOINT}"
method: POST
path: "/{YOUR_GRANT_AWARD_ENDPOINT}"
tags: ["Orders"]
---

# POST /{YOUR_GRANT_AWARD_ENDPOINT}

`POST /{YOUR_GRANT_AWARD_ENDPOINT}`

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

 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. </Warning>

## Headers

- `x-publisher-token` string
- `signature` string

## Request body

- PlayerOrderReportRequest
  - `orderId` string — Order ID in the Publisher Dashboard.
  - `purchaseId` string — Purchase ID. Temporary identifier assigned before the `orderId` is credited, typically for troubleshooting failed orders.
  - `appChargePaymentId` string — Payment ID.
  - `purchaseDateAndTimeUtc` string, date-time — Date and time of the purchase in UTC.
  - `playerId` string — Player ID returned in the player authentication process.
  - `bundleName` string — Offer name.
  - `bundleId` string — Offer ID.
  - `sku` string — Offer ID you provided.
  - `products` object[] — Product details.
    - `amount` integer — Amount of the purchased product (minimum 0).
    - `sku` string — Product ID.
    - `name` string — Product name.
  - `priceInDollar` integer — Price before taxes in USD cents. Converted in real time.
  - `priceInCents` integer — Total price paid in the lowest unit of the local currency.
  - `subTotal` integer — Price paid before taxes in the lowest unit of the local currency.
  - `tax` integer — Tax amount in the lowest unit of the local currency.
  - `taxRate` number, float — Tax rate (percentage).
  - `taxInDollar` integer — Tax amount in USD cents.
  - `currency` string — ISO 4217 currency code.
  - `currencyExchangeCost` number, float — Currency exchange cost in USD cents.
  - `action` 'purchase' | 'bonus' — Customer action.
  - `actionStatus` 'completed' — Action status.
  - `originalPriceInDollar` integer — 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.
  - `paymentPriceInDollar` integer — Base price of the offer in USD cents.
  - `paymentMethod` string — Payment method.
  - `countryCode2` string — Two-letter country code in [ISO-3166 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. Required if `playerIp` is not provided. Example: `US`.
  - `playerIp` string — Player IP address in [IPv4](https://en.wikipedia.org/wiki/IPv4) format. Required if `countryCode2` is not provided. Example: `192.0.2.1`.
  - `priceTotalInDollar` integer — Price paid including taxes. Converted in real time to USD cents.
  - `playerEmail` string — Email address.
  - `sessionMetadata` string — An object for passing data.
  - `receiptId` string — Receipt ID.
  - `estimatedPublisherNetAmount` number, float — Estimated Publisher net amount in USD cents.
  - `estimatedAppchargeFee` number, float — Estimated Appcharge fee in USD cents.
  - `pricePointMetadata` integer — Base price of the price point in USD cents.
  - `createdByIp` string — IP address from which the order was made.
  - `zipCode` string, nullable — Zip code (US/Canada only).
  - `awardFlow` 'auto' | 'manual_retry' — Award flow. Automatic or manual retry via the Publisher Dashboard.
  - `promoCodeName` string — Promo code name.
  - `discount` number, float — Discount amount in the currency the order was placed in.
  - `discountRatePoints` number — Discount rate (percentage).
  - `storeMetadata` object — Details on offer-related metadata.
    - `productsSequenceIndex` integer — The index of the offer.
    - `offerType` 'PopUp' | 'Bundle' | 'SpecialOffer' | 'RollingOffer' | 'CheckoutLink' — Offer type.
    - `utms` object — UTM data.
      - `utmSource` string — The source of the traffic (e.g., Facebook).
      - `utmMedium` string — The marketing channel used (e.g., email).
      - `utmCampaign` string — The marketing campaign identifier (e.g., spring_sale).

## Response `200`

Successfully granted award to customer.

- PlayerOrderReportSuccess
  - `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](/../../api-reference/checkout/awards/introduction#before-you-begin).

## Other responses

- `400` — Award request failed because of a client error. The response body must include `publisherErrorMessage`.
- `500` — Award request failed because of a server error. The response body must include `publisherErrorMessage`.

---

[API](https://skmtc.net/appcharge/apis/grant-award.md) · [All operations](https://skmtc.net/appcharge/apis/grant-award/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/appcharge/grant-award/revisions/b4f6759240d5/schema)