> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appcharge.com/llms.txt
> Use this file to discover all available pages before exploring further.

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


<RequestExample>
  ```bash Grant Award - Paid Order theme={"system"}
  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"
        }
      }
    }'
  ```

  ```bash Grant Award - Free Order theme={"system"}
  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": "662345678",
      "purchaseId": "6abc123xyz789",
      "appChargePaymentId": "pay_6876543210",
      "purchaseDateAndTimeUtc": "",
      "playerId": "player_12345",
      "bundleName": "First Daily Bonus",
      "bundleId": "664044555ed01178ed2c0b36",
      "sku": "first-daily-bonus",
      "products": [
        {
          "amount": 400,
          "sku": "prod62224448763536",
          "name": "Gold Coins"
        }
      ],
      "priceInDollar": 0,
      "priceInCents": 0,
      "subTotal": 0,
      "tax": 0,
      "taxRate": 0,
      "taxInDollar": 0,
      "currency": "USD",
      "currencyExchangeCost": 0,
      "action": "bonus",
      "actionStatus": "completed",
      "originalPriceInDollar": 0,
      "paymentPriceInDollar": 0,
      "paymentMethod": "",
      "countryCode2": "US",
      "priceTotalInDollar": 0,
      "playerEmail": "john.doe@example.com",
      "sessionMetadata": "{
        "userId": "12345",
        "level":10
      }",
      "receiptId": "receipt_6abc123",
      "estimatedPublisherNetAmount": 0,
      "estimatedAppchargeFee": 148.50,
      "createdByIp": "192.168.1.1",
      "zipCode": "10001",
      "awardFlow": "auto",
      "discount": 0,
      "discountRatePoints": "0",
      "storeMetadata": {
        "productsSequenceIndex": 1,
        "offerType:" "PopUp"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Grant Award - Paid Order theme={"system"}
  {
    "publisherPurchaseId": "222673459829966773354378"
  }
  ```

  ```json Grant Award - Free Order theme={"system"}
  {
    "publisherPurchaseId": "662673459829966773354378"
  }
  ```

  ```json 400 theme={"system"}
  {
    "publisherErrorMessage": "Unable to grant the award because the player ID is invalid."
  }
  ```

  ```json 500 theme={"system"}
  {
    "publisherErrorMessage": "Unable to grant the award because the inventory service is unavailable."
  }
  ```
</ResponseExample>


## OpenAPI

````yaml openapi-grant-award.json post /{YOUR_GRANT_AWARD_ENDPOINT}
openapi: 3.1.0
info:
  title: Grant Award
  version: 1.0.0
  description: HTTP API to report player order transactions (converted from webhook).
servers: []
security: []
paths:
  /{YOUR_GRANT_AWARD_ENDPOINT}:
    post:
      tags:
        - Orders
      description: >-
        <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>
      operationId: grant-award
      parameters:
        - name: x-publisher-token
          in: header
          schema:
            type: string
          description: Publisher token.
        - name: signature
          in: header
          schema:
            type: string
          description: >-
            [Signature](/../../api-reference/appcharge-publisher-secure-communication).
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlayerOrderReportRequest'
      responses:
        '200':
          description: Successfully granted award to customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerOrderReportSuccess'
        '400':
          description: >-
            Award request failed because of a client error. The response body
            must include `publisherErrorMessage`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerOrderReportError'
              example:
                publisherErrorMessage: Unable to grant the award because the player ID is invalid.
              examples:
                '400':
                  summary: '400'
                  value:
                    publisherErrorMessage: >-
                      Unable to grant the award because the player ID is
                      invalid.
        '500':
          description: >-
            Award request failed because of a server error. The response body
            must include `publisherErrorMessage`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayerOrderReportError'
              example:
                publisherErrorMessage: >-
                  Unable to grant the award because the inventory service is
                  unavailable.
              examples:
                '500':
                  summary: '500'
                  value:
                    publisherErrorMessage: >-
                      Unable to grant the award because the inventory service is
                      unavailable.
