Managing refunds and chargebacks from your service

Table of Contents

• What is the Clawback Service?
• Latest Updates October 2025
• Risk and Fraud Potential
• Microsoft.StoreServices Library
• Setup and Configuration
  • Supported Product Types
  • Queue Setup Request
  • Associating Products
  • Accessing Your Queue
• Processing Events
  • Queue Operations
  • Event Structure
  • Event Sources
• Reconciliation by Product Type
  • Consumable Products
  • Store-managed Subscriptions
  • Durable and Game Products
  • Bundle Products
• Event States and Actions
  • Refund vs Return
  • Chargebacks
• Testing
• Troubleshooting

What is the Clawback Service?

The Clawback service sends notifications to your message queue when Microsoft Store purchases are refunded, returned, or charged back by banks or credit card companies. This helps you protect your in-game economy and prevent fraud.

Why Use Clawback Events?

Without Clawback notifications, users can exploit the system by:

1. Purchasing consumable items (like in-game currency)
2. Consuming the items in your game
3. Requesting a refund from Microsoft
4. Keeping both their money and the value of the consumed items

Key Benefits

• Fraud Prevention: Detect and respond to refund abuse in real-time
• Revenue Protection: Revoke content when payments are reversed
• Real-time Notifications: Get instant alerts instead of waiting for periodic entitlement checks
• Comprehensive Coverage: Support for all product types (consumables, subscriptions, games, durables, bundles)

How It Works

1. User requests refund through Microsoft Store
2. Clawback event created and sent to your message queue
3. Your service reads the event and finds the affected purchases
4. Take corrective action by removing content or adjusting balances

This helps your service prevent and reduce revenue loss from fraudulent transactions and refund abuse.

Latest updates October 2025

• Clawback events can now be configured for all product types including Games, Durables, and Bundles. To enable these additional product types for your Clawback queue, contact your Developer Partner Manager or Microsoft contact. See Supported Clawback product types.

• When a bundle (Game bundle, Add-on bundle, or Season Pass bundle) is refunded, the Clawback service will now generate individual events for each consumable product included within that bundle. This ensures that partners receive appropriate notifications when consumed items are affected by refunds. See Clawback events for bundles.

Risk and fraud potential with refunded products

The Microsoft Store allows users the ability to request refunds or returns of digitally purchased content through their account's orders page (https://account.microsoft.com/billing/orders/). The automated system allows users the ability to receive a refund if certain criteria are met, such as the time between purchase and the refund or time spent playing the game. Otherwise, only in certain instances will Microsoft's Customer Support team issue refunds or returns of a digital item.

For consumable products (like in-game currency), if the item hasn't been used yet, the refund automatically removes it from the user's balance. However, if the item was already used before the refund, the user's balance stays the same (never goes below 0). This means the user keeps both the in-game currency they already spent and gets their money back. This can lead to abuse where players buy currency, spend it in-game, then get refunded.

Store-managed subscriptions must follow different regional laws that require either full or partial refunds. Depending on the refund type, you may want to remove different subscription benefits based on what rewards were already given to the user.

For Games and Durable products (including bundles), the license is removed from the user's account where XStore licensing APIs and Collections services will no longer show it as valid. However, your service would only notice these changes the next time it checks for user entitlements. If your service gives specific rewards or benefits to users, they might keep access to content while getting their money back until you check entitlements again.

We recommend using the Clawback event service to detect these situations and take corrective action to protect your revenue.

Utilizing the Microsoft.StoreServices library and sample

To help demonstrate the principles and flows outlined in this article review the Microsoft.StoreServices Sample which provides the following:

• Use of the Microsoft.StoreServices library to manage authentication and make the calls to the Microsoft Store Services.

• Example logic for managing consumable products, tracking pending consume requests, reconciling refunded purchases, renew expired User Store Ids, and more.

• A configuration guide that includes the steps in this article on how to configure and setup your Microsoft Entra Id for this authentication method.

• Microsoft.StoreServices (GitHub)

• Microsoft.StoreServices Sample (GitHub)

Clawback event queues

