开始购买

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

Error codes

This operation may return the following PlayFab errors:

Error	Code
ProductDisabledForTitle	1609
StoreNotFound	1221

POST

Client

StartPurchase

Start Purchase

curl --request POST \
  --url https://{titleId}.playfabapi.com/Client/StartPurchase \
  --header 'Content-Type: application/json' \
  --header 'X-Authorization: <api-key>' \
  --data '
{
  "CatalogVersion": "0",
  "StoreId": "BonusStore",
  "Items": [
    {
      "ItemId": "something",
      "Quantity": 1,
      "Annotation": "totally buying something"
    }
  ]
}
'

import requests

url = "https://{titleId}.playfabapi.com/Client/StartPurchase"

payload = {
    "CatalogVersion": "0",
    "StoreId": "BonusStore",
    "Items": [
        {
            "ItemId": "something",
            "Quantity": 1,
            "Annotation": "totally buying something"
        }
    ]
}
headers = {
    "X-Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Authorization': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    CatalogVersion: '0',
    StoreId: 'BonusStore',
    Items: [{ItemId: 'something', Quantity: 1, Annotation: 'totally buying something'}]
  })
};

fetch('https://{titleId}.playfabapi.com/Client/StartPurchase', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{titleId}.playfabapi.com/Client/StartPurchase",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'CatalogVersion' => '0',
    'StoreId' => 'BonusStore',
    'Items' => [
        [
                'ItemId' => 'something',
                'Quantity' => 1,
                'Annotation' => 'totally buying something'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{titleId}.playfabapi.com/Client/StartPurchase"

	payload := strings.NewReader("{\n  \"CatalogVersion\": \"0\",\n  \"StoreId\": \"BonusStore\",\n  \"Items\": [\n    {\n      \"ItemId\": \"something\",\n      \"Quantity\": 1,\n      \"Annotation\": \"totally buying something\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{titleId}.playfabapi.com/Client/StartPurchase")
  .header("X-Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"CatalogVersion\": \"0\",\n  \"StoreId\": \"BonusStore\",\n  \"Items\": [\n    {\n      \"ItemId\": \"something\",\n      \"Quantity\": 1,\n      \"Annotation\": \"totally buying something\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{titleId}.playfabapi.com/Client/StartPurchase")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"CatalogVersion\": \"0\",\n  \"StoreId\": \"BonusStore\",\n  \"Items\": [\n    {\n      \"ItemId\": \"something\",\n      \"Quantity\": 1,\n      \"Annotation\": \"totally buying something\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "status": "OK",
  "data": {
    "OrderId": "8853591446005860822",
    "Contents": [
      {
        "ItemId": "shield_level_5",
        "ItemClass": "shields",
        "DisplayName": "Level 5 Shield",
        "VirtualCurrencyPrices": {
          "RM": 199,
          "GV": 25
        }
      }
    ],
    "PaymentOptions": [
      {
        "Currency": "RM",
        "ProviderName": "Steam",
        "Price": 199
      },
      {
        "Currency": "RM",
        "ProviderName": "Amazon",
        "Price": 199
      },
      {
        "Currency": "RM",
        "ProviderName": "Paypal",
        "Price": 199
      },
      {
        "Currency": "GV",
        "ProviderName": "TitleA90A",
        "Price": 25
      }
    ],
    "VirtualCurrencyBalances": {
      "GV": 25
    }
  }
}

{
  "code": 123,
  "errorCode": 123,
  "status": "<string>",
  "error": "<string>",
  "errorMessage": "<string>",
  "errorDetails": {}
}

授权

X-Authorization

string

header

必填

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

请求体

application/json

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.

Items

object[]

必填

Array of items to purchase.

Show child attributes

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.

响应

code

integer

The Http status code. If X-ReportErrorAsSuccess header is set to true, this will report the actual http error code.

status

string

The Http status code as a string.

data

object

Show child attributes

示例:

{
  "OrderId": "8853591446005860822",
  "Contents": [
    {
      "ItemId": "shield_level_5",
      "ItemClass": "shields",
      "DisplayName": "Level 5 Shield",
      "VirtualCurrencyPrices": { "RM": 199, "GV": 25 }
    }
  ],
  "PaymentOptions": [
    {
      "Currency": "RM",
      "ProviderName": "Steam",
      "Price": 199
    },
    {
      "Currency": "RM",
      "ProviderName": "Amazon",
      "Price": 199
    },
    {
      "Currency": "RM",
      "ProviderName": "Paypal",
      "Price": 199
    },
    {
      "Currency": "GV",
      "ProviderName": "TitleA90A",
      "Price": 25
    }
  ],
  "VirtualCurrencyBalances": { "GV": 25 }
}

最后修改于 2026年10月6日

⌘I

Start Purchase

curl --request POST \
  --url https://{titleId}.playfabapi.com/Client/StartPurchase \
  --header 'Content-Type: application/json' \
  --header 'X-Authorization: <api-key>' \
  --data '
{
  "CatalogVersion": "0",
  "StoreId": "BonusStore",
  "Items": [
    {
      "ItemId": "something",
      "Quantity": 1,
      "Annotation": "totally buying something"
    }
  ]
}
'

import requests

url = "https://{titleId}.playfabapi.com/Client/StartPurchase"

payload = {
    "CatalogVersion": "0",
    "StoreId": "BonusStore",
    "Items": [
        {
            "ItemId": "something",
            "Quantity": 1,
            "Annotation": "totally buying something"
        }
    ]
}
headers = {
    "X-Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Authorization': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    CatalogVersion: '0',
    StoreId: 'BonusStore',
    Items: [{ItemId: 'something', Quantity: 1, Annotation: 'totally buying something'}]
  })
};

