Managing refunds and chargebacks from your service

Article
06/19/2024

The Clawback service allows partner services to be notified of refunds, returns, and chargeback events for their consumable products and store-managed subscriptions.
This allows partner services to implement logic helping prevent and mitigate revenue loss from fraudulent transactions and refund requests.

The following information is based on the latest version of the Clawback event service, which is the recommended approach for all services.

Risk and fraud potential with refunded consumables and store-managed subscriptions

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 certain number of automatic returns per year if certain criteria are met, such as the purchase being made within a short time of the return request. Otherwise, only in certain instances will Microsoft's Customer Support team issue refunds or returns of a digital item.

If a consumable product has not yet been fulfilled or its quantity consumed, the quantity from the returned purchase is automatically removed from the user's balance. However, if the item was fulfilled or consumed prior to the return, the user's balance will never go below 0. In this instance, the user has the in-game currency credit from when the game service consumed the item and they received their money back. This can lead to abuse and fraud related to consumables purchased, redeemed in-game, and then refunded.

Similarly, store-managed subscriptions are subject to varying regional laws that require either full or partial refunds.
Depending on the refund type, different revocation actions may be desired by the game developer or publisher.

Therefore, it is recommended that partners use the Clawback event service to detect these scenarios, manage, and protect their revenue streams for consumable products and store-managed subscriptions.

Utilizing the Microsoft.StoreServices .NET 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 is based on writing event messages to an Azure Storage Queue configured for your service's Entra application client ID.
The events are written to the queue almost instantly when a refund, return, or chargeback is processed through the Microsoft Store services.
Therefore, this allows your service to periodically query for any recent Clawback events across your entire product catalog and reconcile them within your system.

Currently the following product types are supported with the Clawback event service queue:

Product type	ProductKind value
Store-managed Consumable	`Consumable`
Developer-managed Consumable	`UnmanagedConsumable`
Store-managed Subscription	`Pass`

Required On-boarding and Setup

On-boarding for a Clawback event queue requires an Azure Storage Queue to be configured by the Microsoft Store services team. The queue's hosting cost and management will be covered by Microsoft.

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

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

Accessing your Clawback event queue

To access your Clawback event queue, your service obtains an SAS Token from purchase.mp.microsoft.com/v8.0/b2b/clawback/sastoken using a service access token generated from your service's Entra ID credentials. The SAS Token has a limited lifetime, but your service can request a new SAS Token at any time.

The returned uri parameter of the SAS Token represents the URI address to your Clawback Queue and the parameters needed to authenticate to it. However, to query and operate on your queue the URI requires additions outlined below depending on the operation you want to perform.

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:

Each entry in the Clawback queue is written as a message with the details of the Clawback event provided as a part of those messages.
To manage the messages on the queue, your service can perform these operations by adding the following parameters to the URI:

Operation	URI Addition	Additional Parameter	Description
Peek	/messages	peekonly=true	Retrieves one or more messages from the front of the queue, but does not alter the visibility of the message.
Get	/messages	none	Retrieves one or more messages from the front of the queue and sets their visibility timeout (default is 30 seconds) so they will not be returned again until after the timeout.
Delete	/messages/(message ID from queue)	popreceipt=(value from queue message)	Removes the target message from the queue permanently.

Operation	Example URI
Peek	https://uluufeofsxh2k.queue.core.windows.net/gxhxcvb32lnk4/messages?sv=2021-10-04&spr=https&st=2023-01-20T22%3A59%3A25Z&se=2023-01-21T04%3A59%3A25Z&sp=rp&sig=zJ4n%2BJdcv0nVNSh5vEwICguV54tqZ62jJwD7Omr87WE%3D&peekonly=true
Get	https://uluufeofsxh2k.queue.core.windows.net/gxhxcvb32lnk4/messages?sv=2021-10-04&spr=https&st=2023-01-20T22%3A59%3A25Z&se=2023-01-21T04%3A59%3A25Z&sp=rp&sig=zJ4n%2BJdcv0nVNSh5vEwICguV54tqZ62jJwD7Omr87WE%3D
Delete	https://uluufeofsxh2k.queue.core.windows.net/gxhxcvb32lnk4/messages/7df1da25-2c9b-4a09-9913-2e4f843ca439?sv=2021-10-04&spr=https&st=2023-01-20T22%3A59%3A25Z&se=2023-01-21T04%3A59%3A25Z&sp=rp&sig=zJ4n%2BJdcv0nVNSh5vEwICguV54tqZ62jJwD7Omr87WE%3D&popreceipt=AgAAAAMAAAAAAAAAP%2B4YHSMt2QE%3D

