promotion.create

This method is used to create a Promotion.

Version

v2

Arguments

This method has the path /promotion/<version>/promotion.create and follows the MicroBase API calling conventions.

Argument Required Type Example Description
title yes String 3 at 10€ Promotion Promotion title.
class yes String default Implementation class. 'default' is the one provided by microbase.
active yes Boolean true Active or disabled.
priority yes Number 100 Priority number to evaluate the promotions.
if yes JSON { category: { id:'By-4rrmsN', quantity: 3, lowestPrice: true } } DSL os the Promotion rules
then yes JSON { category: {id: 'By-4rrmsN', 'quantity': 3, discount: {rate: 10, isFixedPrice: true } } } DSL of the Promotion consequences.

The "if" and "then" fields

The "if" and "then" fields are part of a DSL (Domain Specification Language) based on JSON.

The "if" field

The if field determines if the Promotion will be fired or not. It contains one (and only one) of this objects:

  • category
  • product
  • all
  • any

The "category" rule

The category rule defines a Category and the quantity of products that needs to be present in the Cart to fire the promotion.

Field Required Type Example Description
id yes String By-4rrmsN The Category ID.
quantity yes Number 3 The needed quantity.
threshold no Number 0.3 Number betweem 0 and 1 to determine the how close is this item to fire a promotion. Default: (promotionQuantity - 1) / promotionQuantity.
lowestPrice no Boolean true If several products present on the cart belongs to this category, select the one with the lowest price.
{
  "category" : {
    "id" : "By-4rrmsN", 
    "quantity" : 3, 
    "lowestPrice" : true
  }
}

The "product" rule

The product rule defines a Product and the quantity of the Product that needs to be present in the Cart to fire the promotion.

Field Required Type Example Description
id yes String By-4rrmsN The Category ID.
quantity yes Number 3 The needed quantity.
threshold no Number 0.3 Number betweem 0 and 1 to determine the how close is this item to fire a promotion. Default: (promotionQuantity - 1) / promotionQuantity.
{
  "product" : {
      "id" : "SksexGRPn4", 
      "quantity" : 2, 
      "threshold" : 0.3
  }
}

The "all" rule

The all rule is an array of any number of this rules:

  • category
  • product
  • all
  • any

All the rules in the array must be fullfilled to fire the promotion.

{
  "all" : [
    {
      "product" : {
        "id" : "SksexGRPn4", 
        "quantity" : 3, 
        "threshold" : 0.3
      }
    }, 
    {
      "category" : {
        "id" : "By-4rrmsN", 
        "quantity" : 2, 
        "lowestPrice" : true
      }
    }
  ]
}

The "any" rule

The any rule is an array of any number of this rules:

  • category
  • product
  • all
  • any

If any of the rules in the array is fullfilled the promotion is fired.

{
  "any" : [
    {
      "product" : {
        "id" : "SksexGRPn4", 
        "quantity" : 3
      }
    }, 
    {
      "product" : {
        "id" : "aNser15F", 
        "quantity" : 2
      }
    }
  ]
}

The "then" field

The then field determines the discounts to be applied once it's fired (the if are true). It contains one (and only one) of this objects:

  • category
  • product
  • all
  • any

The "category" rule

The category rule defines a Category and the quantity of products in that Category that will be discounted.

Field Required Type Example Description
id yes String By-4rrmsN The Category ID.
quantity yes Number 1 The quantity of products to be discounted.
discount yes JSON { rate: 10, isPercentage: true } The discount to be applied

The discount object

Field Required Type Example Description
rate yes Number 10 The number to use in the discount.
isPercentage no Boolean true The rate is a percentaje number, ie: 10%
isFixedPrice no Boolean true The rate is the final price of the product, ie: 10€

If none of isPercentage or isFixedPrice are present, the rate is an ammount to discount, ie: -10€

{
  "category" : {
    "id" : "By-4rrmsN", 
    "quantity" : 1, 
    "discount" : {
      "rate" : 10, 
      "isPercentage" : true
    }
  }
}

The "product" rule

The product rule defines a Product and the quantity of this Product that will be discounted.

Field Required Type Example Description
id yes String SksexGRPn4 The Product ID.
quantity yes Number 1 The quantity of products to be discounted.
discount yes JSON { rate: 10, isPercentage: true } The discount to be applied

The "discount" object

Field Required Type Example Description
rate yes Number 10 The number to use in the discount.
isPercentage no Boolean true The rate is a percentaje number, ie: 10%
isFixedPrice no Boolean true The rate is the final price of the product, ie: 10€

If none of isPercentage or isFixedPrice are present, the rate is an ammount to discount, ie: -10€

{
  "product" : {
    "id" : "SksexGRPn4", 
    "quantity" : 1, 
    "discount" : {
      "rate" : 10, 
      "isPercentage" : true
    }
  }
}

The "all" rule

The all rule is an array of any number of this rules:

  • category
  • product
  • all
  • any

All the rules in the array will applied as discounts.

{
  "all" : [
    {
      "product" : {
        "id" : "SksexGRPn4", 
        "quantity" : 1, 
        "discount" : {
          "rate" : 10, 
          "isPercentage" : true
        }
      }
    }, 
    {
      "category" : {
        "id" : "By-4rrmsN", 
        "quantity" : 1, 
        "discount" : {
          "rate" : 10, 
          "isPercentage" : true
        }
      }
    }
  ]
}

The "any" rule

The any rule is an array of any number of this rules:

  • category
  • product
  • all
  • any

Only the first of the rules will be appiad as discount.

{
  "any" : [
    {
      "product" : {
        "id" : "SksexGRPn4", 
        "quantity" : 1, 
        "discount" : {
          "rate" : 10, 
          "isPercentage" : true
        }
      }
    }, 
    {
      "product" : {
        "id" : "aNser15F", 
        "quantity" : 1, 
        "discount" : {
          "rate" : 10, 
          "isPercentage" : true
        }
      }
    }
  ]
}

Response

Returns a Promotion object:

{
  "ok": true,
  "promotion":  { 
    "id" : "ryUGgm44", 
    "title" : "3 at 10€ Promotion", 
    "class" : "default", 
    "active" : false, 
    "priority" : 100, 
    "if" : {
      "category" : {
        "id" : "By-4rrmsN", 
        "quantity" : 3, 
        "lowestPrice" : true
      }
    }, 
    "then" : {
      "category" : {
        "id" : "By-4rrmsN", 
        "quantity" : 3, 
        "discount" : {
          "rate" : 10, 
          "isFixedPrice" : true
        }
      }
    }
  }
}

Errors

Expected errors that this method could return. Some errors return additional data.

Error Data Description
validation_error The data causing the error Some validation error

Example

curl --request POST \
  --url http://localhost:3000/services/promotion/v1/promotion.create \
  --header 'authorization: Bearer xxxxx...' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{ "ok": true, \
            "promotion":  { \ 
              "id" : "ryUGgm44", \ 
              "title" : "3 at 10€ Promotion", \ 
              "class" : "default", \ 
              "active" : false, \
              "priority" : 100, \
              "if" : { "category" : { "id" : "By-4rrmsN", "quantity" : 3, "lowestPrice" : true } }, \ 
              "then" : { "category" : { "id" : "By-4rrmsN", "quantity" : 3, "discount" : { "rate" : 1000, "isFixedPrice" : true } } } \
          } }'

Events

A Promotion creation fires a CREATE event in the PROMOTIONS channel.

Payload

Property Description
new The new Promotion created
data The request data used to crate the Promotion