Import a brand's menu
const url = 'https://sandbox.partners.loops.sa/v1/brands/brd_9Lk3Vb/menu';const options = { method: 'PUT', headers: { 'Loops-Merchant-Id': 'mer_7Hq2Lw8Z', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"categories":[{"external_ref":"CAT-BURGERS","name":{"en":"Burgers","ar":"برجر"},"sort_order":1}],"modifier_groups":[{"external_ref":"MG-EXTRAS","name":{"en":"Extras","ar":"إضافات"},"min_selections":0,"max_selections":3,"options":[{"external_ref":"OPT-CHEESE","name":{"en":"Extra cheese","ar":"جبنة إضافية"},"price":{"amount":300,"currency":"SAR"}}]}],"products":[{"external_ref":"PRD-CHICKEN-BURGER","category_external_ref":"CAT-BURGERS","name":{"en":"Chicken Burger","ar":"برجر دجاج"},"calories":540,"variants":[{"external_ref":"VAR-CB-REG","name":{"en":"Regular","ar":"عادي"},"price":{"amount":2500,"currency":"SAR"}},{"external_ref":"VAR-CB-LRG","name":{"en":"Large","ar":"كبير"},"price":{"amount":3200,"currency":"SAR"}}],"modifier_group_external_refs":["MG-EXTRAS"]}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url https://sandbox.partners.loops.sa/v1/brands/brd_9Lk3Vb/menu \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'Loops-Merchant-Id: mer_7Hq2Lw8Z' \ --data '{ "categories": [ { "external_ref": "CAT-BURGERS", "name": { "en": "Burgers", "ar": "برجر" }, "sort_order": 1 } ], "modifier_groups": [ { "external_ref": "MG-EXTRAS", "name": { "en": "Extras", "ar": "إضافات" }, "min_selections": 0, "max_selections": 3, "options": [ { "external_ref": "OPT-CHEESE", "name": { "en": "Extra cheese", "ar": "جبنة إضافية" }, "price": { "amount": 300, "currency": "SAR" } } ] } ], "products": [ { "external_ref": "PRD-CHICKEN-BURGER", "category_external_ref": "CAT-BURGERS", "name": { "en": "Chicken Burger", "ar": "برجر دجاج" }, "calories": 540, "variants": [ { "external_ref": "VAR-CB-REG", "name": { "en": "Regular", "ar": "عادي" }, "price": { "amount": 2500, "currency": "SAR" } }, { "external_ref": "VAR-CB-LRG", "name": { "en": "Large", "ar": "كبير" }, "price": { "amount": 3200, "currency": "SAR" } } ], "modifier_group_external_refs": [ "MG-EXTRAS" ] } ] }'Replaces the brand’s whole menu: categories, products, variants and modifier groups,
keyed by your own external_ref values. Anything not in the request is removed from the menu.
Up to 5 MB of JSON.
Importing doesn’t change what delivery apps show. Publish the menu when you’re ready.
The import runs in the background: you get a job, and job.completed when it finishes.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The brand ID (brd_…).
Header Parameters
Section titled “Header Parameters”The merchant you are acting for (mer_…). Required for platform applications;
optional for direct integrations, which have a single merchant.
Request Bodyrequired
Section titled “Request Bodyrequired”object
object
Your own ID for this object, from your system. Unique within its type for the merchant
(for menu items, within the brand). Letters, digits, -, _, . and :.
Text in English and Arabic. Delivery apps in Saudi Arabia show both, so both are required.
object
Text in English and Arabic.
object
A set of choices, such as “Sauce” or “Extras”, that you can attach to several products.
object
Your own ID for this object, from your system. Unique within its type for the merchant
(for menu items, within the brand). Letters, digits, -, _, . and :.
Text in English and Arabic. Delivery apps in Saudi Arabia show both, so both are required.
object
0 makes the group optional; 1 or more makes it required.
Must be at least min_selections.
object
Your own ID for this object, from your system. Unique within its type for the merchant
(for menu items, within the brand). Letters, digits, -, _, . and :.
Text in English and Arabic. Delivery apps in Saudi Arabia show both, so both are required.
object
An amount in minor units (halalas for SAR), including VAT, as customers see it.
object
ISO 4217 code. Only SAR for now.
Give either price, or at least one variant; not both.
object
Your own ID for this object, from your system. Unique within its type for the merchant
(for menu items, within the brand). Letters, digits, -, _, . and :.
Text in English and Arabic. Delivery apps in Saudi Arabia show both, so both are required.
object
Text in English and Arabic.
object
Public HTTPS URL of a JPG or PNG, at least 800 × 800 px. Loops downloads and stores a copy.
Most delivery apps in Saudi Arabia require calories on menu items.
A version of a product with its own price, such as a size.
object
Your own ID for this object, from your system. Unique within its type for the merchant
(for menu items, within the brand). Letters, digits, -, _, . and :.
Text in English and Arabic. Delivery apps in Saudi Arabia show both, so both are required.
object
An amount in minor units (halalas for SAR), including VAT, as customers see it.
object
ISO 4217 code. Only SAR for now.
Modifier groups shown with this product, in this order.
false shows the product as unavailable on delivery apps.
Responses
Section titled “Responses”Import started.
object
pending and running while in progress. succeeded: everything applied.
partially_failed: some results failed (publish only). failed: nothing applied.
For a failed import, every problem found. An import is all or nothing.
object
The menu item the problem is about, if any.
For a publish, one result per location and delivery app.
object
Items the delivery app rejected, and why.
object
The menu item the problem is about, if any.
Example
{ "id": "job_01J9R2K7TN", "type": "menu_import", "status": "pending", "errors": [ { "external_ref": "PRD-CHICKEN-BURGER", "field": "image_url", "code": "image_unreachable", "message": "The image URL returned 404." } ], "results": [ { "status": "pending", "errors": [ { "external_ref": "PRD-CHICKEN-BURGER", "field": "image_url", "code": "image_unreachable", "message": "The image URL returned 404." } ] } ]}The request is invalid. errors lists each problem.
RFC 9457 Problem Details with a stable code.
object
Stable machine-readable error code. Switch on this, not on title.
For external_ref_conflict, the ID of the object that already uses the reference.
Field errors, for invalid_request.
object
Example
{ "type": "https://docs.partners.loops.sa/errors/external_ref_conflict", "title": "External reference already used", "status": 409, "code": "invalid_request", "detail": "A location with external_ref BR-01 already exists.", "request_id": "req_01J9X7P2QK", "existing_id": "loc_2Xf9K", "errors": [ { "field": "products[3].price", "message": "Required unless the product has variants." } ]}The access token is missing, expired or invalid.
RFC 9457 Problem Details with a stable code.
object
Stable machine-readable error code. Switch on this, not on title.
For external_ref_conflict, the ID of the object that already uses the reference.
Field errors, for invalid_request.
object
Example
{ "type": "https://docs.partners.loops.sa/errors/external_ref_conflict", "title": "External reference already used", "status": 409, "code": "invalid_request", "detail": "A location with external_ref BR-01 already exists.", "request_id": "req_01J9X7P2QK", "existing_id": "loc_2Xf9K", "errors": [ { "field": "products[3].price", "message": "Required unless the product has variants." } ]}Not allowed: the scope isn’t approved or granted, the connection is not active,
or your application is suspended. See code.
RFC 9457 Problem Details with a stable code.
object
Stable machine-readable error code. Switch on this, not on title.
For external_ref_conflict, the ID of the object that already uses the reference.
Field errors, for invalid_request.
object
Example
{ "type": "https://docs.partners.loops.sa/errors/external_ref_conflict", "title": "External reference already used", "status": 409, "code": "invalid_request", "detail": "A location with external_ref BR-01 already exists.", "request_id": "req_01J9X7P2QK", "existing_id": "loc_2Xf9K", "errors": [ { "field": "products[3].price", "message": "Required unless the product has variants." } ]}Not found, or not accessible with this connection.
RFC 9457 Problem Details with a stable code.
object
Stable machine-readable error code. Switch on this, not on title.
For external_ref_conflict, the ID of the object that already uses the reference.
Field errors, for invalid_request.
object
Example
{ "type": "https://docs.partners.loops.sa/errors/external_ref_conflict", "title": "External reference already used", "status": 409, "code": "invalid_request", "detail": "A location with external_ref BR-01 already exists.", "request_id": "req_01J9X7P2QK", "existing_id": "loc_2Xf9K", "errors": [ { "field": "products[3].price", "message": "Required unless the product has variants." } ]}The request conflicts with the current state, for example an external_ref already in use,
or a business profile that is in review. See code.
RFC 9457 Problem Details with a stable code.
object
Stable machine-readable error code. Switch on this, not on title.
For external_ref_conflict, the ID of the object that already uses the reference.
Field errors, for invalid_request.
object
Example
{ "type": "https://docs.partners.loops.sa/errors/external_ref_conflict", "title": "External reference already used", "status": 409, "code": "invalid_request", "detail": "A location with external_ref BR-01 already exists.", "request_id": "req_01J9X7P2QK", "existing_id": "loc_2Xf9K", "errors": [ { "field": "products[3].price", "message": "Required unless the product has variants." } ]}© 2026 Loops Technologies | شركة لووبز للتقنيات. All rights reserved.