Salla Publication Consistency

Scope: PUBLIC apps (App Store listing). Private apps don't use this stepwise flow and have no MCP publish action — the partner sends their publish request from the app-details page https://portal.salla.partners/apps/{app_id} (see salla-app-builder).

Before you can publish — prerequisites

Check these first; they gate the whole flow regardless of the sections:

All three are readable from app details — apppublish action=get (or sallaapps action=get) returns canpublish, requirescitc, and canhavefree_plan. Check them before filling:

1. The app must be publishable. can_publish must be true. If false, the app cannot be

submitted.

1. The partner's account must be verified. Before publishing, the partner verifies their

account at https://portal.salla.partners/account. An unverified account blocks submission (validate/submit returns an id_verification error).

1. CITC certification (SMS communication apps). When requires_citc is true, the partner

must upload a CITC certification on the account verification form before publishing (Saudi regulatory requirement) → salla-communication-app.

Prepare a Salla app for review via app_publish (base /app/{id}/publication): a readiness-driven loop, not one bulk call. Fill sections one at a time; the server decides when the draft is ready.

**open → get (read the current draft) → (set <section> → readiness)\* → validate → partner reviews the /publish link → sendpublishrequest**

apppublish action=validate validates every section for completeness/correctness and saves a DRAFT, returning a valid publication — it does not submit. Sending the app to Salla review is HARD-GATED: after a clean validate, surface the partner's real /publish link (id substituted) and ask them to REVIEW the draft. Only then does it go to review — either the partner submits one-click in the Portal, or, after they explicitly confirm, the agent calls apppublish action=sendpublishrequest with confirm: true. Never send the request before a clean validate and the partner reviewing the link and confirming.

Drive off the readiness checklist returned by open and every set: it marks each section complete or, for incomplete ones, lists the exact missing fields. Fix the one section it points at, re-check, repeat. validate runs the same server-side gate and returns 422 + missing sections if anything is incomplete, and saves the draft when every section is complete.

The loop (app_publish, base /app/{id}/publication)

Listing content (name, description, logo, screenshots, benefits) is authored with apppagebuilder → salla-app-ui-builder.

Read the current draft first (resume / review)

Before filling or fixing anything — especially when resuming a draft or asked to review one — read it with apppublish action=get. It returns publicationlast_save (every saved section value) plus the app's scopes and webhooks. readiness tells you what's missing; get tells you what's already there — never re-ask the partner for a value the draft already holds, and never blind-overwrite a section you haven't read.

Validation is step-by-step

Three layers, in order — don't defer everything to one bulk check at the end:

1. set validates FORMAT per section (server PublicationSectionRequest: e.g.

shortdescription 50–200, videourl/URLs well-formed, plan numeric rules). A set that returns 422 is THIS section's validation error — the tool surfaces the field messages; fix them and set again before moving on.

1. readiness reports COMPLETENESS — which sections are complete and the exact missing

(blank) fields. Completeness ≠ correctness: a field can be present-but-invalid (caught by set) or present-but-blank (caught by readiness).

1. validate is the final CROSS-FIELD + requiredness gate over the whole draft — it saves

the DRAFT when clean, or returns 422 + the still-missing sections.

The loop: set <section> → if 422, fix this section → readiness → next. Catch each section's errors as you write it, not in one end-of-flow validate.

Step map — this skill is the master router

Each publication step routes to the skill that owns its modelling, and each has a reference (data retrieval → submission schema → how to submit):

apppagebuilder is the App Store LISTING/PROFILE page builder — the public app profile
(rating, plans, install button). It is publication-coupled: it pulls images/text/plans from the
draft, can be edited against a draft publication, and its **images and content override the
publication's. It is NOT the post-install embedded dashboard UI (→ salla-embedded-app** /
salla-embedded-ui).

The 5 sections at a glance

Pass section + only the fields you're writing (localized fields take { ar, en }; image fields an integer id from salla_upload; multi-value fields an array). Per-field schema, server rules, and a worked set example are in each step's reference (Step map above) — read it before writing.

Route elsewhere — not set via app_publish

These live outside the publication sections. Finalize each in its own tool, then re-check readiness:

Security review checks belong to the owning skills: minimum OAuth scopes → salla-app-auth; webhook signature verification + authenticated interfaces → salla-webhooks; secret handling → keep credentials test-only, redacted, never plaintext.

The draft is a snapshot taken at validate, not a live mirror. Settings snapshot when the draft is saved and are matched against the live state, so finalize the external pieces before you validate and do settings last:

• Finalize the settings form (salla_settings) before validate — whatever is live when

the draft is saved is what the partner submits.

• Communication apps must declare supported features

(sallasettings action=setfeatures) before validate, or the gate blocks.

• After changing any external piece (scopes, webhook, events, settings, builder content),

re-run readiness (re-open if needed) and validate again before handing off.

First-time publish — guided onboarding, not a blind fill

The publication sections carry the partner's business decisions — listing copy, categories, pricing/plans/trial, contact, supported countries, screenshots/benefits. For a first-time publish, walk the partner through the sections one at a time; fill each from their answers, never invent or auto-fill. At each section:

• Ask the right questions for that section, e.g.:

