xml

Method Description

Invoked with a POST request. Operation name is set up via Maestra framework.

When 'Place Order' is clicked or before the receipt is printed at the retail store, the service verifies current availability of customer discounts and redeems the discounts customer intends to use (promo codes, gift cards, points). The service can return a validation error that should be presented to the customer.

If the order price was updated since the order precalculation service was called (for example, a promotion has ended), the service returns 409 Conflict. In this case, call order precalculation service again to recalculate prices.

Upon success, order placement service blocks promo codes, gift cards, and bonus points used in customer’s order. They will stay blocked until confirmation or cancellation occurs.

Upon success, the service returns internal Maestra order ID. Make sure to save it for potential order update calls at a later time. Site (or cash desk) can store the order in its database only if the service call ended successfully.

POST https://api.maestra.io/v3/operations/{sync/async}?endpointId={API endpoint ID}&operation={operation name}

Accept: application/xml
Content-Type: application/xml
Authorization: SecretKey {Secret Key}

<order>
  <pointOfContact>{site/store/kiosk ID}</pointOfContact>
  <area>{area ID, if promotions and discounts vary by region}</area>
  <createdDateTimeUtc>{order creation date and time}</createdDateTimeUtc>
  <customer>
    <email>{customer email}</email>
    <mobilePhone>{customer mobile}</mobilePhone>
    <ids>
      <webSiteUserId>{customer ID}</webSiteUserId>
    </ids>
    <isAuthorized>{true/false, relevant for website. Use false for anonymous orders}</isAuthorized>
  </customer>
  <lines>
    <line>
      <sku>
        <productId>{product ID}</productId>
        <basePricePerItem>{base price per item}</basePricePerItem>
      </sku>
      <quantity>{product item quantity}</quantity>
      <customFields>
        <custom line field>{custom field value}</custom line field>
      </customFields>      <giftCard>
        <id>{number of card being purchased}</id>
        <getFromPool>{get card number from pool}</getFromPool>
      </giftCard>
    </line>
  </lines>
  <discounts>
    <discount>
      <type>balance</type>
      <amount>{points to be spent by customer}</amount>
    </discount>
    <discount>
      <type>promoCode</type>
      <id>{promo code value}</id>
      <amount>{discount amount}</amount>
    </discount>
    <discount>
      <type>externalPromoAction</type>
      <id>{promotion ID}</id>
      <amount>{external promotion discount amount}</amount>
    </discount>
  </discounts>
  <deliveryCost>{delivery cost}</deliveryCost>
  <payments>
    <payment>
      <type>giftCard</type>
      <id>{gift card ID}</id>
      <amount>{payment amount}</amount>
    </payment>
    <payment>
      <type>{payment method ID}</type>
      <amount>{payment amount}</amount>
    </payment>
  </payments>
  <preOrderDiscountedTotalPrice>{order price returned to order precalculation service}</preOrderDiscountedTotalPrice>
    </payment>
  </payments>
  <customFields>
    <custom order field>{custom field value}</custom order field>
  </customFields>
</order>

Response Description

