playtest commands read
a game’s playtests in Partner Center, and create, update, publish, and delete them. create,
update, publish, and delete ask before they make a change.
create, update, publish, and delete are Experimental: their options and output might change
or be removed. See Experimental commands.
Commands
Arguments and options
Examples
List playtests, get one, and compare two:Reading playtests
playtest list writes a playtests array. Its table has PLAYTEST ID, NAME, STATUS, TYPE,
START, and END columns. An excerpt:
playtest get writes the playtest as the service returns it. etag is the version to pass to
update --if-match, and audiences.audienceIds lists the audiences that can join. Its table has
FIELD and VALUE rows.
playtest diff writes hasDiffData, current, and compared. When hasDiffData is false,
there’s nothing to compare, and compared is left out. Its table shows only the fields that
differ, in FIELD, CURRENT, and COMPARED columns. Images aren’t compared.
Creating a playtest
playtest create makes a private draft playtest and writes it as playtest get does. Running it
again creates another playtest; remove one you don’t want with
playtest delete.
Each create sends an idempotency key, a new GUID unless you pass --idempotency-key. A create that
repeats a key returns the playtest that key created, and ignores any options that differ.
When the outcome is unknown, such as after a timeout, the command exits 3 and prints a command
that retries with the same key:
--idempotency-key and that key. If the retry is refused, such as because the end date has passed,
check playtest list before you create the playtest with a new key.
Packages
A playtest can have one PC package and one console package. Choose a package that’s ready for a playtest fromxbox package list, and pass its id to the option
for its platform:
update, a package option you leave out keeps its package, a new ID replaces it, and ""
removes it:
Updating a playtest
playtest update changes only the options you pass, and needs at least one. It writes the updated
playtest as playtest get does. Game art configured in Partner Center is kept; other art linked to
the playtest is replaced with a placeholder.
To avoid overwriting someone else’s change, pass the etag from playtest get in --if-match.
The double quotes around it are optional, and *, weak (W/) etags, and lists of etags are
refused:
3. Check the playtest with playtest get before
you retry.
Choosing audiences
An audience is a group of players, such as testers, that the seller manages in Partner Center. Pass anid from audience list to --audience-id, and repeat it for more:
--audience-id, create makes a playtest with no audiences, and update keeps them. On
update, the IDs you pass replace all of the playtest’s audiences. To remove every audience, pass
"" alone:
"" can’t be combined with audience IDs, and create refuses it. A playtest needs at least one
audience to be published.
Publishing a playtest
If the game uses XBOX services, set up their configuration and embargo before you publish. See Use XBOX services in a playtest.412 and
changes nothing.
Before it asks you to confirm, the command checks the game’s XBOX services setup, such as whether
its embargo date is after the playtest’s end date, and lists anything to review on stderr. These
checks only advise; --confirm publishes without asking.
The service then runs its own checks. When one blocks the publish, nothing is queued, and the
command lists each check on stderr and exits 1. Fix the errors and publish again. A playtest
blocked for missing age ratings needs the age-rating questionnaire completed in Partner Center.
Once the publish is queued, the command waits until the playtest is Scheduled, Live, or
PublishFailed, and writes it as playtest get does. Ctrl+C stops waiting, but the publish
continues. With --no-wait, the command writes publishJobId and any warnings as soon as the
publish is queued; follow it with playtest get.
Deleting a playtest
playtest delete deletes the version of the playtest it reads first. It waits until the playtest
is Deleted or gone, then writes the service’s response, with status. Ctrl+C stops waiting, but
the delete continues. With --no-wait, it writes the response as soon as the delete is queued.
After a 412, the delete might already be queued, so wait a minute and check with playtest get
before you delete again.
Dates
--start and --end accept ISO 8601 dates and times, such as 2026-11-01T09:00:00-07:00 or
2026-11-01T16:00:00Z. A date without a time means midnight UTC, and a time without an offset is
UTC. When an update passes only one date, the service checks it against the playtest’s other date.
Errors
Failures go to stderr and exit1, unless the exit-code tables above say otherwise. create and
update exit 3 when their outcome is unknown. A failure the service returns includes its HTTP
status, and --verbose adds the service’s response, whose code field is shown here:
For other failures, the command shows the service’s message. A 429 means you sent too many
requests; wait as long as the message says before you try again.