When you use the Get operation to retrieve messages from the queue, it places a visibility timeout (default 30 seconds) on the returned messages. This prevents messages being processed from showing up in subsequent Get operations until after the visibility timeout. The Peek operation on the other hand, does not set a visibility timeout and the messages will be visible to all follow up Peek or Get requests. However, in order to delete a message from the queue you need the popreceipt value which is only returned in messages using the Get operation.

The recommended flow for message processing is:

Get a message (or set of messages) from the queue.
Extract the Clawback event information from each message.
Check your completed transaction database for any matching transactions with the same ProductId, OrderId, and LineItemOrderId as the Clawback event.
Reconcile the items granted to the user in your system from the completed transactions.
Set the transaction in your own database as reconciled.
Delete the message from the message 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

Parameter	Type	Description	Required
`MessageId`	`GUID`	Unique ID for the message in the queue.	Yes
`InsertionTime`	`datetime`	The UTC date and time that the message was inserted into the queue.	Yes
`ExpirationTime`	`datetime`	The UTC date and time that the message will be automatically removed from the queue.	Yes
`PopReceipt`	`string`	Used in the Delete operation to remove the message from the queue.	No
`TimeNextVisible`	`datetime`	The UTC date and time that the message will be visible in the queue again.	Yes
`DequeueCount`	`int`	Number of times the message has be dequeued (pulled off the queue with the Get API).	Yes
`MessageText`	`string`	Base64 encoded string that is a JSON structure of a Clawback event	Yes

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:

Parameter	Type	Description	Required
`id`	`GUID`	Unique ID for the Clawback event.	Yes
`source`	`string`	Source service that triggered the event.	Yes
`type`	`string`	The object format of the data field. This should be ClawbackEventContractV2.	Yes
`data`	`ClawbackEventContractV2`	ClawbackEventContractV2 object that contains the data relevant to the Order affected by the Clawback event.	Yes
`time`	`datetime`	The UTC date and time that the event was created.	Yes
`specversion`	`string`	Version of the contract. Should be 1.0.	Yes
`datacontenttype`	`string`	Format of the data parameter. This should be application/json.	Yes
`subject`	`string`	Additional information used by the Clawback service for logging.	Yes
`traceparent`	`string`	Additional information used by the Clawback service for logging.	Yes

Clawback event source values

Value	Description
`/Purchase/Refund`	Event originated from a return or refund being processed through Microsoft Customer Support or the Xbox Support return request site.
`/Purchase/Chargeback`	Event originated from a chargeback or chargeback reversal by the payment institution from the order. This could be a bank, credit card, etc.

ClawbackEventContractV2 structure

Parameter	Type	Description	Required
`lineItemId`	`GUID`	Identifies the lineItem within the purchase order for the consumable (orders can have multiple lineItemIds for shopping cart scenarios).	Yes
`orderId`	`GUID`	Identifies the purchasing order the product was a part of when purchased by the user.	Yes
`productId`	`string`	Also referred to as the Store ID for the product within the Microsoft Store catalog. An example Store ID for a product is 9NBLGGH42CFD.	Yes
`productType`	`string`	Indicates the product type. For more information, see Product type values and meaning.	Yes
`purchasedDate`	`datetime`	The UTC date and time that the item was purchased.	Yes
`eventDate`	`datetime`	The UTC date and time that the item was returned or refunded.	Yes
`sandboxId`	`string`	The sandbox which the product's purchase is tied to. Production environment with end-users is 'RETAIL'.	Yes
`eventState`	`string`	The state of this specific Clawback event. See Clawback event states.	Yes
`skuId`	`string`	The specific SKU identifier if there are multiple offerings of the product in the Microsoft Store catalog. An example Store ID for a SKU is 0010.	Yes
`subscriptionData`	`ClawbackEventSubscriptionData`	The ClawbackEventSubscriptionData object returned if the order was for a subscription product. This contains data relevant to the subscription order affected by the Clawback event.	No

Clawback event states