The Clawback event service uses an Azure Storage Queue set up for your service's Entra application client Id. Events are added to the queue within seconds of when a refund, return, or chargeback is processed through Microsoft Store services. This lets your service regularly check for recent Clawback events across all your products and handle them in your system.

Supported Clawback product types

As of October 2025, the Clawback event service supports refunds of all product types. Below is a table of common products configured in Partner Center for games and their associated ProductKind values that would need to be enabled on your Clawback queue.

Required setup / on-boarding request

Setting up a Clawback event queue requires the Microsoft Store services team to configure an Azure Storage Queue for you. Microsoft covers the hosting costs and management.

To have a Clawback event queue setup for you, contact your Developer Partner Manager or Microsoft contact. When requesting the queue's setup you must provide the following:

• The Entra application client Id that your service(s) will use to authenticate and that your products are associated with in Partner Center.
• The preferred geographical Azure data center of the primary queue. This is not required as the queue is accessible world-wide, but will provide better latency if close to your own service(s).
• The product types you want to receive Clawback events for. By default, consumables and store-managed subscriptions are enabled. If you want to receive events for additional product types such as durables, games, or bundles, you must specifically request them.

Once submitted, it can take 1-2 weeks for your queue setup to be deployed.

Associating your products with your Clawback queue

To receive Clawback events for your products, you must link the Entra client Id from your queue setup with your products in Partner Center. To do this, follow the same steps in Additional configuration required to view and manage products with a User Store Id / Microsoft Entra Id Auth.

Accessing your Clawback event queue

To access your Clawback event queue, your service gets an SAS Token from purchase.mp.microsoft.com/v8.0/b2b/clawback/sastoken using your service's Entra Id credentials. The SAS Token expires after a set time, but you can request a new one anytime.

The uri parameter from the SAS Token is the web address to your Clawback Queue and includes the authentication details. To perform different operations on your queue, you need to add specific parameters to this URI as shown below.

Processing Clawback messages from the queue

Using the modified uri parameter of the SAS token, your service can interact with your Clawback queue using either of the following:

• Azure Queue Storage REST APIs
• Azure Queue Storage using .NET

Each Clawback event in the queue is stored as a message containing the event details.
To work with messages in the queue, your service can perform these operations by adding the following parameters to the URI:

When you use the Get operation, it makes the messages invisible to others for 30 seconds. This prevents other services from processing the same messages while you're working on them. The Peek operation doesn't hide messages - everyone can still see them. However, to delete a message you need the popreceipt value, which you only get from the Get operation (not Peek).

Recommended steps for processing messages:

1. Get messages from the queue.
2. Read the Clawback event details from each message.
3. Find matching transactions in your database using the same productId, orderId, and lineItemId.
4. Fix the items given to the user (remove currency, revoke content, etc.).
5. Mark the transaction as processed in your database.
6. Delete the message from the queue.

The response from the Get or Peek functions will be an XML List of QueueMessage items with the following format:

<QueueMessagesList>  
    <QueueMessage>  
      <MessageId>string-message-id</MessageId>  
      <InsertionTime>insertion-time</InsertionTime>  
      <ExpirationTime>expiration-time</ExpirationTime>  
      <PopReceipt>opaque-string-receipt-data</PopReceipt>  
      <TimeNextVisible>time-next-visible</TimeNextVisible>  
      <DequeueCount>integer</DequeueCount>  
      <MessageText>message-body</MessageText>  
    </QueueMessage>  
</QueueMessagesList>  

QueueMessage structure

Clawback event structure

Each message in the queue will have an encoded JSON string in the MessageText that represents the Clawback event with the following parameters:

Clawback event source values

ClawbackEventContractV2 structure

Clawback event states

ClawbackEventSubscriptionData structure

Clawback event example

