Player Item Management - Start Purchase

Creates an order for a list of items from the title catalog

POST https://titleId.playfabapi.com/Client/StartPurchase

Request Header

Name Required Type Description
X-Authorization True
  • string

This API requires a client session ticket, available from any Client Login function.

Request Body

Name Required Type Description
Items True

Array of items to purchase.

CatalogVersion
  • string

Catalog version for the items to be purchased. Defaults to most recent catalog.

CustomTags
  • object

The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).

StoreId
  • string

Store through which to purchase items. If not set, prices will be pulled from the catalog itself.

Responses

Name Type Description
200 OK
400 Bad Request

This is the outer wrapper for all responses with errors

Security

X-Authorization

This API requires a client session ticket, available from any Client Login function.

Type: apiKey
In: header

Definitions

ApiErrorWrapper

The basic wrapper around every failed API response

CartItem
ItemPurchaseRequest
PaymentOption
StartPurchaseRequest

This is the first step in the purchasing process. For security purposes, once the order (or "cart") has been created, additional inventory objects may no longer be added. In addition, inventory objects will be locked to the current prices, regardless of any subsequent changes at the catalog level which may occur during the next two steps.

StartPurchaseResult

ApiErrorWrapper

The basic wrapper around every failed API response

Name Type Description
code
  • integer

Numerical HTTP code

error
  • string

Playfab error code

errorCode
  • integer

Numerical PlayFab error code

errorDetails
  • object

Detailed description of individual issues with the request object

errorMessage
  • string

Description for the PlayFab errorCode

status
  • string

String HTTP code

CartItem

Name Type Description
Description
  • string

Description of the catalog item.

DisplayName
  • string

Display name for the catalog item.

ItemClass
  • string

Class name to which catalog item belongs.

ItemId
  • string

Unique identifier for the catalog item.

ItemInstanceId
  • string

Unique instance identifier for this catalog item.

RealCurrencyPrices
  • object

Cost of the catalog item for each applicable real world currency.

VCAmount
  • object

Amount of each applicable virtual currency which will be received as a result of purchasing this catalog item.

VirtualCurrencyPrices
  • object

Cost of the catalog item for each applicable virtual currency.

ItemPurchaseRequest

Name Type Description
Annotation
  • string

Title-specific text concerning this purchase.

ItemId
  • string

Unique ItemId of the item to purchase.

Quantity
  • number

How many of this item to purchase. Min 1, maximum 25.

UpgradeFromItems
  • string[]

Items to be upgraded as a result of this purchase (upgraded items are hidden, as they are "replaced" by the new items).

PaymentOption

Name Type Description
Currency
  • string

Specific currency to use to fund the purchase.

Price
  • number

Amount of the specified currency needed for the purchase.

ProviderName
  • string

Name of the purchase provider for this option.

StoreCredit
  • number

Amount of existing credit the user has with the provider.

StartPurchaseRequest

This is the first step in the purchasing process. For security purposes, once the order (or "cart") has been created, additional inventory objects may no longer be added. In addition, inventory objects will be locked to the current prices, regardless of any subsequent changes at the catalog level which may occur during the next two steps.

Name Type Description
CatalogVersion
  • string

Catalog version for the items to be purchased. Defaults to most recent catalog.

CustomTags
  • object

The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).

Items

Array of items to purchase.

StoreId
  • string

Store through which to purchase items. If not set, prices will be pulled from the catalog itself.

StartPurchaseResult

Name Type Description
Contents

Cart items to be purchased.

OrderId
  • string

Purchase order identifier.

PaymentOptions

Available methods by which the user can pay.

VirtualCurrencyBalances
  • object

Current virtual currency totals for the user.

Error Codes

Name Code
StoreNotFound 1221