Value	Description
`Revoked`	User's payment was given back and an attempt was made to revoke the user's entitlement but it was not successful. For consumables, this indicates the item was fulfilled by your service before the order was returned. Reconciliation with your own records and data would be required. See Reconciling consumable Clawback events
`Returned`	User's payment was given back and their entitlement was removed from their account. No reconciliation on your service is required. For consumables, this is where the purchased item has not yet been fulfilled by your service.
`Refunded`	User's payment was given back but they were allowed to retain the entitlement to the product. No reconciliation on your service is required, but you should keep track of this user account and frequent events of this type may indicate fraud behavior.
`ChargebackReversal`	This item was originally reported as either Revoked or Returned due to a Chargeback that was initiated from the payment instrument (Credit Card, Bank, etc.). Microsoft appealed the chargeback and was granted the appeal. The cost of the item was restored to Microsoft and the item's state restored to the user's account. For information on Chargebacks see Chargebacks and chargeback reversals. Additionally for specific behavior of dev-managed vs store-managed consumables see Unique behavior of dev-managed consumables during chargeback Reversal.

ClawbackEventSubscriptionData structure

Parameter	Type	Description	Required
`recurrenceId`	`string`	Unique ID to the user's subscription period and can be used with the Subscription management APIs.	Yes
`durationIntervalStart`	`datetime`	The UTC date and time that the subscription's interval tied to the purchase order started.	Yes
`durationInDays`	`int`	Number of days purchased for the subscription interval in the order.	Yes
`consumedDurationInDays`	`int`	Number of days that were used and not refunded / returned to the user.	Yes

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

Refunds vs returns

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 are 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 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 a 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 Clawback return state behavior for consumable products and Clawback return behavior for store-managed subscription products

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 based on information if we believe the purchase appears to be legitimate and quantity 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.

The timeline of a chargeback and chargeback reversal can vary. Chargebacks are usually triggered within 90 days of a purchase, but some may take up to 180 days after the purchase. If the chargeback is appealed by Microsoft, the process and final appeal outcome can take between 3 - 6 months.

Reconciling consumable Clawback events

When a Clawback event for an already fulfilled or consumed item is detected, the development team or publisher are free to determine the proper course of action on the user's account. Some possible actions are listed below, but are not limited to only these.

Remove the equivalent consumable value (usually in-game currency) from the user's remaining balance if possible
Remove the last purchased items using the consumable value within the game (if unable to remove quantity from their remaining balance)
Take no action against the user at this time, but track their account to see if this is a pattern of possible fraud or abuse of returns (ex: Large consumable qty products purchased, then returned after being consumed in-game).

It is recommended to notify the user of reconciliation actions taken, reason why, and logging this information in your services to avoid further Customer Support calls or disputes. Example: "Due to a return issued to your account through Microsoft we have removed [qty] of [product] from your account balance."

Requirements for managing Clawback events for consumable products

To properly manage and reconcile events related to store-managed and dev-managed 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 need to 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

Clawback Return state behavior for consumable products

Consumable Type	Consumed	eventStatus	Impact to the user's entitlement of the consumable	Recommended actions for developer services
`Store-managed`	No	`Return`	Qty reduced by the amount granted from the purchase. Ex: Qty = 1 before return, Qty = 0 after event.	No action, item was not consumed.
`Store-managed`	Yes	`Revoked`	Qty not reduced as the item was previously consumed / fulfilled. Ex: Qty = 0 before return, Qty = 0 after event.	Search your completed transactions database for matching OrderID, LineItemID, and ProductID. Revoke value of purchase from the user's balance tracked on game server.
`Dev-managed`	No	`Return`	Qty reduced by the amount granted from the purchase. Ex: Qty = 1 before return, Qty = 0 after event.	No action, item was not consumed.
`Dev-managed`	Yes	`Revoked`	Qty not reduced as the item was previously consumed / fulfilled. Ex: Qty = 0 before return, Qty = 0 after event.	Search your completed transactions database for matching OrderID, LineItemID, and ProductID. Revoke value of purchase from the user's balance tracked on game server.

Clawback 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.
Pro-actively 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.

Consumable Type	Consumed	eventStatus	Impact to the user's entitlement of the consumable	Recommended actions for developer services
`Store-managed`	No	`Refund`	Qty is not reduced	No revocation action, user is allowed to keep the entitlement, but log the event and any linked user information to watch for repeated patterns
`Store-managed`	Yes	`Refund`	Qty is not reduced	No revocation action, user is allowed to keep the entitlement, but log the event and any linked user information to watch for repeated patterns
`Dev-managed`	No	`Refund`	Qty is not reduced	No revocation action, user is allowed to keep the entitlement, but log the event and any linked user information to watch for repeated patterns
`Dev-managed`	Yes	`Refund`	Qty is not reduced	No revocation action, user is allowed to keep the entitlement, but log the event and any linked user information to watch for repeated patterns