components:
  schemas:
    PlayerOrderReportRequest:
      type: object
      properties:
        orderId:
          type: string
          description: Order ID in the Publisher Dashboard.
          example: 68e25eebdcb1278
        purchaseId:
          type: string
          description: Purchase ID.
          example: pr_750b85591e1643685718e5443xyz789
        appChargePaymentId:
          type: string
          description: Payment ID.
          example: 68e25eebd76543210
        purchaseDateAndTimeUtc:
          type: string
          format: date-time
          description: Date and time of the purchase in UTC.
          example: '2024-07-21T14:17:27.329Z'
        playerId:
          type: string
          description: Player ID returned in the player authentication process.
          example: '8533676467'
        bundleName:
          type: string
          description: Offer name.
          example: Starter Pack
        bundleId:
          type: string
          description: Offer ID.
          example: 684044555ed01178ed2c0b3b
        sku:
          type: string
          description: Offer ID you provided.
          example: starterpack
        products:
          type: array
          description: Product details.
          items:
            type: object
            properties:
              amount:
                type: integer
                description: Amount of the purchased product (minimum 0).
                example: 1000
              sku:
                type: string
                description: Product ID.
                example: prod22224448763533
              name:
                type: string
                description: Product name.
                example: Gold Coins
        priceInDollar:
          type: integer
          format: int32
          description: Price before taxes in USD cents. Converted in real time.
          example: 999
        priceInCents:
          type: integer
          format: int32
          description: Total price paid in the lowest unit of the local currency.
          example: 999
        subTotal:
          type: integer
          format: int32
          description: Price paid before taxes in the lowest unit of the local currency.
          example: 850
        tax:
          type: integer
          format: int32
          description: Tax amount in the lowest unit of the local currency.
          example: 149
        taxRate:
          type: number
          format: float
          description: Tax rate (percentage).
          example: 17.5
        taxInDollar:
          type: integer
          format: int32
          description: Tax amount in USD cents.
          example: 149
        currency:
          type: string
          description: ISO 4217 currency code.
          example: USD
        currencyExchangeCost:
          type: number
          format: float
          description: Currency exchange cost in USD cents.
          example: 0
        action:
          type: string
          enum:
            - purchase
            - bonus
          description: Customer action.
          example: purchase
        actionStatus:
          type: string
          enum:
            - completed
          description: Action status.
          example: completed
        originalPriceInDollar:
          type: integer
          format: int32
          description: >-
            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:
          type: integer
          format: int32
          description: Base price of the offer in USD cents.
          example: 999
        paymentMethod:
          type: string
          description: Payment method.
          example: card
        countryCode2:
          type: string
          description: Country code (2-letter).
          example: US
        priceTotalInDollar:
          type: integer
          format: int32
          description: Price paid including taxes. Converted in real time to USD cents.
          example: 1148
        playerEmail:
          type: string
          description: Email address.
          example: john.doe@example.com
        sessionMetadata:
          type: string
          description: An object for passing data.
          example:
            userId: '12345'
            level: 10
        receiptId:
          type: string
          description: Receipt ID.
          example: receipt_abc123
        estimatedPublisherNetAmount:
          type: number
          format: float
          description: Estimated Publisher net amount in USD cents.
          example: 850.5
        estimatedAppchargeFee:
          type: number
          format: float
          description: Estimated Appcharge fee in USD cents.
          example: 148.5
        pricePointMetadata:
          type: integer
          format: int32
          description: Base price of the price point in USD cents.
          example: 999
        createdByIp:
          type: string
          description: IP address from which the order was made.
          example: 192.168.1.1
        zipCode:
          type: string
          nullable: true
          description: Zip code (US/Canada only).
          example: '10001'
        awardFlow:
          type: string
          enum:
            - auto
            - manual_retry
          description: Award flow. Automatic or manual retry via the Publisher Dashboard.
          example: auto
        promoCodeName:
          type: string
          description: Promo code name.
          example: SUMMER2024
        discount:
          type: number
          format: float
          description: Discount amount in the currency the order was placed in.
          example: 100
        discountRatePoints:
          type: number
          description: Discount rate (percentage).
          example: '10'
        storeMetadata:
          type: object
          description: Details on offer-related metadata.
          properties:
            productsSequenceIndex:
              type: integer
              description: The index of the offer.
              example: 1
            offerType:
              type: string
              description: Offer type.
              enum:
                - PopUp
                - Bundle
                - SpecialOffer
                - RollingOffer
                - CheckoutLink
            utms:
              description: UTM data.
              type: object
              properties:
                utmSource:
                  type: string
                  description: The source of the traffic (e.g., Facebook).
                  example: Facebook
                utmMedium:
                  type: string
                  description: The marketing channel used (e.g., email).
                  example: email
                utmCampaign:
                  type: string
                  description: The marketing campaign identifier (e.g., spring_sale).
                  example: spring_sale
    PlayerOrderReportSuccess:
      type: object
      required:
        - publisherPurchaseId
      properties:
        publisherPurchaseId:
          type: string
          description: >-
            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).
          example: '222673459829966773354378'
    PlayerOrderReportError:
      type: object
      required:
        - publisherErrorMessage
      example:
        publisherErrorMessage: >-
          Unable to grant the award because the inventory service is
          unavailable.
      properties:
        publisherErrorMessage:
          type: string
          description: >-
            Explanation of why the award request failed. Required when your
            endpoint returns a `4XX` or `5XX` response.
          example: >-
            Unable to grant the award because the inventory service is
            unavailable.

````