- basicinformation → value prop / short description, main category + sub-categories, supported countries, a demo/video URL? (videourl is required — if they have none, point them to the educational-video guide: https://salla.dev/tutorial/educational-video-guidelines-apps-ar/) - pricing → free or paid? one-time, subscription plans, or addons? a trial? - contactinformation → support email/phone, policy + FAQ URLs? - App Information (apppage_builder) → name, description, logo, ≥3 screenshots, benefits?

• Suggest valid options grounded in Salla so the partner picks from real choices, not

guesses: real categories from sallareference action=categories; the pricing models Salla billing supports (free / one-time / subscription plans + addons + trial → salla-app-billing); supported-country options from sallareference action=countries.

• Fill from the answers, then run app_publish action=readiness to see what's still

missing, and move to the next section.

Suggest the publication-window monetization features. First publish is the moment to set these — surface them as grounded opt-in options (never auto-add), each routing to salla-app-billing / salla-addon-purchase:

• Addons — extra in-app purchases on top of any plan.
• Trial — a free plan_trial (days) and/or the reviewer service trial.
• Promotions — time-boxed plan discounts (promotions[]).
• Comparison matrix — plan_features[] to compare plans side by side.
• Recommended / highlighted plan — recommended, iscompareincluded.
• Strikethrough pricing — onetimeoldprice (once) or a plan's oldprice.
• Adjustable quantities — planadditionalfeatures (once) / per-plan additional_features.
• Churn-prevention — unsubscribereward, unsubscribeemail_reward.

Note which are publication-window only; per-merchant/tailored plans come later via App details → Custom Plans. Any paid choice triggers the billing-cycle gate (below).

This composes with the image-asset rule below (ask for images; on skip → clearly-marked placeholders + tell the partner to replace them).

Gate: "Each section filled from the partner's answers — listing copy, categories, pricing, contact — not auto-invented?"

Listing images — ask first, placeholder only with a heads-up

The listing needs real images: logo + ≥3 screenshots (App Information), banner + embedded_image (App Features). These are owned by salla-app-ui-builder — read it for the fields, dimensions, and the generate-then-upload recipe. The discipline here:

• If you don't have the images, ASK the user to provide all the required ones. Don't

invent a real-looking image and don't silently skip them — this is verify-don't-invent.

• If the user skips or declines, proceed with clearly-marked default placeholders so the

draft still validates — then explicitly tell the partner to replace the placeholders in the Portal before they do the one-click submit. Never present a placeholder as final.

Gate: "Every listing image is a real partner asset — or a placeholder the partner has been explicitly told to replace before submitting?"

Pre-publication sequence (in order)

1. Open the draft (action=open); read the initial readiness checklist.
2. set each incomplete section's data, re-checking readiness after each — **one section

at a time**, driven off the returned missing list.

1. Author builder content (screenshots, benefits, listing name/description/logo) via

apppagebuilder → salla-app-ui-builder so features completes — applying the image-asset rule above for any missing image.

1. Finalize the settings form (salla_settings); for communication apps run

sallasettings action=setfeatures.

1. Re-run readiness — confirm all 5 sections read complete.
2. Validate + save the draft (action=validate). On 422, set the missing sections

and validate again until it returns a valid publication. 6b. Billing-cycle gate — paid pricing only, BEFORE submit. If the draft's pricing has a recurring plan or any addon, the app must handle the subscription lifecycle before it can go to review. The lifecycle rides on app events (app.subscription. / app.trial.), which the app is subscribed to by default — Salla auto-delivers them to the webhookurl. So there is no subscribe call to check. Auto-check: sallaapps action=get shows a webhookurl set, and the partner's handler covers the full app.subscription. / app.trial. family (→ salla-app-billing Step 2). This only proves the receiver is wired at the platform level — not that the handler code is deployed and working. So also verify a real round-trip: fire a test subscription event on a demo store and confirm the app provisions/revokes correctly (→ salla-live-testing). Then user-confirm: ask the partner to confirm the handlers are deployed and tested for the FULL lifecycle — provision on started, re-point entitlement on renewed, revoke on expired/canceled (verify itemtype: plan vs addon), and for external_recurring addons the renew API is wired (→ salla-app-billing). If not coherent, do NOT submit — keep the saved draft, hand off to salla-app-billing / salla-addon-purchase to implement the billing cycle, then re-check and re-gate. Only a coherent billing cycle clears this gate.

1. Ask the partner to REVIEW, then send the publish request. Give them their real Portal

link — substitute the app's actual id, never the placeholder: https://portal.salla.partners/apps/{appid}/publish (e.g. https://portal.salla.partners/apps/1234567/publish). Tell them to review the draft there. To go to review, either the partner clicks submit one-click in the Portal, or — only after they explicitly confirm — you call apppublish action=sendpublishrequest with confirm: true. Hard rule: never send the request before a clean validate, the partner being shown the link, and their confirmation.

Gate: "All sections validated + saved as a draft; for paid pricing (recurring plan or any addon) the billing cycle is wired + confirmed (else kept as a draft until it is); the partner was given the real /publish link and asked to review — and sendpublishrequest fires ONLY after they confirm (or they submit one-click themselves)?"

Done (for the agent) means validate returns a valid publication and the partner has reviewed the real /publish link — the app goes to review only on their one-click submit or their explicit confirmation (then sendpublishrequest confirm=true), never before.

Red Flags