Salla Publication Consistency

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 — app_publish action=get (or salla_apps action=get) returns can_publish, requires_citc, and can_have_free_plan. Check them before filling:

1. The app must be publishable. can_publish must be true. If false, the app cannot be submitted.
2. 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).
3. 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 → send_publish_request

app_publish 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 app_publish action=send_publish_request 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 app_page_builder → 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 app_publish action=get. It returns publication_last_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. short_description 50–200, video_url/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.
2. 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).
3. 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):

app_page_builder 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 (salla_settings action=set_features) 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.:
  • basic_information → value prop / short description, main category + sub-categories, supported countries, a demo/video URL? (video_url 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?
  • contact_information → support email/phone, policy + FAQ URLs?
  • App Information (app_page_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 salla_reference action=categories; the pricing models Salla billing supports (free / one-time / subscription plans + addons + trial → salla-app-billing); supported-country options from salla_reference 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, is_compare_included.
• Strikethrough pricing — one_time_old_price (once) or a plan's old_price.
• Adjustable quantities — plan_additional_features (once) / per-plan additional_features.
• Churn-prevention — unsubscribe_reward, unsubscribe_email_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.
3. Author builder content (screenshots, benefits, listing name/description/logo) via app_page_builder → salla-app-ui-builder so features completes — applying the image-asset rule above for any missing image.
4. Finalize the settings form (salla_settings); for communication apps run salla_settings action=set_features.
5. Re-run readiness — confirm all 5 sections read complete.
6. 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 webhook_url. So there is no subscribe call to check. Auto-check: salla_apps action=get shows a webhook_url 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 item_type: 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.
7. 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/{app_id}/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 app_publish action=send_publish_request 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 send_publish_request 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 send_publish_request confirm=true), never before.

Red Flags