Help with my ideal flow and documentation (flight -> update metadata -> rollout)

[PandaSharp (Panda-Sharp)]

Hello guys,

I'm really struggling with the current documentation (https://learn.microsoft.com/en-us/windows/apps/publish/msstore-dev-cli/commands?pivots=msstoredevcli-installer-windows) to try to implement my ideal flow.

First thing I noticed in the docs, looks like there are duplicated commands like the flights ones and it miss some proper real life examples, anyway let's try to go trough all my steps:

1. I want to publish my package to a flight group, so I execute

msstore publish "C:\path\to\winui3_app" --flightId ${flightId}

2. I would like to promote a flght package to a draft submission, but looks like it's not possible, so I have to reupload the package and create the submission like this

msstore publish "C:\path\to\winui3_app" --noCommit

3. Now I want to update some metadata

e.g. release notes (code cut to essential)

so I download the submission json
msstore submission get ${productId}

update the json
$package.'Listings'.'en-us'.'BaseListing'.'ReleaseNotes' = "Bug fixes and improvements"

and update the submission
msstore submission update ${productId} ${packageJson}

here I have 2 questions:

• what's the difference between submission update and submission updateMetadata
• would be nice to provide some real life json examples

6. Now I would like to start the rollout to 5% and here I'm stuck, the only methods that support it are
   msstore publish "C:\path\to\winui3_app" --packageRolloutPercentage 5
   but than I'll have to update the package again? and what happens to my updated metadata?

and
msstore flights submission rollout get <productId> <flightId>
but this works only for flights right?

7. Now I'd like to increase the rollout
   Looks like it's possible only for flights
   msstore flights submission rollout update <productId> <flightId> <percentage>

8. Now I'd like to finalize the rollout
   again looks like it's possible only for flights
   msstore flights submission rollout finalize <productId> <flightId>

Thanks

[PandaSharp (Panda-Sharp)]

cc Alexandre Zollinger Chohfi (@azchohfi) any idea if these are/will be even possible or if I'm missing something? thanks

[Alexandre Zollinger Chohfi (azchohfi)]

Hi PandaSharp (@Panda-Sharp), sorry for the slow reply here.

Short version: almost everything you want already works today, without flights. The blocker is a documentation gap, not a missing feature.

The docs bug you hit

msstore submission rollout exists and has get / update / halt / finalize, exactly like the flight version. It's just missing from the Submission Command table on the Learn page, while the flight one is documented — which is why it looked to you like rollout was flights-only. Try it:

msstore submission rollout --help

I'll get the docs page fixed. That also explains the "duplicated commands" feeling: the flight commands are genuinely a parallel set (msstore flights submission ... vs msstore submission ...), operating on flight submissions vs. the main app submission.

submission update vs submission updateMetadata

For an MSIX/packaged app (product ID like 9NBLGGGZ5QDQ) they are literally the same code path — updateMetadata just forwards to update. Use either; both take the full submission JSON and PUT it back.

They only differ for unpackaged apps (MSI/EXE, product ID is a GUID):

Command	Unpackaged behavior
submission update	Updates the packages (UpdatePackagesRequest)
submission updateMetadata	Updates the listing metadata (UpdateMetadataRequest)

So for your WinUI 3 app, just use submission update.

The one gotcha that will bite you: ordering

If your app already has a published submission, msstore publish deletes the existing pending draft and creates a fresh one cloned from your last published submission. So if you update metadata and then publish, your metadata edits are thrown away. (On a brand-new app that hasn't published yet, it reuses the draft instead — but the safe ordering below works either way, so I'd just always follow it.)

Always: publish (--noCommit) → edit metadata → commit.

Rollout without re-uploading the package

This is the key bit you were missing — and there are two ways to do it, neither of which needs a second upload.

Option A — fold it into the metadata update. The rollout lives in the same submission JSON you're already editing for release notes:

"PackageDeliveryOptions": {
  "PackageRollout": {
    "IsPackageRollout": true,
    "PackageRolloutPercentage": 5,
    "PackageRolloutStatus": "PackageRolloutNotStarted",
    "FallbackSubmissionId": "0"
  },
  "IsMandatoryUpdate": false,
  "MandatoryUpdateEffectiveDate": "1601-01-01T00:00:00Z"
}

Set it in the same submission update call as your release notes. One round trip, no second upload, metadata preserved.

This isn't a workaround, incidentally — it's the officially documented way to enable a rollout programmatically. From Manage app submissions:

1. Create an app submission or get an existing app submission.
2. In the response data, locate the packageRollout resource, set the isPackageRollout field to true, and set the packageRolloutPercentage field to the percentage of your app's customers who should get the updated packages.
3. Pass the updated app submission data to the update an app submission method.

That same page also confirms the ramp-up story: you can change the rollout percentage or halt it "for a published submission without having to create a new submission."

Option B — set it at publish time. msstore publish ... --packageRolloutPercentage 5 also works, and applies the rollout to the submission it creates. The catch is ordering: publish recreates the draft, so if you need metadata edits too they have to come after it. That's why the flow below uses --noCommit first and then patches metadata and rollout together.

Your full flow, end to end

