Matcha Purchase API for Matcha browser widgets

matchaPurchase.md

Documentation of Matcha Purchase API

Unified browser javascript api, to send a purchase request from a Matcha widget (Virtual wine advisor, Wine Select...) to the ecommerce website it is in.

Usage

• Write a global javascript function that calls your "add to kart" internal function, with the relevant data taken from the Matcha Purchase object.
• Transmit its name to Matcha widget via the parameter onPurchase (see the documentation of the widget you use)
• The widget will call it when a user clicks on the purchase button inside the widget

onPurchase function

Arguments

• matchaPurchaseObject: A Matcha Purchase Object

Returns

Return can be:

1. No return
2. A Matcha purchase success object (with any relevant information you can have
3. A promise, with 1. or 2. on success, and a Matcha Purchase Error on error

Throws If purchase fails synchronously, it can throws a Matcha Purchase Error

Matcha Purchase Object model

Example

{
  "id": "e957d95a-143d-400a-a4e2-899051d0be48",
  "date": "2019-03-08T17:07:36.497Z",
  "source": "matchaWineAdvisor",
  "target": "kart",
  "purchasedProducts": [
    {
      "id": "1f109146-3729-4bdc-9816-b4be67960423",
      "count": 1,
      "product": {
        "id": "cabasse-cuvee-deux-rouge-2010-bottle",
        "price": 25.45,
        "volume": 75,
        "packSize": 1
      },
      "wine": {
        "id": "1445",
        "name": "Cuvée D'Eux rouge 2010, Domaine de Cabasse, Côtes du Rhône Villages Séguret"
      }
    }
  ]
}

Matcha purchase object

Object with these properties:

• id (String): Matcha identifier of the purchase, generated when the user clicks on the purchase button
• date (Date): javascript date object, fixing time and date when the user clicks on the purchase button
• shopId (String, optional): The exact shop id given to Matcha widget
• source (String, with values in ["matchaWineAdvisor", "matchaWineSelect"]): The source widget name of the purchase
• target (String, default "kart", with values in ["kart", "purchaseList"]): The source widget of the purchase. Only relevant if you have a purchase list feature in your website
• purchasedProduct (Array of Object): The Purchased Product objects of this purchase

Matcha Purchased Product object

• id (String): Matcha identifier of the purchased product, generated when the user clicks on the purchase button
• count : Number of products purchased by the user. If packSize > 1, it's the "pack number", for example count = 2 is 12 bottles if packSize is 6)
• wine : Matcha Wine Object (ex. Pouilly fumé 2016 1/2 bouteille)
• product : Matcha Product Object of this wine that is purchased (ex. Pouilly fumé 2016 1/2 bouteille)

Matcha Wine Object

• id: Your identifier of the wine, as given in Matcha API. Or a generated one if you did not give an identifier.
• name (String): Name of the wine

Matcha Product Object

• id : Your identifier of the wine product, as given in Matcha API. Or a generated one if you did not give an identifier.
• price (Number): Price of the product as given in Matcha API
• volume (Number): Volume of the product (in cL) as given in Matcha API
• packSize (Number, default 1): Number of bottles in the product, as given in Matcha API

Matcha Purchase Success Data

On receiving a Matcha purchase, you can return a Matcha Purchase Success Data. It is an object, with data like your purchase id, and other purchase info.

Matcha Purchase Error

If the purchase fails, you can throw an error. This is a standard javascript Error, with its message as the message we will show to the user, and a data key.

• message (String, native field): Error message for user
• data (Object): Error data for Matcha (http code, error id, technical error message...)

Error declaration example:

const matchaPurchaseError = new Error("Wine out of stocks.")

const failPurchaseData = {
  ...
}
matchaPurchaseError.data = failPurchaseData

throw matchaPurchaseError

Example

<!--Purchase API script -->
<script>
    window.onMatchaPurchase = function(matchaPurchase) {
      const {id, date, source, purchasedProducts} = matchaPurchase
    
      alert(`A purchase has been sent by ${source} on ${purchasedProducts.length} products, see logs for details`)
      console.log(`[purchase id = ${id}] A purchase has been sent by ${source} on ${purchasedProducts.length} products on date ${date}`, matchaPurchase)
    
      purchasedProducts.forEach(purchasedProduct => {
        const {count, product, wine} = purchasedProduct
        const {name} = wine
        const {volume, price} = product
    
        console.log(`[wine id = ${wine.id}][product id = ${product.id}] ${count} items of wine ${name} (volume ${volume}cL, price ${price}€)`)
      })
    }
</script>

<!--Matcha widget declaration -->
<script
    src="..."
    onPurchase="onMatchaPurchase"
    ...
></script>