fetch('https://{titleId}.playfabapi.com/Client/StartPurchase', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{titleId}.playfabapi.com/Client/StartPurchase",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'CatalogVersion' => '0',
    'StoreId' => 'BonusStore',
    'Items' => [
        [
                'ItemId' => 'something',
                'Quantity' => 1,
                'Annotation' => 'totally buying something'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{titleId}.playfabapi.com/Client/StartPurchase"

	payload := strings.NewReader("{\n  \"CatalogVersion\": \"0\",\n  \"StoreId\": \"BonusStore\",\n  \"Items\": [\n    {\n      \"ItemId\": \"something\",\n      \"Quantity\": 1,\n      \"Annotation\": \"totally buying something\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{titleId}.playfabapi.com/Client/StartPurchase")
  .header("X-Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"CatalogVersion\": \"0\",\n  \"StoreId\": \"BonusStore\",\n  \"Items\": [\n    {\n      \"ItemId\": \"something\",\n      \"Quantity\": 1,\n      \"Annotation\": \"totally buying something\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{titleId}.playfabapi.com/Client/StartPurchase")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"CatalogVersion\": \"0\",\n  \"StoreId\": \"BonusStore\",\n  \"Items\": [\n    {\n      \"ItemId\": \"something\",\n      \"Quantity\": 1,\n      \"Annotation\": \"totally buying something\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "status": "OK",
  "data": {
    "OrderId": "8853591446005860822",
    "Contents": [
      {
        "ItemId": "shield_level_5",
        "ItemClass": "shields",
        "DisplayName": "Level 5 Shield",
        "VirtualCurrencyPrices": {
          "RM": 199,
          "GV": 25
        }
      }
    ],
    "PaymentOptions": [
      {
        "Currency": "RM",
        "ProviderName": "Steam",
        "Price": 199
      },
      {
        "Currency": "RM",
        "ProviderName": "Amazon",
        "Price": 199
      },
      {
        "Currency": "RM",
        "ProviderName": "Paypal",
        "Price": 199
      },
      {
        "Currency": "GV",
        "ProviderName": "TitleA90A",
        "Price": 25
      }
    ],
    "VirtualCurrencyBalances": {
      "GV": 25
    }
  }
}

{
  "code": 123,
  "errorCode": 123,
  "status": "<string>",
  "error": "<string>",
  "errorMessage": "<string>",
  "errorDetails": {}
}

PlayFab API

PlayFab REST API References

开始购买

Error codes

授权

请求体

响应