Skip to main content
XBOX test accounts are created in batches for a Partner Center seller. These commands create, update, and delete batches, follow the job that creates the accounts, and read batches and the accounts in them. They can’t change individual accounts, and they never return passwords. Your account needs the Partner Center test account role for the seller. Every command takes --seller-id. Without it, a command uses XBOX_SELLER_ID or the seller saved with xbox context set, and then your only seller; if you have several, pass --seller-id.

Commands

batch create, batch update, and batch delete ask before they change anything, and are sent once and never retried. See Safety and destructive operations.

Options for reading batches

Tags appear as keywords in JSON output and in error codes such as test_account_keyword_invalid. --tag matches a whole tag, not part of one. If you can’t read every batch for the seller, you get no error: batch list returns only the batches you created.

Expired batches

A batch is expired once its accessExpirationDate, the date its sandbox access ends, has passed. A batch with no date never expires. Expiry doesn’t say whether the accounts can still sign in. batch list --expired reads the seller’s whole list to find the expired batches, so it’s slower for a seller with many batches. It can’t be combined with --include-sandboxes; run batch get on an expired batch to see its sandbox access.

Response shape

list returns:
  • keywords and sandboxAccess are null unless you pass --include-sandboxes. get always returns them.
  • isComplete means the creation job stopped, not that every account was created. Compare the number of accounts from get with batchSize, and read progress for the status message.
  • createdBy is a numeric Partner Center user ID.
  • jobId is the batch’s running job, and is null once the job has stopped. Update and delete jobs appear here too, but only a creation job can be followed with job wait.
get returns the same batch object plus its accounts:
Each account has only xuid, email, gamertag, and isDeleted. xuid is a string.

Errors when reading batches

batch list, batch get, and test-account get exit 1 on failure. When the service returns a JSON error, stderr gets a JSON error with status, title, detail, code when the response includes one, and its correlationId; most add a hint to detail. Other failures print a line of text. Check the exit code before parsing stderr.

Looking up an account

test-account get <email> says whether the batch holding an account has expired. The email must end with @xboxtest.com. The command searches the newest 10 batches whose email template matches the account’s name. When it doesn’t find the account there, it says older batches weren’t searched and prints batch list and batch get commands to check them yourself. It returns the following, shortened here; batch holds every batch field that batch list returns:
expiredOn is null when the batch hasn’t expired. A deleted account is reported only when no live copy exists, with account.isDeleted set. The command exits 0 whenever it finds the account, expired or not, so scripts should read expired. It exits 1 when:
  • The account isn’t in the batches you can see. It might belong to another seller, so try --seller-id, or another developer created its batch and you can’t read every batch for the seller.
  • The email appears in more than one batch. stderr lists a batch get command for each.
  • A request fails, as in Errors when reading batches.

Creating a batch

batch create starts a job that creates the accounts, then waits for it to stop. The accounts count against the seller’s test account limit until the batch is deleted. In a terminal, the command shows the security question picker, lists the values it will send, including the defaults for options you left out, and asks you to confirm. It then prompts for the password and security answer, signs in, and sends the request. --confirm (--yes, -y) skips only the confirmation. Without a terminal, pass --password-file, --security-answer-file, and --confirm. Without --confirm, the command prints the values, refuses, and sends nothing.

Choosing a security question

In a terminal, when you pass neither --security-question nor --security-answer-file, the command shows a numbered picker of these questions. Enter selects the first. To choose one without the picker, pass its text with --security-question:
  1. What is your favorite hobby?
  2. Who is your favorite athlete?
  3. What is your maternal grandmother’s first name?
  4. What was your childhood best friend’s first name?
  5. What was the name of your first pet?
  6. What is your current best friend’s first name?
  7. What was your favorite city to visit as a child?
Without a terminal, or with an answer file and no question, the question is What is your favorite hobby?. Ctrl+C at the picker cancels without creating anything. Choosing a question doesn’t confirm the create.

Secrets

The password and security answer are never accepted as option values or environment variables, so they stay out of shell history, process listings, and logs. Each comes from:
  • Its --password-file or --security-answer-file. A single trailing line break is removed.
  • - in place of a path, which reads it from stdin. Only one of the two can read stdin.
  • With no file option, a prompt in the terminal that doesn’t echo what you type.
