Freigeben über


Player Item Management - Start Purchase

NOTE: This is a Legacy Economy API, and is in bugfix-only mode. All new Economy features are being developed only for version 2. 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

ItemPurchaseRequest[]

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

StartPurchaseResult

400 Bad Request

ApiErrorWrapper

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

Name Description
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

ItemPurchaseRequest[]

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

CartItem[]

Cart items to be purchased.

OrderId

string

Purchase order identifier.

PaymentOptions

PaymentOption[]

Available methods by which the user can pay.

VirtualCurrencyBalances

object

Current virtual currency totals for the user.

Error Codes

Name Code
StoreNotFound 1221