Edit

Share via

Economy v2 Subscriptions

  • Article

Subscriptions allow you to grant time based access to durable goods. Items within a subscription are unpacked in a player's inventory after calling GetInventoryItems.

Note

This article focuses on virtual subscriptions, or the subscriptions that live inside of your game. We have a new feature in Private Preview where you can link virtual subscriptions to real-world marketplaces using PlayFab's Inventory Redeem APIs. Here is where you can find more information about how to do this:

To access this feature, send an email to PFEconomyPreviews@microsoft.com with the subject PlayFab Mobile Subscriptions along with your PlayFab Title ID and we will enable the feature in your environment.

Creating a Subscription

To create a subscription, you must first make sure you have published Catalog Items, Currency, or User Generated Content (UGC) that you want to be accessible/purchaseable in your game. To set up your catalog before creating a subscription, see Economy V2 Quickstart

  1. Navigate to Economy > Catalog (V2).

  2. Under the Subscriptions tab, select New Subscription.

The above Holiday Skins Pass subscription grants two items, Glowing Gloves and Shiny Shoes at two price points for two different validity periods. The first price set of 5 diamonds and 10 gold ensures that the subscription is valid for one week while the second price set of 7 diamonds and 12 gold ensures that the subscription is valid for one month. Do note time duration needs to be set in seconds.

This should return a response that the subscription has been created and published:

{
  "code": 200,
    "status": "OK",
    "data": {
        "Item": {
            "Id": "{{NewlyCreatedSubscriptionItemID}}",
            "Type": "subscription",
            "AlternateIds": [],
            "Title": {
                "NEUTRAL": "Holiday Skins Pass"
            },
    ...
}

Subscriptions within Inventory

Subscriptions will be present in the player's inventory collection with an ID, StackId, expiration date, and display properties. Everything in a subscription can be modified just like any other item using Add, Subtract, and Update, etc.

You can use the GetInventoryItems with a Type filter to retrieve all subscriptions a player currently has.

{ 
    "Entity": {
        "Type": "title_player_account", 
        "Id": "ID" 
    }, 
    "CollectionId": "default", 
    "Filter": "type eq 'subscription'"
}

**Sample Response**

{
    "code": 200,
    "status": "OK",
    "data": {
        "Items": [
            {
                "Id": "{{SubscriptionID}}",
                "StackId": "default",
                "DisplayProperties": {},
                "Type": "subscription",
                "ExpirationDate": "2023-08-27T23:59:59Z"
            }
        ],
        "ETag": "1/Mw=="
    }
}

An unexpired subscription is unpacked at read time. The unpacked items have the expected ID, a unique compound StackId composed of the Subscription ID and the subscription's StackId. The amount is set to the amount configured in the subscription item reference. These unpacked items are immutable and can't be modified using Add, Subtract, Update, etc.


{ 
    "Entity": {
        "Type": "title_player_account", 
        "Id": "ID" 
    }, 
    "CollectionId": "default", 
    "Filter": "StackId eq 'SubscriptionItemID:default'"
}

**Sample Response**

{
    "code": 200,
    "status": "OK",
    "data": {
        "Items": [
            {
                "Id": "{{GlowingGlovesItemID}}",
                "StackId": "{{SubscriptionID:default}}",
                "DisplayProperties": {},
                "Amount": 1,
                "Type": "catalogItem"
            },
            {
                "Id": "{{ShinyShoesItemID}}",
                "StackId": "{{SubscriptionID:default}}",
                "DisplayProperties": {},
                "Amount": 1,
                "Type": "catalogItem"
            }
        ],
        "ETag": "1/NQ=="
    }
}

Subscription unpacking occurs before filtering and paging such that subscription items can be reliably filtered and paged just like any other items in a collection.

You can use UpdateInventoryItems, AddInventoryItems, and SubtractIventoryItems to update the expiration date of a Subscription for a player.

UpdateInventoryItems API call here's updating the Subscription's expiration date.

{
   "Entity": { 
      "Type": "title_player_account", 
      "Id": "{{ID}}" 
    }, 
  "CollectionId": "default", 
   "Item": { 
        "Id": "{{SubscriptionID}}", 
        "StackId": "default",
        "DisplayProperties": {},
        "Type": "subscription",
        "ExpirationDate": "2023-03-27T23:59:59Z" 
    } 
}

AddInventoryItems API call here's extending the expiration date by increasing the DurationInSeconds parameter.

{
    "Entity": { 
        "Type": "title_player_account", 
        "Id": "{{ID}}" 
    }, 
    "CollectionId": "default", 
    "Item": { 
        "Id": "{{SubscriptionID}}" 
    }, 
    "DurationInSeconds":2628000 
}

SubtractInventoryItems API call here's decreasing the expiration date by reducing the DurationInSeconds parameter.

{
    "Entity": { 
        "Type": "title_player_account", 
        "Id": "{{ID}}" 
    }, 
    "CollectionId": "default", 
    "Item": { 
        "Id": "{{SubscriptionID}}" 
    }, 
    "DurationInSeconds":60 
}