Fulfill purchases through the backend API

Implement your own backend that listens to purchase events and tracks your player's entitlements.

Read time 5 minutes

Last updated 16 days ago

If your game uses server-authoritative entitlements, implement a backend system that does the following:

Validate the webhook event (JWT).
Parse the event.
Update entitlements or inventory in your system based on the event type.
Mark the order as fulfilled.
Return an event response.

This ensures both your system and Unity IAP are in sync.

Important

You must mark every paid order as fulfilled, even though your backend grants the player's entitlements. The player keeps their entitlement either way, but an order that stays in the

paid

state leaves Unity IAP order tracking and analytics incomplete. In hybrid setups that mix the SDK and webhooks, unacknowledged orders can also cause order state to drift between systems.

Validate webhook events (JWT)

To enable validation, Unity IAP signs webhook requests with a JSON Web Token (JWT). Verify the following information for this token in your backend to ensure events are authentic:

Authorization header:
```
Bearer <token>
```
Signature: Signed with a private key. Fetch and cache the JWKS (public key) to verify:
```
https://services.api.unity.com/webhooks/.well-known/jwks.json
```

Issuer:

https://services.api.unity.com/webhooks/

Audience claims (array):
```
upid
```
(Unity Project Id),
```
envId
```
(Environment Id)
Token expiration: Ensure
```
exp
```
(expiration) has not passed.

There are libraries for most languages that you can use to validate JWTs.

Webhook event shape

Unity IAP normalizes events from all supported payment providers into this consistent format. Refer to the following example:


{  "id": "018d5e5e-5e5e-7e5e-5e5e-5e5e5e5e5e5e",  "version": "1.0.0",  "eventType": "order.paid",  "time": "2024-01-15T14:30:00Z",  "projectId": "018d5e5e-1111-7e5e-5e5e-111111111111",  "environmentId": "018d5e5e-2222-7e5e-5e5e-222222222222",  "dataType": "order",  "data": {    "id": "018d5e5e-3333-7e5e-5e5e-333333333333",    "playerId": "player_12345",    "paymentProvider": "stripe",    "paymentProviderResourceId": "cs_test_a1b2c3d4e5f6",    "url": "https://checkout.stripe.com/pay/cs_test_a1b2c3d4e5f6",    "lineItems": [      {        "sku": "com.game.coins_100",        "productType": "Consumable",        "price": {          "amountMicros": 4990000,          "currency": "USD"        }      }    ],    "total": {      "amountMicros": 4990000,      "currency": "USD",      "refundedAmountMicros": 0    },    "status": "paid",    "customReferenceId": "order_xyz_789",    "metadata": {      "campaign": "summer_sale",      "platform": "iOS"    },    "createdAt": "2024-01-15T14:25:00Z",    "updatedAt": "2024-01-15T14:30:00Z",    "paidAt": "2024-01-15T14:30:00Z",    "fulfilledAt": null  }}

Refer to the following fields in webhook events:

id

string

required

A unique identifier for the webhook event.

version

string

required

The version of the webhook event schema.

eventType

string

required

The type of the event. Refer to Event types for possible values.

time

string

required

The time the event was generated (ISO 8601 format).

projectId

string

required

The ID of the Unity project this order belongs to.

environmentId

string

required

The ID of the Unity environment this order occurred in.

dataType

string

required

The type of data in the event.

data

object

required

The order data object containing details about the purchase.

id

string

required

A unique identifier for the order.

playerId

string

required

The Unity authentication player ID.

paymentProvider

string

required

The payment provider that processed the order, for example,

stripe

coda

paymentProviderResourceId

string

required

The unique ID assigned to the resource by the payment provider.

url

string

required

The checkout URL for the order.

lineItems

object array

required

A list of products purchased in the order.

sku

string

required

The unique identifier for the product.

productType

string

required

The type of product, for example,

Consumable

price

object

required

The price of the product.

amountMicros

integer

required

The price in micros (1,000,000 micros equals $1.00). These values are what was shown to the user.

currency

string

required

The three-letter ISO 4217 currency code.

total

object

required

The total order amount.

amountMicros

integer

required

The total order amount in micros.

currency

string

required

The three-letter ISO 4217 currency code.

refundedAmountMicros

integer

required

The total refunded amount in micros. In partial refunds, this may be smaller than

amountMicros

status

string

required

The status of the order. Possible values:

created

paid

failed

fulfilled

revoked

customReferenceId

string

An optional custom reference ID for the order.

metadata

object

A key-value object containing any custom metadata passed during the purchase flow.

createdAt

string

required

The timestamp when the order was created (ISO 8601 format).

updatedAt

string

required

The timestamp when the order was last updated (ISO 8601 format).

paidAt

string

The timestamp when the order was paid (ISO 8601 format).

fulfilledAt

string

The timestamp when the order was fulfilled, or

null

if not yet fulfilled.

revokedAt

string

The timestamp when the order was revoked, or

null

if not revoked.

Event types

Unity IAP sends the following webhook event types:

order.paid

Unity IAP sends the

order.paid

event when a player successfully completes a purchase. When you receive this event, grant the player the entitlements or currency they purchased and mark the order as fulfilled.

order.updated

Unity IAP sends the

order.updated