<order>  
  <ids>
    <retailOrderId>{Order ID in Maestra}</retailOrderId>
  </ids>
  <pointOfContact>{Point of Contact ID, site/store/kiosk/etc.}</pointOfContact>
  <area>{area ID, if promotions and discounts vary by region}</area>
  <createdDateTimeUtc>{order creation date and time in UTC as yyyy-MM-dd HH:mm:ss}</createdDateTimeUtc>
  <lines>
    <line>
      <sku>
        <productId>{product ID}</productId>
        <basePricePerItem>{base price per product item}</basePricePerItem>
      </sku>
      <quantity>{product item quantity}</quantity>
      <discountedPrice>{discounted price per receipt line}</discountedPrice>
      <appliedDiscounts>
        <appliedDiscount>
          <type>promoAction</type>
          <id>{promotion ID}</id>
          <amount>{discount amount, applied to receipt line}</amount>
        </appliedDiscount>
        <appliedDiscount>
          <type>balance</type>
          <amount>{discount amount, applied to receipt line}</amount>
        </appliedDiscount>
        <appliedDiscount>
          <type>promoCode</type>
          <amount>{discount amount, applied to receipt line}</amount>
        </appliedDiscount>
        <appliedDiscount>
          <type>externalPromoAction</type>
          <id>{promotion ID}</id>
          <amount>{discount amount for external promotion}</amount>
        </appliedDiscount>
      </appliedDiscounts>
      <placeholders>
        <placeholder>
          <id>{text output placeholder ID}</id>
          <content>
            <contentItem>
              <type>text</type>
              <promoActionId>{internal promotion name, applicable to receipt line}</promoActionId>
              <value>{promotion description, applicable to receipt line}</value>
            </contentItem>
          </content>
        </placeholder>
      </placeholders>
      <giftCard>
        <id>{number of gift card being purchased}</id>
        <status>{status of gift card being purchased, NotFound/AlreadyUsed/CanBeUsed/Blocked/CannotBeUsedInCurrentOrder/Inactive}</status>
      </giftCard>
    </line>
  </lines>
  <appliedDiscounts>
    <appliedDiscount>
      <type>promoAction</type>
      <id>{promotion ID}</id>
      <amount>{discount amount, applied to order}</amount>
    </appliedDiscount>
    <appliedDiscount>
      <type>balance</type>
      <amount>{discount amount, applied to order}</amount>
    </appliedDiscount>
    <appliedDiscount>
      <type>promoCode</type>
      <amount>{discount amount, applied to order}</amount>
    </appliedDiscount>
    <appliedDiscount>
      <type>externalPromoAction</type>
      <id>{promotion ID}</id>
      <amount>{external promotion discount amount}</amount>
    </appliedDiscount>
  </appliedDiscounts>
  <discountedTotalPrice>{order price with discounts}</discountedTotalPrice>
  <payments>
    <payment>
      <type>giftCard</type>
      <id>{gift card ID}</id>
      <amount>{payment amount}</amount>
    </payment>
    <payment>
      <type>{payment method ID}</type>
      <amount>{payment amount}</amount>
    </payment>
  </payments>
  <placeholders>
    <placeholder>
      <id>{text output area ID}</id>
      <content>
        <contentItem>
          <type>text</type>
          <promoActionId>{internal promotion name, applicable to this order}</promoActionId>
          <value>{promotion description, applicable to this order}</value>
        </contentItem>
      </content>
    </placeholder>
  </placeholders>
  <discountsInfo>
    <discountInfo>
      <type>Balance</type>
      <availableAmountForCurrentOrder>{points available for this order}</availableAmountForCurrentOrder>
      <balance>
        <total>{total bonus points}</total>
        <available>{available bonus points}</available>
        <blocked>{blocked bonus points}</blocked>
      </balance>
    </discountInfo>
    <discountInfo>
      <type>promoCode</type>
      <availableAmountForCurrentOrder>{absolute amount available to discount for this order with a promo code}</availableAmountForCurrentOrder>
      <promoCode>
        <id>{promo code value}</id>
        <status>{promo code status,  CanBeUsed/Inactive/AlreadyUsed/NotFound/CanBeUsed}</status>
        <availableFromDateTimeUtc>{promo code start date and time}</availableFromDateTimeUtc>
        <availableTillDateTimeUtc>{promo code expiry date and time}</availableTillDateTimeUtc>
        <usedDateTimeUtc>{promo code used date and time}</usedDateTimeUtc>
      </promoCode>
    </discountInfo>
  </discountsInfo>
  <paymentsInfo>
    <paymentInfo>
      <type>giftCard</type>
      <availableAmountForCurrentOrder>{absolute amount from gift card, available to pay for this order}</availableAmountForCurrentOrder>
      <giftCard>
        <id>{gift card number}</id>
        <status>{card status, NotFound/AlreadyUsed/CanBeUsed/Blocked/CannotBeUsedInCurrentOrder/Inactive}</status>
        <balance>
          <total>{gift card face value}</total>
          <available>{available sum}</available>
          <used>{spent sum}</used>
        </balance>
      </giftCard>
    </paymentInfo>
  </paymentsInfo>
  <customer>
    <status>{customer status, Found/NotFound}</status>
    <email>{customer email}</email>
    <mobilePhone>{mobile phone}</mobilePhone>
    <lastName>{customer last name}</lastName>
    <firstName>{customer first name}</firstName>
    <birthDate>{date of birth as YYYY-MM-DD}</birthDate>
    <discountCards>
      <discountCard>
        <id>{discount card number}</id>
        <status>{card status}</status>
              <type>
                  <id>{card type ID}</id>
                  <percentDenomination>{card discount}</percentDenomination>
              </type>
          </discountCard>
      </discountCards>
  </customer>
  <totalAcquiredBalanceChange>{points awarded for this order}</totalAcquiredBalanceChange>
</order>