{
  "id": "5ef37bd1-8b4b-48c4-9b67-be458d8ab9de",
  "source": "/Purchase/Refund",
  "type": "ClawbackEventContractV2",
  "data": {
    "lineItemId": "230e9063-bffe-411a-8aa1-6f99ca091452",
    "orderId": "70fd35f2-7e4a-4f27-8df3-a673a5a4d9d9",
    "productId": "9N0297GK108W",
    "productType": "UnmanagedConsumable",
    "purchasedDate": "2023-01-24T21:59:19.5725585+00:00",
    "eventDate": "2023-01-26T08:18:52.246847+00:00",
    "eventState": "Revoked",
    "sandboxId": "XDKS.1",
    "skuId": "0010"
  },
  "time": "2023-01-26T08:18:56.7103057+00:00",
  "specversion": "1.0",
  "datacontenttype": "application/json",
  "subject": "/Purchase/Refund/907eb4af-57bf-4ff6-b040-e9296d169436",
  "traceparent": "00-6d2a86a53e8cae15cddaadc43f4d9670-4821cba073c416c1-00"
}

Clawback refund vs return states

When an event comes from the /Purchase/Refund source, this indicates that the event is tied to either a customer refund or return request. These two terms are sometimes used synonymously, but in the context of the Microsoft Store services they each have unique behavior that should be handled by your service.

In both cases the user will receive their payment back from the order, but they differ in what happens to the entitlement or quantity granted from the purchase. A return operation will attempt to remove the entitlement or quantity from the user's account. Refunds however result in the user's account retaining the entitlement or quantity from the purchase.

Requests to Microsoft Customer Support or through the automated tools are generally treated as return requests. However, in rare cases, as a 'make-good' gesture based on the circumstances related to the customer's issue, the state of the event may be Refund in an effort to provide positive customer service. The Refund state may also be used as a pro-active refund issued to the customer if there is an indication the purchase will be reported as a chargeback to avoid the chargeback processing fees.

Your service should check the eventState value and follow the recommendations for reconciliation of each value outlined in Clawback event states. For example scenarios see Return and Revoked state behavior for consumable products and Clawback event behavior for Store-managed subscriptions.

Chargebacks and chargeback reversals

When an event comes from the /Purchase/Chargeback source, this indicates that the payment institution reversed the charge of the order and has taken payment back. A common cause of a chargeback is a dispute or fraudulent charge to the payment instrument. When the chargeback event happens, the Clawback service will report the event with either a Revoked or Returned state based on the attempt to remove the entitlement or quantity from the user's account. At the time of the event, your service should treat chargeback events with the same reconciliation actions as events from /Purchase/Refund.

Microsoft will commonly appeal the chargeback if we believe the purchase appears to be legitimate and the quantity was used. If the appeal is granted, payment is sent back to Microsoft and a ChargebackReversal event will be logged in your Clawback queue. This event will have the same OrderIDs as the initial chargeback event.

When a ChargebackReversal happens, the item that was purchased is restored to the user's account. Therefore, any action taken on your server to revoke or remove the purchased item should be reversed as the payment has now been restored.

Reconciling Consumable Clawback events

When a Clawback event shows that an item was already used by the player, you can choose what action to take on their account. Some possible actions include:

