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#
- Your system → Let's PizzaSends the menu or its changes
POST /partner/v1/catalog/imports - Let's PizzaMaps codes, checks and compares (draft)
- Let's Pizza → Your systemImport result and issues
- Let's PizzaPublished by hand or automatically, per policy
- Let's Pizza → CustomerSite and app show the new menu
Who owns what#
| Data | Source of truth |
|---|---|
| Item, names, prices, sizes, options and their rules | Your system (the fields it owns) |
| Pictures, display order, sections, tags, marketing offers | Let's Pizza console |
| The pizza builder’s art and rules | Let's Pizza console |
| Branches, hours, delivery zones and fees | Let'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.publish | What happens |
|---|---|
manual | The menu becomes a draft a person reviews and publishes in the console. |
auto_prices | Price-only changes within maxPriceChangePct publish by themselves; anything else waits for review. |
auto | Published 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.
status | Meaning | Reasons |
|---|---|---|
rejected | The checks failed; nothing changed. Fix issues and send again. | CHECKS_FAILED |
staged | Kept, waiting for review by Let’s Pizza staff. | REVIEW_REQUIREDNOT_PRICE_ONLYPRICE_CHANGE_TOO_LARGETOO_MANY_REMOVALS |
published | Published; customers see it now (or there was nothing to change). | NO_CHANGE or none |
discarded | Discarded by Let’s Pizza staff at review. | — |
superseded | Replaced 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.
{
"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/mappingsis all or nothing: one bad row refuses the whole request with422 MAPPINGS_REFUSEDand 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.mergeadds and replaces the rows sent;replacealso removes the mappings of the kinds sent that are not listed;dryRunchecks and counts only.- An order whose branch, products or options are not mapped still reaches you; what is missing is listed in
external.unmapped.
{
"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.
- GET
/partner/v1/catalogThe published menu with your codescatalog:readAvailable - POST
/partner/v1/catalog/importsSend the menu from your systemcatalog:writeAvailable - GET
/partner/v1/catalog/importsYour last menuscatalog:writeAvailable - GET
/partner/v1/catalog/imports/{id}One import reportcatalog:writeAvailable - GET
/partner/v1/mappingsYour codes for our idscatalog:readAvailable - PUT
/partner/v1/mappingsThe code mappingsmappings:writeAvailable - GET
/partner/v1/branchesYour branches and your codesbranches:readAvailable