event every time the order is updated. This includes changes such as the following:

The order being marked as fulfilled.
A refund being processed.
Other order modifications.

The

refundedAmountMicros

field in

data.total

reflects the current total refunded amount. Refunds are developer-initiated. For example, you might issue a refund to a player through the payment provider's dashboard. Unity IAP doesn't automatically revoke entitlements when a refund occurs. If you want to revoke entitlements on refund, you can listen for this event and handle it in your own entitlement system.

order.revoked

Unity IAP sends the

order.revoked

event when the order status changes to

revoked

. When you receive this event, revoke the player's entitlements or currency that was granted for the original purchase. Chargebacks are player-initiated. For example, a player might dispute a charge through their credit card company or bank. When a chargeback dispute closes and the player wins the dispute, Unity IAP automatically revokes the order and sends this event. Unlike refunds, Unity IAP revokes entitlements on chargebacks.

Mark orders as fulfilled via API

After granting entitlements on your backend, use the Orders API to mark the order as fulfilled. This updates the

fulfilledAt

timestamp and ensures the order status is tracked correctly.

Authentication

To call these endpoints, you need to authenticate using one of the following methods:

Service account: Create a service account in the Unity Dashboard and use it to authenticate your backend server. For more information, refer to Service account authentication.
Cloud Code: Call the endpoint from a Cloud Code script or module, which can authenticate on behalf of your project. For more information, refer to Use a Cloud Code module to fulfill purchases.

Get order

Call the

GET

endpoint to retrieve the order.


GET https://iap.services.api.unity.com/v1/projects/{projectId}/environments/{environmentId}/orders/{orderId}

Order statuses

Status	Description
`created`	Order has been created but payment has not been completed. Can transition to `paid` , `failed` , or `cancelled` .
`paid`	Payment has been received and confirmed by the payment provider. Can transition to `fulfilled` or `revoked` .
`fulfilled`	Order has been fulfilled and the player has been rewarded. Can transition to `revoked` .
`failed`	Order failed. This is a terminal state.
`revoked`	Order has been revoked. This is a terminal state.
`cancelled`	Order has been cancelled before payment. This is a terminal state.

Example response body

Both

GET

and

PATCH

endpoints return the full order object:


{  "id": "018d5e5e-3333-7e5e-5e5e-333333333333",  "projectId": "018d5e5e-1111-7e5e-5e5e-111111111111",  "environmentId": "018d5e5e-2222-7e5e-5e5e-222222222222",  "playerId": "player_12345",  "paymentProvider": "stripe",  "paymentProviderResourceId": "cs_test_12345",  "url": "https://checkout.stripe.com/pay/cs_test_12345",  "lineItems": [    {      "sku": "com.game.coins_100",      "productType": "Consumable"    }  ],  "status": "paid",  "fulfilledAt": null,  "revokedAt": null,  "customReferenceId": "order_xyz_789",  "metadata": {    "campaign": "summer_sale"  },  "createdAt": "2024-01-15T14:25:00Z",  "updatedAt": "2024-01-15T14:30:00Z"}

Update an order

Call the

PATCH

endpoint to update an order's status:


PATCH https://iap.services.api.unity.com/v1/projects/{projectId}/environments/{environmentId}/orders/{orderId}

Request body


{  "status": "fulfilled"}

status

string

required

The new status to set for the order. Allowed values:

```
fulfilled
```
: Set after granting entitlements to the player. Can only be set on
```
paid
```
orders.
```
revoked
```
: Set to revoke the player's entitlements (for example, after a refund). Can only be set on
```
paid
```
or
```
fulfilled
```
orders.
```
cancelled
```
: Set to cancel the order. Can only be set on
```
created
```
orders (before payment).

Once an order is

revoked

cancelled

, its status cannot be changed.

You can refer to the IAP Client API documentation for the HTTP response status codes.

Return an event response

You need to return an event response to indicate the success or failure of processing the event.

2xx
response: Indicates successful event processing.
Non-
2xx
response: Indicates a failure. Unity IAP will replay the event according to the replay policy.

Event replay behavior

When your webhook endpoint returns a non-

2xx

response, Unity IAP automatically retries delivery of the event. Ensure your webhook handler is idempotent so that replayed events don't result in duplicate entitlements.

Next steps

This page is part of a workflow to set up Direct-to-Consumer (D2C) payment providers with IAP. To continue this workflow, choose one of the following options:

Integrate D2C payment providersReturn to the Integrate D2C payment providers with IAP workflow page.

Test your integrationProceed to the next step in the workflow to set up your D2C payment provider.

Fulfill purchases through the backend API

Validate webhook events (JWT)

Webhook event shape

id

version

eventType

time

projectId

environmentId

dataType

data

data properties

id

playerId

paymentProvider

paymentProviderResourceId

url

lineItems

lineItems properties

sku

productType

price

price properties

amountMicros

currency

total

total properties

amountMicros

currency

refundedAmountMicros

status

customReferenceId

metadata

createdAt

updatedAt

paidAt

fulfilledAt

revokedAt

Event types

order.paid

order.updated

order.revoked

Mark orders as fulfilled via API

Authentication

Get order

Order statuses

Status

Description

Example response body

Update an order

Request body

status

Return an event response

Event replay behavior

Next steps