Skip to main content
A playtest lets a chosen group of players try a game before release. The 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:
Create a playtest for an audience:
Change a playtest’s end date:
Publish a playtest:
Delete a playtest:

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:
The retry returns the playtest if the first request created it, and creates it otherwise. When an option holds a line break, only the key is printed; run the same command with --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 from xbox package list, and pass its id to the option for its platform:
On update, a package option you leave out keeps its package, a new ID replaces it, and "" removes it:

Updating a playtest

Any update returns a published playtest to draft, as editing it in Partner Center does. Publish it again with playtest publish to make it available to players.
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:
When the outcome is unknown, the command exits 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 an id from audience list to --audience-id, and repeat it for more:
Without --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.
Publishing offers the playtest to its audiences from its start date. The command publishes the version it reads first; if the playtest changes in between, the publish fails with 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 exit 1, 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.
Last modified on November 18, 2026