03 - Customizing your Marketplace Listing

How to compose a listing's detail page in the Super App. A listing is made
of ordered panels (sections), and each panel holds ordered cards
(offers). The on-screen look is the combination of a panel's panelType +
layout and a card's design + linkType.

See also: Getting Started for the onboarding
checklist and Integration & API Reference
for the full lifecycle walkthrough.

1. Storefront at a glance

You can customize how your marketplace listing appears on our app through our composable interface.

2. Panel styles

2.1 panelType — what the section accepts

2.2 layout — how the row renders

2.3 Other fields

3. Card (offer) styles

4. Style recipes

Pick the section type, its layout, and the cards' design to produce each view.

Set showTitle: true, subtitle, themeColor, and bannerImageUrl on
campaigns (OCCASIONS), and bodyEn/Ar on INFO sections.

5. The flow

5.1 Listing lifecycle

stateDiagram-v2
    [*] --> DRAFT
    DRAFT --> SUBMITTED : submit listing
    CHANGES_REQUESTED --> SUBMITTED : submit listing
    REJECTED --> SUBMITTED : submit listing
    SUBMITTED --> IN_REVIEW : admin review
    IN_REVIEW --> APPROVED : admin approves
    IN_REVIEW --> CHANGES_REQUESTED : changes requested
    IN_REVIEW --> REJECTED : admin rejects
    APPROVED --> PUBLISHED : published in Super App

5.2 Panels

5.3 Cards (offers)

5.4 Worked examples

Create a HERO_CAROUSEL campaign panel via
POST .../listing/panels:

{
  "panelType": "OCCASIONS",
  "layout": "HERO_CAROUSEL",
  "titleEn": "Ramadan Specials",
  "titleAr": "عروض رمضان",
  "showTitle": true,
  "subtitleEn": "Iftar & suhoor deals, all month",
  "themeColor": "#16A34A",
  "expiresAt": "2026-09-18T21:00:00Z"
}

Create a purchasable card inside that panel via
POST .../listing/offers:

{
  "panelId": "12",
  "titleEn": "Silver top-up",
  "titleAr": "تعبئة فضية",
  "design": "tile",
  "linkType": "offer",
  "url": "",
  "price": "49.99",
  "originalPrice": "79.99",
  "currency": "SAR",
  "badgeLabel": "Best seller",
  "badgeColor": "#E8553C",
  "fulfillmentMode": "INSTANT"
}

• Omit panelId to place a card in the implicit ALL_CARDS panel; set it to
  move a card to another section (same listing).
• price is a decimal string (≤ 7 integer + 2 fraction digits). Omit it to keep
  the card non-purchasable.

6. Rules & limits

• Order: the app sorts panels[] then each panel's items[] by sortOrder
  ascending; the reorder endpoints rewrite these.
• Implicit panel: a listing always has an ALL_CARDS panel once the first
  card is authored.
• Fallbacks (client-side): unknown layout → LIST; unknown panelType →
  CARD_GRID.
• Deprecated cards[]: the customer detail API still returns a flattened
  cards[] (union of all panels[].items[]) for backward compatibility — build
  against panels[].
• Limits: max 20 panels and 20 cards per listing.
• Delete rules: a panel must be empty before deletion; a card with existing
  orders is soft-disabled (inStock=false) instead of deleted to preserve order
  history.

7. Summary

• Compose panels with the right panelType + layout, and cards with the right
  design + linkType, then reorder both to control the exact on-screen view.
• Listing content is editable only in DRAFT / CHANGES_REQUESTED / REJECTED;
  submit it for review once the storefront is final.