External promotions are promotions that are created and operate in an external system (your website, point-of-sale terminals, mobile app, and so on), but which Maestra still needs to account for in the overall promotion arbitrage.
You can’t create or change the logic of an external promotion from the Maestra admin panel. However, when your loyalty program is active in Maestra, you can configure how an external promotion combines with other promotions — up to and including fully cancelling the external promotion (provided the cash register, website, or other channel runs arbitrage on Maestra’s side).
External promotions can apply a discount either to the entire order or to a specific purchase (a receipt line). The promotion’s conditions are configured on the cash register, website, or app side, and are sent to Maestra in the format: promotion ID + discount amount.
Because the discount amount on an external promotion can be 0, external promotions are often used as markers during receipt calculation. For example, an external promotion called “cash payment to courier” indicates that the customer chose cash on delivery and therefore shouldn’t receive the additional 5% discount that’s normally applied for online payment.
An external promotion must be sent to Maestra via API in advance so that it appears in the promotion tree. There are two ways to do this:
- Import promotions as a list (bulk import).
- Add them one at a time through an operation.
Once added, the promotion appears in the promotion tree under the “External promotions” group. From there you can move it to any other group in the tree with the application rules you need.
If you want to rename a promotion, click its name in the promotion tree, then click the pencil icon on the page that opens.
If you don’t import an external promotion via API ahead of time and instead pass it directly in the order creation or order calculation operation, the promotion won’t be added to the promotion tree. Instead, it will appear on the “External promotions outside processing” page.
External promotions that haven’t been added to Maestra in advance still participate in discount calculations and are processed by the arbitrage engine using the application rules of the “External promotions” group.
Manual discount applied at the register
Example: a customer is buying a product at the register, but the item rings up at a different price because the price tag wasn’t updated. The cashier can apply a manual discount on the product so the price matches the tag. When this is transmitted to Maestra, you’ll see the product’s base price along with the discount the cashier applied.
Automatic discount driven by register logic
Example: at certain hours, a bakery runs a promotion that gives a 50% discount on specific products based on their shelf life. Because the list of eligible products changes every day, it’s inconvenient to set up these promotions on the Maestra side. The easiest approach is to pass the discount to Maestra as an external promotion tagged “Automatic discount at register.” 