Clawback chargeback behavior for consumable products

Consumable Type	Consumed	eventStatus	Impact to the user's entitlement of the consumable	Recommended actions for developer services
`Store-managed`	No	`Return`	Qty reduced by the amount granted from the purchase. Ex: Qty = 1 before return, Qty = 0 after event.	No action, item was not consumed.
`Store-managed`	Yes	`Revoked`	Qty not reduced as the item was previously consumed / fulfilled. Ex: Qty = 0 before return, Qty = 0 after event.	Search your completed transactions database for matching OrderID, LineItemID, and ProductID. Revoke value of purchase from the user's balance tracked on game server, then update tracking database entry to note it was a chargeback
`Dev-managed`	No	`Return`	Qty reduced by the amount granted from the purchase. Ex: Qty = 1 before return, Qty = 0 after event.	No action, item was not consumed.
`Dev-managed`	Yes	`Revoked`	Qty not reduced as the item was previously consumed / fulfilled. Ex: Qty = 0 before return, Qty = 0 after event.	Search your completed transactions database for matching OrderID, LineItemID, and ProductID. Revoke value of purchase from the user's balance tracked on game server, then update tracking database entry to note it was a chargeback

Clawback chargeback reversal behavior for consumable products

Consumable Type	Consumed	eventStatus	Impact to the user's entitlement of the consumable	Recommended actions for developer services
`Store-managed`	No	`ChargebackReversal`	Qty from chargeback is restored to the user's Qty because it was not consumed before the chargeback event. Ex: Qty = 0 before reversal, Qty = 1 after reversal.	Qty should be seen and consumed as normal by your normal query flow and consumed. Search your completed transactions database for matching OrderID, LineItemID, and ProductID. If a match is not round, or the record does not indicate it went through a Chargeback, do nothing.
`Store-managed`	Yes	`ChargebackReversal`	Qty from chargeback is not restored to the user's Qty because it was previously consumed before the chargeback event. Ex: Qty = 0 before reversal, Qty = 0 after reversal.	Search your completed transactions database for matching OrderID, LineItemID, and ProductID. If a match is found and it was recorded as being a Chargeback in your system, reverse the Chargeback action taken to the user's balance previously. Then update the tracking entry to note the Chargeback was reversed.
`Dev-managed`	No	`ChargebackReversal`	Qty from chargeback is restored to the user's Qty because it was not consumed before the chargeback event. But Qty will never show greater than 1, see note below.	See note below.
`Dev-managed`	Yes	`ChargebackReversal`	Qty from chargeback is restored to the user's Qty even though it was already consumed. See note below.	See note below.

Note

Dev-Managed consumables behave uniquely with chargeback reversals and require additional logic to handle these events. See below for details.

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, Dev-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 Dev-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 Dev-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'.

Clawback return behavior for store-managed subscription products

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

Clawback event behavior for store-managed subscriptions

eventStatus	Scenario	Recommended actions for developer services
Revoked	Subscription interval includes days that have already been used, the subscription entitlements have been removed from the user’s account.	Verify if return is partial or full. Take appropriate action to revoke entitlements that have not been paid for, or grant partial value based on how much of a partial payment was retained.
Return	Upcoming subscription interval that has not yet been used / started was removed from the user’s account.	No action, interval was not started.
Refund	Currently active subscription interval’s payment has been sent back to the user.	No revocation action, user is allowed to keep the entitlement, but log the event and any linked user information to watch for repeated patterns. Follow normal status and logic using the Recurrence services. See Managing subscription products from your service.
ChargebackReversal	Subscription interval from a previous Revoked state was restored to the user’s account.	Reverse any action taken when the item was reconciled as revoked. Follow normal status and logic of the subscription state as reported by the Recurrence services. See Managing subscription products from your service.

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.

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:

Verify that the test products are set with non-zero prices ($0.01 is sufficient).
Login to the development sandbox with your test account(s).
Purchase the product(s) on the test account(s).
Fulfill / consume the purchased items using the includeOrderIds: true option on the consume request.
Note the OrderIds that are returned in the consume responses.
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:

Request Type	OrderID	OrderLineItemId	Test Account (Email)	Name of item purchased	Date of Purchase	Request Summary, additional info
Return	8060a406-85c8-4d01-a105-ff11725499c9	cb054aa0-7392-4cc6-af06-53b285e39259	`XDKS-RefundTest0001@xboxtest.com`	Consumable 1	2021-08-30T21:53:08.2565331+00:00	Clawback testing of item

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

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.

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

Share via