Sign in

v1

latestOpenAPI 3.1.02026-07-2665153355.3 KB
Orders

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

post/{YOUR_GRANT_AWARD_ENDPOINT}

Headers

x-publisher-tokenstring

Publisher token.

signaturestring

Signature.

Request body

orderIdstring

Order ID in the Publisher Dashboard.

purchaseIdstring

Purchase ID. Temporary identifier assigned before the orderId is credited, typically for troubleshooting failed orders.

appChargePaymentIdstring

Payment ID.

purchaseDateAndTimeUtcstring date-time

Date and time of the purchase in UTC.

playerIdstring

Player ID returned in the player authentication process.

bundleNamestring

Offer name.

bundleIdstring

Offer ID.

skustring

Offer ID you provided.

priceInDollarinteger

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

priceInCentsinteger

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

subTotalinteger

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

taxinteger

Tax amount in the lowest unit of the local currency.

taxRatenumber float

Tax rate (percentage).

taxInDollarinteger

Tax amount in USD cents.

currencystring

ISO 4217 currency code.

currencyExchangeCostnumber float

Currency exchange cost in USD cents.

action'purchase' | 'bonus'

Customer action.

actionStatus'completed'

Action status.

originalPriceInDollarinteger

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.

paymentPriceInDollarinteger

Base price of the offer in USD cents.

paymentMethodstring

Payment method.

countryCode2string

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

playerIpstring

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

priceTotalInDollarinteger

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

playerEmailstring

Email address.

sessionMetadatastring

An object for passing data.

receiptIdstring

Receipt ID.

estimatedPublisherNetAmountnumber float

Estimated Publisher net amount in USD cents.

estimatedAppchargeFeenumber float

Estimated Appcharge fee in USD cents.

pricePointMetadatainteger

Base price of the price point in USD cents.

createdByIpstring

IP address from which the order was made.

zipCodestring nullable

Zip code (US/Canada only).

awardFlow'auto' | 'manual_retry'

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

promoCodeNamestring

Promo code name.

discountnumber float

Discount amount in the currency the order was placed in.

discountRatePointsnumber

Discount rate (percentage).

Example request

{
  "orderId": "68e25eebdcb1278",
  "purchaseId": "pr_750b85591e1643685718e5443xyz789",
  "appChargePaymentId": "68e25eebd76543210",
  "purchaseDateAndTimeUtc": "2024-07-21T14:17:27.329Z",
  "playerId": "8533676467",
  "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",
  "action": "purchase",
  "actionStatus": "completed",
  "originalPriceInDollar": 1499,
  "paymentPriceInDollar": 999,
  "paymentMethod": "card",
  "countryCode2": "US",
  "priceTotalInDollar": 1148,
  "playerEmail": "john.doe@example.com",
  "receiptId": "receipt_abc123",
  "estimatedPublisherNetAmount": 850.5,
  "estimatedAppchargeFee": 148.5,
  "pricePointMetadata": 999,
  "createdByIp": "192.168.1.1",
  "zipCode": "10001",
  "awardFlow": "auto",
  "promoCodeName": "SUMMER2024",
  "discount": 100,
  "storeMetadata": {
    "productsSequenceIndex": 1,
    "utms": {
      "utmSource": "Facebook",
      "utmMedium": "email",
      "utmCampaign": "spring_sale"
    }
  }
}

Response

Successfully granted award to customer.

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

{
  "publisherPurchaseId": "222673459829966773354378"
}
All 65 operations