$productId = '9NBLGGGZ5QDQ'
$flightId  = '<flight-id>'
$appPath   = 'C:\path\to\winui3_app'

# 1. Ship to the flight group
msstore publish $appPath --flightId $flightId

# 2. Upload the same package to the main draft, but don't commit it yet.
#    (This wipes any existing draft, so it MUST come before metadata edits.)
msstore publish $appPath --noCommit

# 3. Patch release notes AND arm the 5% rollout in a single update
$submission = msstore submission get $productId | ConvertFrom-Json

$submission.Listings.'en-us'.BaseListing.ReleaseNotes = 'Bug fixes and improvements'

if (-not $submission.PackageDeliveryOptions) {
    $submission | Add-Member PackageDeliveryOptions ([pscustomobject]@{ IsMandatoryUpdate = $false }) -Force
}
$submission.PackageDeliveryOptions | Add-Member PackageRollout ([pscustomobject]@{
    IsPackageRollout         = $true
    PackageRolloutPercentage = 5
}) -Force

msstore submission update $productId ($submission | ConvertTo-Json -Depth 100 -Compress)

# 4. Commit and wait for certification
msstore submission publish $productId
msstore submission poll $productId

# 5. Ramp up later — no re-upload, no new submission
msstore submission rollout get    $productId
msstore submission rollout update $productId 20
msstore submission rollout update $productId 50

# 6. Ship to everyone (or pull the cord)
msstore submission rollout finalize $productId
# msstore submission rollout halt   $productId

rollout get/update/halt/finalize also accept -s, --submissionId if you need to target a specific submission instead of letting the CLI resolve the pending/last-published one.

Caveat on how far I verified this. I checked the individual pieces against a real Partner Center account — the command surface (submission rollout and its four sub-commands, arguments and options), the JSON shapes you'll get back from submission get, and the packageDeliveryOptions.packageRollout structure. The rollout procedure itself is straight from the official docs linked above. What I have not done is run this exact sequence end to end on a live app through certification and out the other side, so treat the ordering and the hand-off between steps as well-reasoned rather than battle-tested. If you hit a snag at a specific step, say which one and I'll dig in.

Step 2: promoting a flight package to the main submission

You're right that the CLI can't do it, and it's a Store API limitation rather than a CLI one — but the nuance is worth spelling out, because Partner Center can do this and the REST API cannot.

The concept is explicitly supported by the Store (Package flights):

If you later decide that you want to make packages from a package flight available to all your customers, you can easily use those same packages in a non-flighted submission.

and, in the same doc's Specify packages to include in your package flight section, you can pick "packages that were associated with a previous published submission (either a non-flighted submission, or one of your other package flights)". So in the UI, reusing a flight's packages in a non-flighted submission is a supported, no-re-upload operation.

The REST API that the CLI sits on top of has no equivalent. Both method tables are closed sets of six operations, and neither includes a promote/copy-packages call:

• Manage app submissions — GET, GET status, POST create, PUT update, POST commit, DELETE
• Manage package flight submissions — same six, scoped to /flights/{flightId}

The mechanical reason is in the POST .../submissions description on both pages: it "creates a new in-progress submission, which is a copy of your last published submission." An app submission clones the last published app submission, and a flight submission clones the last published flight submission. The two lineages never cross, so a flight package simply has no package ID that a non-flighted submission can reference.

So: re-uploading, as you're doing in step 2, is the correct workaround for a fully automated pipeline. If you'd rather not upload twice, the alternative is to do that one step in Partner Center — but then the submission is no longer API-created, and per the API docs mixing the two is explicitly warned against:

If you use Partner Center to change a submission that you originally created by using the API, you will no longer be able to change or commit that submission by using the API.

For a CI/CD flow, stick with the double upload. That's simply how the submission API is designed — the two submission types are separate resources and there's no operation that bridges them, so it isn't something the CLI can paper over.

Follow-ups I'm taking

I've opened a docs PR covering these; it's in review now, so the Learn page should catch up shortly:

1. ✅ Add the missing submission rollout section to the Learn page — it was absent from the Submission table entirely, which is the root of this whole thread.
2. ✅ Add a realistic end-to-end example (upload → metadata → staged rollout → finalize) rather than isolated per-command snippets.
3. ✅ Document the publish → metadata ordering constraint, which is genuinely surprising.
4. ✅ Clarify that update and updateMetadata are equivalent for packaged apps.

On the duplicated commands — you read that correctly, the flights sections really do appear twice on that page. They aren't behind pivot tabs, so both copies render one after the other. I'm leaving that one alone for now; it's a large deletion and I'd rather not bundle it into a docs fix that's otherwise purely additive.

The command syntax and JSON shapes above were checked against a real Partner Center account rather than just read off the source, so those should match what you actually get back — with the end-to-end caveat noted earlier.

Hope this unblocks you — shout if any step misbehaves.

[PandaSharp (Panda-Sharp)]

No worries, things can get busy... Thank you so much for the amazingly detailed reply, now everything is much clearer !
I'm busy with other stuff now, I'll try as soon I'll get a chance and if I'll still have some issues or doubts I'll ping you again, thanks a lot!