Let's Pizza Developersv1.0.0

Guides

Menu from your ERP

A product and its price are typed once, in your system. We import them, compare them with what customers see, and publish per the agreed policy.

The flow#

  1. Your system → Let's PizzaSends the menu or its changesPOST /partner/v1/catalog/imports
  2. Let's PizzaMaps codes, checks and compares (draft)
  3. Let's Pizza → Your systemImport result and issues
  4. Let's PizzaPublished by hand or automatically, per policy
  5. Let's Pizza → CustomerSite and app show the new menu

Who owns what#

DataSource of truth
Item, names, prices, sizes, options and their rulesYour system (the fields it owns)
Pictures, display order, sections, tags, marketing offersLet's Pizza console
The pizza builder’s art and rulesLet's Pizza console
Branches, hours, delivery zones and feesLet's Pizza console

The fields your system can own: names · descriptions · prices · sizes · groups · options · categories · availability. Yours are in settings.catalog.fields.

Publishing#

settings.catalog.publishWhat happens
manualThe menu becomes a draft a person reviews and publishes in the console.
auto_pricesPrice-only changes within maxPriceChangePct publish by themselves; anything else waits for review.
autoPublished when the checks pass and no more than maxRemovals items disappear.

The import report#

Every send returns a report (CatalogImport): its status and reason, counts, unmapped codes (unknown), what was taken off, the checks (issues) and the difference from what customers see (diff). Send the whole menu (full) or changes only (delta); dryRun returns the report without keeping anything.

statusMeaningReasons
rejectedThe checks failed; nothing changed. Fix issues and send again.CHECKS_FAILED
stagedKept, waiting for review by Let’s Pizza staff.REVIEW_REQUIREDNOT_PRICE_ONLYPRICE_CHANGE_TOO_LARGETOO_MANY_REMOVALS
publishedPublished; customers see it now (or there was nothing to change).NO_CHANGE or none
discardedDiscarded by Let’s Pizza staff at review.—
supersededReplaced by a newer menu you sent before it was reviewed.—

On a dry run the reason starts with DRY_RUN. If your settings do not make you the menu source the answer is 403 CATALOG_SOURCE_REQUIRED.

  • Only the fields settings.catalog.fields gives you change. Pictures, the pizza builder, display order and sections stay with Let’s Pizza.
  • A blocked item, and in a full menu a mapped item you no longer list, is taken off at your live branches, never deleted.
POST /partner/v1/catalog/imports · PartnerMenu
{
  "mode": "full",
  "dryRun": true,
  "categories": [
    {
      "code": "string",
      "nameAr": "string",
      "nameEn": "string",
      "sortOrder": 0,
      "blocked": true
    }
  ],
  "items": [
    {
      "code": "string",
      "nameAr": "string",
      "nameEn": "string",
      "descriptionAr": "string",
      "descriptionEn": "string",
      "categoryCode": "string",
      "price": 0,
      "variants": [
        {
          "code": "string",
          "price": 0,
          "blocked": true
        }
      ],
      "groupCodes": [
        "string"
      ],
      "blocked": true
    }
  ],
  "groups": [
    {
      "code": "string",
      "nameAr": "string",
      "nameEn": "string",
      "minSelect": 0,
      "maxSelect": 1,
      "maxPerOption": 1,
      "options": [
        {
          "code": "string",
          "nameAr": "string",
          "nameEn": "string",
          "price": 0,
          "pricesBySize": {
            "medium": 0,
            "large": 0
          },
          "blocked": true
        }
      ]
    }
  ]
}

Mapping your codes#

Neither side changes its ids. Each of our branches, categories, products, groups, options and tenders is linked to your code in a mapping per environment.

  • PUT /partner/v1/mappings is all or nothing: one bad row refuses the whole request with 422 MAPPINGS_REFUSED and nothing changes. detail.errors[] lists each bad row: its index, the code (UNKNOWN_ID, DUPLICATE_ROW or CODE_TAKEN), the field and the value. This refusal is not kept as the Idempotency-Key answer, so the corrected request may reuse the key.
  • merge adds and replaces the rows sent; replace also removes the mappings of the kinds sent that are not listed; dryRun checks and counts only.
  • An order whose branch, products or options are not mapped still reaches you; what is missing is listed in external.unmapped.
422 · PartnerError
{
  "code": "MAPPINGS_REFUSED",
  "message": {
    "ar": "رُفض طلب الربط كاملاً ولم يتغيّر شيء: راجع detail.errors.",
    "en": "The mapping request was refused whole and nothing changed: see detail.errors."
  },
  "field": null,
  "retryable": false,
  "requestId": "req_01JD7Q8W3K2M",
  "detail": {
    "errors": [
      {
        "index": 3,
        "code": "UNKNOWN_ID",
        "field": "id",
        "value": "99999"
      }
    ]
  }
}

Endpoints used#

Anything marked “Coming soon” is not served yet; it joins the reference as soon as it ships.