The password must be 8 to 16 characters and contain at least three of: lowercase letters, uppercase letters, numbers, and symbols. Underscore doesn’t count as a symbol. The password can’t match the security answer.

Waiting and exit codes

While it waits, the command prints progress to stderr. It writes the final job to stdout, in the same shape as job get.

When the outcome is unknown

When the CLI can’t tell whether the service created a batch, such as when the connection drops after the request is sent or the service returns a 5xx error, it exits 3. It never sends the create again. stderr prints the time the request started, in UTC, and these steps:
  1. Wait a few minutes; a batch still being created might not be listed yet.
  2. Run xbox test-account batch list --mine --email-prefix <prefix> and look for a batch with the same email prefix and template created at or after that time.
  3. If that batch’s jobId is set, follow it with xbox test-account job wait <job-id> --batch-id <batch-id>. If jobId is null, the job has stopped; inspect it with xbox test-account batch get <batch-id>.
  4. Create again only if no such batch exists.
The printed commands keep the seller, profile, and sign-in options you used, so you can copy them as they are.

Errors when creating

Failures write a JSON error to stderr with status, title, detail, and code when the response includes one. Branch on code, not on detail.

Following a creation job

batch create prints the batch and job IDs as soon as the job is accepted. A job can run for days, so you can stop waiting at any time and follow it later: Both return the job:
state is running, succeeded, or failed. errorCode is test_account_job_failed when the job failed. job wait retries temporary read failures, such as throttling or a dropped connection.

Errors when following a job

These error codes point at the job ID, --batch-id, or --seller-id:

Updating a batch

batch update changes every account in a batch: it can give them access to more sandboxes, take access away, move when that access expires, and add to or replace the batch’s tags. It then waits until the batch shows the change. In a terminal, the command first shows each requested change next to the batch’s current value, warns when a job is still running on the batch, and asks. Pass --confirm (--yes, -y) to skip the prompt. Without a terminal and without --confirm, it prints the changes, refuses, and sends nothing. Pass at least one change. A batch can have at most 20 tags. --replace-tags and --clear-tags keep the tag that records which tool created the batch, which doesn’t count toward the limit. Changing sandboxes or the expiry needs access to those sandboxes; extending the expiry needs access to every sandbox on the batch. The command returns the batch’s values once the update completes:
state is updated once the batch shows the change, or updating with --no-wait or when the wait ends first. When the batch already has every requested value, nothing changes: state is unchanged, jobId is null, and the command exits 0. Update jobs can’t be followed with job get or job wait.

Waiting and exit codes when updating

Errors when updating

A 404 or 405 with no code means updating batches isn’t available.

Deleting a batch

batch delete deletes a whole batch, then waits until it’s gone. Every account in the batch loses its sandbox access, and its test account record is deleted. The accounts’ Microsoft accounts and XBOX profiles aren’t closed. In a terminal, the command first shows the batch’s email template, size, and creator, warns when a job is still running on it, and asks. Pass --confirm (--yes, -y) to skip the prompt. Without a terminal and without --confirm, it prints what it would delete, refuses, and sends nothing. There’s no bulk delete; delete batches one at a time. The command returns:
state is deleted once the batch is gone, or deleting with --no-wait or when the wait ends first. Delete jobs can’t be followed with job get or job wait; while the delete runs, the batch shows its jobId.

Waiting and exit codes when deleting

Errors when deleting

A 404 or 405 with no code means deleting batches isn’t available.

Table output

Every command accepts --output table. Times are shown in UTC, and summary lines go to stderr, so stdout holds only the table.

Examples

These commands list and read batches, accounts, and jobs:
Create a batch of five accounts. The command prompts for the password and security answer, then asks you to confirm:
Create a batch unattended, with the secrets read from files, no prompt, and a wait of up to 30 minutes:
Wait up to two hours for a create job to finish:
Add a sandbox, and set when sandbox access expires. The command shows the changes, asks you to confirm, then waits until the batch shows them:
Add two tags unattended, without waiting:
Replace every tag with one:
Delete a batch. The command shows the batch, asks you to confirm, then waits until it’s gone:
Delete a batch another developer created, unattended and without waiting:
Last modified on November 18, 2026