• Remove the same amount of currency from the user's current balance (if they have enough)
• Remove the most recent items they bought with that currency (if they don't have enough currency left)
• Don't take action right now, but watch their account for patterns of fraud or abuse (example: buying large amounts of currency, using it, then getting refunds repeatedly)

We recommend telling the user what action you took and why, and logging this information to avoid customer support issues. Example: "Due to a return issued to your account through Microsoft we have removed [qty] of [product] from your account balance."

Requirements to manage consumable Clawback events

To properly handle Clawback events for consumables, your service must track each consume transaction and use the includeOrderIds parameter as TRUE. This parameter returns the Ids related to the purchase orders and quantity used to fulfill the consume request.

These same OrderIds are provided in the Clawback events which can then be used to search for and identify exactly which consume transaction and user in your own database should be reconciled based on the data in the event.

For more information on recommendations and flow to track consume transactions on your service, see Managing consumable products from your service

Create a consume tracking database

Your tracking database should store these values for each transaction so you can find and update them when Clawback events arrive.

Set up your tracking database early, even before you start using the Clawback event queue. This gives you a history of transactions that might get refunded or charged back later. It also lets you compare data from before and after you start handling Clawback events to see the impact.

Return and Revoked state behavior for consumable products

Refund state behavior for consumable products

A Refund event state is a special case where the user is given their payment back, but also allowed to keep the entitlement to the item. There are two main scenarios that would lead to this event state:

• Refund issued by customer service as a 'make good' effort to a user for their inconvenience or issue that lead to the refund.
• Proactively issued refund when there is a high probability the purchase will be reported as a chargeback. This prevents the added fees and resource cost of processing a likely chargeback event.

Therefore, the correct action when you see a Refund event state is to record the event with the linked account information on your service. Then watch for patterns or repeated Refund event states on a single account indicating possible fraud or abuse on that account.

Chargeback behavior for consumable products

Chargeback reversal behavior for consumable products

Unique behavior of dev-managed consumables during chargeback reversal

Regardless if the dev-managed consumable was consumed or not before the chargeback event, if there is a chargeback reversal the consumable quantity from the purchase will be added back to the user's account balance. However, Developer-managed consumables will never report a quantity greater than 1 even if there are multiple valid entitlements to the dev-managed consumable. This is because Developer-managed consumables are intended to block users from purchasing the consumable again until it has been reported as consumed/fulfilled by the game service. In the case of a chargeback reversal when there is already a non-zero balance on the user's account, the multiple entitlements are still valid and can be individually consumed as normal. Just note that the user's balance will remain as '1' after each consume request until all of the active entitlements have been consumed / fulfilled. Therefore, your system should go through the consume flow as normal until the user's balance for the Developer-managed consumable reports as '0'.

When consuming, if you see a record matching the same OrderID, LineItemID, and ProductID, check if it is marked as going through a chargeback reconciliation. If it was marked as reconciled from a chargeback, reverse the action taken on the user's account balance and mark the item as a chargeback reversal.

Example: Qty = 1 before reversal, Qty = 1 after reversal but there are actually 2 active entitlements. Service consumes 1 of the consumable, user's quantity will still be '1' after the consume. Service consumes 1 more of the consume, user's quantity now reports as '0'.

Bundle refund considerations for consumables

When consumables are included in a refunded bundle, you will receive separate Clawback events for:

1. The bundle itself - This event represents the bundle product that was refunded
2. Each consumable included in the bundle - Individual events for each consumable product that was granted as part of the bundle

When reconciling bundle-related consumable refunds:

• Track bundle relationships: Consider maintaining records of which consumables were granted as part of bundle purchases vs individual purchases
• Coordinate reconciliation: Ensure that both the bundle refund and individual consumable refunds are properly handled without double-processing
• User communication: When notifying users about revoked content, consider mentioning that the action is related to a bundle refund to provide better context

The OrderIDs for consumable events from bundle refunds will match the bundle's original purchase OrderID, allowing you to correlate these events together.

Reconciling Store-managed subscription Clawback events

When a Clawback event for a store-managed subscription is detected, additional information related to the subscription is added to the Clawback event through the ClawbackEventSubscriptionData structure. Specifically, if the user was issued a full or partial amount of their payment for the corresponding subscription interval. If your subscription grants monthly in-game rewards or currency to the user’s account, you may want to revoke those rewards depending on how many days payment was returned vs retained.

[NOTE!] The development team and publisher are free to determine the proper course of action on a user’s account when a store-managed subscription Clawback event is received. If action is taken to revoke any items or benefits, it is recommended to notify the user of the reconciliation actions taken, reason why, and logging the information in your service to avoid further Customer Support calls or disputes. Example: “Due to a return issued to your account through Microsoft we have adjusted your [subscription product] benefits.”

Requirements for managing Clawback events for Store-managed subscription

For subscription products, the OrderID associated with the clawback event may change with each renewal transaction of the subscription. Additionally, the LineItemIds for subscriptions are not exposed in the Collections or Recurrence APIs. Therefore, the best way to track and identify the subscription from the Recurrence APIs to related clawback events is through the RecurrenceID value. We recommend using this as the lookup / unique Id for the subscription that you are associating with the user in your tracking database.

Clawback event behavior for Store-managed subscriptions

Example ClawbackEventSubscriptionData for full and partial returns

Scenario: Monthly subscription, user was issued a pro-rated (partial) return on Jul 6, 2023. User was given back the price of 25 unused days, Microsoft retained the remaining price for 6 days that were used.

    "subscriptionData": {
      "recurrenceId": "mdr:0:ae5cad80acf2428fa64c38529996a3fd:df3763c2-36f8-4bde-8fa5-a29fb6058d62",
      "durationIntervalStart": "2023-07-01T00:00:00+00:00",
      "durationInDays": 31,
      "consumedDurationInDays": 6,
      "refundType": "Partial"
    }

Scenario: Monthly subscription, user was issued a full return on Jul 6, 2023. User was given back the full price paid for the month subscription, Microsoft did not retain any payment.

    "subscriptionData": {
      "recurrenceId": "mdr:0:0dc7194514404dd3bf0f678e21716774:23a454d5-f240-4dad-9923-9c3f53f515cc",
      "durationIntervalStart": "2023-07-01T00:00:00+00:00",
      "durationInDays": 31,
      "consumedDurationInDays": 6,
      "refundType": "Full"
    }

Scenario: Yearly subscription, user was issued a pro-rated (partial) return on Jan 15, 2024. User was given back the price of 199 unused days, Microsoft retained the remaining price for 168 days that were used.

    "subscriptionData": {
      "recurrenceId": "mdr:0:9ed0a48236404b78a017e9e226da94c6:22aa4f3c-1ffc-4dd3-8801-cb2a227a5c46",
      "durationIntervalStart": "2023-07-31T00:00:00+00:00",
      "durationInDays": 367,
      "consumedDurationInDays": 168,
      "refundType": "Partial"
    }

[NOTE!] The above example’s yearly subscription durationInDays is 367 rather than 365. One day is added due to 2024 being a leap-year, the other is added to move the user’s renewal date to the 1st of the next month in order to avoid issues with some months not having a 29th, 30th, or 31st. For more information see Understanding subscription start, renew, and expire dates.

In the latter example, payment for the time prior to the Clawback event was retained. If the subscription granted monthly rewards or in-game items, the recommendation is to ensure the user keeps the items granted to them for that time period.

Reconciling Durable and Game product Clawback events

When a Clawback event is received for a durable or game product (including bundles), your reconciliation approach may be different than a consumable. If your client is using the appropriate XStore licensing APIs the client should act appropriately as the user no longer has a valid license. However, in some cases your title or services may be granting tracked rewards or benefits added to their account from the durable purchase. In this case, it would be similar to a consumable where the granted reward tracked in your service would need to be revoked from the user's account.

OrderIds and LineItemIds for Durable and Game products

When a Game or Durable product is purchased, it will generate an OrderId and LineItemId as any other product purchase. However, these product types' LineItemIds are not exposed within the existing Collections service query APIs. If your service will be tracking the ownership of and matching Clawback events for a Game or Durable, use the OrderID combined with the ProductID of the Game or Durable as a unique identifier.

Clawback event states for Durable and Game products

It is recommended to notify users of any reconciliation actions taken, provide clear reasons, and log all actions in your service to help resolve potential Customer Support inquiries.

Clawback events for bundles

When a bundle is refunded, the following Clawback events will be generated and written to the Clawback queue(s) associated with the bundle product itself. If the included products in the bundle are associated with different Entra client Ids, these events will not be written to those queues. Therefore, ensure your bundle product is linked to the Entra client Id(s) of the queue(s) you expect to receive these events in.

• Bundle: The bundle itself will generate a Clawback event based on its product type (Game bundle or Durable bundle) and if the partner's Clawback queue is configured for the associated product type(s)
• All included consumables: Each consumable product included in the bundle will generate separate Clawback events
• Other included products: Durable and Game products included in bundles may also generate events if those product types are enabled for your Clawback queue, depending on how they were configured within the bundle at the time of purchase

Required configuration for bundle events

To receive Clawback events for a bundle and its included products, you must ensure your Entra client Id(s) are properly associated with the bundle product in Partner Center:

Add-on & Season Pass Bundles:

1. Navigate to the Product collections and purchases page of the base Game that the bundle is configured under
2. Ensure the correct Entra client Ids are associated with the bundle
3. Save and republish the product to your sandbox(es) and RETAIL

Game Bundles:

1. Navigate to the Product collections and purchases page for the Game bundle product
2. Ensure the correct Entra client Ids are associated with the bundle
3. Save and republish the product to your sandbox(es) and RETAIL

OrderIds and LineItemIds for bundles and their included products

When a bundle is purchased, it will generate an OrderID and LineItemId as any other product purchase does. These same values are then inherited by all included products granted within the bundle. Therefore, for consumables within a bundle, they will all share the same OrderID and LineItemId, and those values will be reflected in both the consume API results and the Clawback events for those included consumables.

Similar to Durables and Games, the bundle's LineItemId is not exposed within the existing Collections service query APIs. If your service will be tracking the ownership of and matching Clawback events for the bundle, use the OrderID combined with the ProductID of the bundle as a unique identifier.

Testing product returns within your development sandbox

Development accounts for sandboxes do not have access to the automated product return request tool on support.xbox.com. Therefore, to test the return scenarios and your Clawback implementation you will need to request a return for test purchases with the help of your Microsoft Developer Account manager or Microsoft contact by doing the following:

1. Verify that the test products are set with non-zero prices ($0.01 is sufficient).
2. Login to the development sandbox with your test account(s).
3. Purchase the product(s) on the test account(s).
4. For consumable products: Fulfill / consume the purchased items using the includeOrderIds: true option on the consume request. For other product types: Ensure the products have been granted to the user's account.
5. Note the OrderIDs from the purchase (available through the query API as the TransactionID, or consume responses for consumables).
6. Send an email to your Microsoft Developer Partner Manager or Microsoft contact to request a product return for the product(s). The email must include the following information in the following template example:

NOTE: Make sure your request is listed as a 'return' and not a 'refund'. The tools used for 'refunds' will refund the payment but keep the entitlement on the user's account. A 'return' in the tools will cause the entitlement to be revoked and cause Clawback event messages to be written to the queue.

NOTE: When testing bundle refunds, you will receive multiple Clawback events - one for the bundle itself and additional events for any consumables (and possibly other products) included in the bundle. Ensure your Entra client Id is properly associated with the bundle product in Partner Center and that the bundle has been republished for the included product events to be generated.

A representative from the Xbox support team will reply to confirm the request has been processed within 3 business days. You should then be able to see the correct Clawback information in your queries. If authorized by your Developer Partner Manager, they may provide you the Xbox Support team's email address for making future requests directly. Do not share this alias broadly within your organization and please remember to CC your Developer Partner Manager on any future direct requests.

NOTE: Returns and refunds will only cause Clawback events with non-zero priced products. Therefore, your products need to have a price of at least $0.01. This is now enabled as all newly created test accounts will have a test payment instrument added to them where they can make test purchases within a sandbox. If you are using an older account that does not have a test payment instrument, create a new account to be able to do this flow.

Troubleshooting Common Issues

Queue Access Problems

• Symptom: Cannot access queue with SAS token
• Solutions:
  • Verify Entra client ID is correctly associated with products in Partner Center
  • Check SAS token hasn't expired (request new one)
  • Ensure correct Azure Storage Queue URI format

Missing Clawback Events

• Symptom: Expected events not appearing in queue
• Solutions:
  • Confirm product type is enabled for your queue (contact Developer Partner Manager)
  • Verify products are republished after Entra client Id association
  • Check that test products have non-zero prices ($0.01 minimum)

Duplicate Event Processing

• Symptom: Same event processed multiple times
• Solutions:
  • Implement idempotency using id field from Clawback event
  • Track processed message Ids to prevent reprocessing
  • Use proper Get/Delete workflow (not just Peek)

Reconciliation Issues

• Symptom: Cannot match events to transactions
• Solutions:
  • Ensure consume tracking database includes OrderID, LineItemID, ProductID
  • Verify includeOrderIds: true is used in consume requests
  • For subscriptions, use RecurrenceID instead of OrderId for matching

Bundle Event Confusion

• Symptom: Unexpected number of events for bundle refunds
• Solutions:
  • Expect multiple events: one for bundle + one per included consumable
  • Check that bundle product has correct Entra client Id association
  • Verify bundle was republished after configuration changes

See also

Commerce Overview

Consumable-based ecosystems

Managing consumable products from your service

Microsoft Store Service APIs

Microsoft.StoreServices library (GitHub)

Microsoft.StoreServices Sample (GitHub)