Utiliser un coupon

NOTE: This is a Legacy Economy API, and is in bugfix-only mode. All new Economy features are being developed only for version 2. Adds the virtual goods associated with the coupon to the user’s inventory. Coupons can be generated via the Economy->Catalogs tab in the PlayFab Game Manager.

Error codes

This operation may return the following PlayFab errors:

Error	Code
CatalogNotConfigured	1218
CharacterNotFound	1135
CouponAlreadyRedeemed	1226
CouponCodeNotFound	1016
LegacyEconomyDisabled	4016
ProductDisabledForTitle	1609

POST

Server

RedeemCoupon

Redeem Coupon

curl --request POST \
  --url https://{titleId}.playfabapi.com/Server/RedeemCoupon \
  --header 'Content-Type: application/json' \
  --header 'X-SecretKey: <api-key>' \
  --data '
{
  "CouponCode": "123-1234-123",
  "CatalogVersion": "5"
}
'

import requests

url = "https://{titleId}.playfabapi.com/Server/RedeemCoupon"

payload = {
    "CouponCode": "123-1234-123",
    "CatalogVersion": "5"
}
headers = {
    "X-SecretKey": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-SecretKey': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({CouponCode: '123-1234-123', CatalogVersion: '5'})
};

fetch('https://{titleId}.playfabapi.com/Server/RedeemCoupon', 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/Server/RedeemCoupon",
  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([
    'CouponCode' => '123-1234-123',
    'CatalogVersion' => '5'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-SecretKey: <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/Server/RedeemCoupon"

	payload := strings.NewReader("{\n  \"CouponCode\": \"123-1234-123\",\n  \"CatalogVersion\": \"5\"\n}")

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

	req.Header.Add("X-SecretKey", "<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/Server/RedeemCoupon")
  .header("X-SecretKey", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"CouponCode\": \"123-1234-123\",\n  \"CatalogVersion\": \"5\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{titleId}.playfabapi.com/Server/RedeemCoupon")

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

request = Net::HTTP::Post.new(url)
request["X-SecretKey"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"CouponCode\": \"123-1234-123\",\n  \"CatalogVersion\": \"5\"\n}"

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

{
  "code": 200,
  "status": "OK",
  "data": {
    "GrantedItems": [
      {
        "ItemId": "shield_level_5",
        "ItemInstanceId": "Unique Item ID",
        "ItemClass": "shields",
        "PurchaseDate": "2014-03-07T00:00:00",
        "Expiration": "2015-10-01T00:00:00",
        "RemainingUses": 10,
        "Annotation": "No Annotation",
        "CatalogVersion": "5",
        "BundleParent": "crate block 1"
      }
    ]
  }
}

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

Autorisations

X-SecretKey

string

header

requis

This API requires a title secret key, available to title admins, from PlayFab Game Manager.

Corps

application/json

Coupon codes can be created for any item, or set of items, in the catalog for the title. This operation causes the coupon to be consumed, and the specific items to be awarded to the user. Attempting to re-use an already consumed code, or a code which has not yet been created in the service, will result in an error.

CouponCode

string

requis

Generated coupon code to redeem.

PlayFabId

string

requis

Unique PlayFab assigned ID of the user on whom the operation will be performed.

CatalogVersion

string

Catalog version of the coupon.

CharacterId

string

Optional identifier for the Character that should receive the item. If null, item is added to the player

CustomTags

object

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

Réponse

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

Exemple:

{
  "GrantedItems": [
    {
      "ItemId": "shield_level_5",
      "ItemInstanceId": "Unique Item ID",
      "ItemClass": "shields",
      "PurchaseDate": "2014-03-07T00:00:00",
      "Expiration": "2015-10-01T00:00:00",
      "RemainingUses": 10,
      "Annotation": "No Annotation",
      "CatalogVersion": "5",
      "BundleParent": "crate block 1"
    }
  ]
}

Dernière modification le 6 octobre 2026

Sujets connexes

Utiliser un coupon Coupons et promotions dans Economy (hérité)Utiliser XAudio2 pour lire un son Utiliser Review and Publish pour publier un jeu player_redeemed_coupon

⌘I

Redeem Coupon

curl --request POST \
  --url https://{titleId}.playfabapi.com/Server/RedeemCoupon \
  --header 'Content-Type: application/json' \
  --header 'X-SecretKey: <api-key>' \
  --data '
{
  "CouponCode": "123-1234-123",
  "CatalogVersion": "5"
}
'

import requests

url = "https://{titleId}.playfabapi.com/Server/RedeemCoupon"

payload = {
    "CouponCode": "123-1234-123",
    "CatalogVersion": "5"
}
headers = {
    "X-SecretKey": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-SecretKey': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({CouponCode: '123-1234-123', CatalogVersion: '5'})
};

fetch('https://{titleId}.playfabapi.com/Server/RedeemCoupon', 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/Server/RedeemCoupon",
  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([
    'CouponCode' => '123-1234-123',
    'CatalogVersion' => '5'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-SecretKey: <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/Server/RedeemCoupon"

	payload := strings.NewReader("{\n  \"CouponCode\": \"123-1234-123\",\n  \"CatalogVersion\": \"5\"\n}")

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

	req.Header.Add("X-SecretKey", "<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/Server/RedeemCoupon")
  .header("X-SecretKey", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"CouponCode\": \"123-1234-123\",\n  \"CatalogVersion\": \"5\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{titleId}.playfabapi.com/Server/RedeemCoupon")

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

request = Net::HTTP::Post.new(url)
request["X-SecretKey"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"CouponCode\": \"123-1234-123\",\n  \"CatalogVersion\": \"5\"\n}"

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

{
  "code": 200,
  "status": "OK",
  "data": {
    "GrantedItems": [
      {
        "ItemId": "shield_level_5",
        "ItemInstanceId": "Unique Item ID",
        "ItemClass": "shields",
        "PurchaseDate": "2014-03-07T00:00:00",
        "Expiration": "2015-10-01T00:00:00",
        "RemainingUses": 10,
        "Annotation": "No Annotation",
        "CatalogVersion": "5",
        "BundleParent": "crate block 1"
      }
    ]
  }
}

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

PlayFab API

PlayFab REST API References

Utiliser un coupon

Error codes

Autorisations

Corps

Réponse