promotions

promotions.find

Returns the promotions that meet the given conditions.

JS
CR.api('commerce.promotions.find', request, function(response) { … });
HTTP
POST /open2b/api/v3/commerce.promotions.find

request

{
  "conditions" : { // returns the promotions …
    "isActive" : true, // … that are active or no - bool
    "appliedTo" : "Carts", // … applied to this, can be "Products", "Departments", "Producers" or "Carts" - string
    "coupon" : "PROMO2016" // … with this coupon code - string(0…32)
  },
  "language" : "en", // language ( ISO code ) of the texts to return - string(2)
  "fields" : [ "id", "name", … ], // fields to return - string
  "order" : [ "name" ], // sort order of returned promotions, can contain "id", "-id", "name", "-name", "isActive", "-isActive",
                        // "appliedTo", "-appliedTo", "startTime", "-startTime", "endTime" and "-endTime" - string
  "limit" : 10, // maximum number of promotions to return - int(1…100)
  "first" : 0 // index of the first promotion to return - int(0…)
}

response

{
  "status" : "ok",
  "promotions" : [ {
    "id" : 43, // identifier - int(1…)
    "name" : { // name - string(2) -> string(0…60)
     "en" : "Promo 2017",
     "it" : "Promo 2017"
    },
    "summary" : { // summary description - string(2) -> string(0…65535)
      "en" : "…",
      "it" : "…"
    },
    "description" : { // detailed description - string(2) -> string(0…65535)
      "en" : "…",
      "it" : "…"
    },
    "isActive" : true, // indicates if it is active or not - bool
    "type" : "PercentDiscount", // type, can be "FixedDiscount", "PercentDiscount" or "FixedPrice" - string
    "appliedTo" : "Products", // indicates to what it is applied, can be "Products", "Departments", "Producers" or "Carts" - string
    "elements" : [ 287, 98, … ], // products, departments or producers (id) to which it is applied - int(1…)
    "coupon" : "PROMO2013", // coupon code - string(0…32)
    "minSubtotal" : 50.00, // minimum cart subtotal (can be null) - decimal[8,2](0..)
    "maxSubtotal" : null, // maximum cart subtotal, can not be zero (can be null) - decimal[8,2](0..)
    "discountAmount" : 0.000, // discount amount on list price - decimal[8,3](0…)
    "discountPercent" : 25.000, // percent discount on list price - decimal[5,3](0…)
    "startTime" : "2016-01-09", // first promotion date - date
    "endTime" : "2016-05-30", // last promotion date - date
    "smallImage" : { // small image (can be null)
      "url" : "http://…", // URL - string(10…255)
      "width" : 200, // width in pixel - int(1…255)
      "height" : 180 // height in pixel - int(1…255)
    },
    "largeImage" : { // large image (can be null)
      "url" : "http://…", // URL - string(10…255)
      "width" : 800, // width in pixel - int(1…2500)
      "height" : 960 // height in pixel - int(1…2500)
    },
    "productsLayout" : { // products layout on the promotion page
      "products" : 12, // number of products per page, can be 0, 12, 24, 36, 48 or 72 - int
      "columns" : 4, // columns, can be 1, 2, 3, 4 or 6 - int
      "sortOrder" : "-Price", // sort order, can be "Position", "Name", "-Name", "Price", "-Price" - string
      "imageSize" : "Optimal", // image size, can be "Optimal", Small", "Medium" or "Large" - string
      "showDescription" : false // indicates if the description is displayed - bool
    },
    "seoTitle" : { // title for SEO - string(2) -> string(0…255)
      "en" : "",
      "it" : ""
    },
    "seoKeywords" : { // keywords for SEO - string(2) -> string(0…255)
      "en" : "",
      "it" : ""
    },
    "seoDescription" : { // description for SEO - string(2) -> string(0…255)
      "en" : "",
      "it" : ""
    },
    "canonicalURL" : { // canonical URL - string(2) -> string(10…)
      "en" : "https://www.site.com/Promo-2017",
      "it" : "https://www.site.com/it/Promo-2017",
      …    
    }
  }, … ]
}

promotions.get

Returns a promotion given its identifier.

JS
CR.api('commerce.promotions.get', request, function(response) { … });
HTTP
POST /open2b/api/v3/commerce.promotions.get

request

{
  "id" : 43, // identifier (required) - int(1…)
  "language" : "en", // language ( ISO code ) of the texts to return - string(2)
  "fields" : [ "id", "name", "summary", … ] // fields to return - string
}

response

{
  "status" : "ok",
  "promotion" : { // (can be null)
    "id" : 43, // identifier - int(1…)
    "name" : { // name - string(2) -> string(0…60)
     "en" : "Promo 2017",
     "it" : "Promo 2017"
    },
    "summary" : { // summary description - string(2) -> string(0…65535)
      "en" : "…",
      "it" : "…"
    },
    "description" : { // detailed description - string(2) -> string(0…65535)
      "en" : "…",
      "it" : "…"
    },
    "isActive" : true, // indicates if it is active or not - bool
    "type" : "PercentDiscount", // type, can be "FixedDiscount", "PercentDiscount" or "FixedPrice" - string
    "appliedTo" : "Products", // indicates to what it is applied, can be "Products", "Departments", "Producers" or "Carts" - string
    "elements" : [ 287, 98, … ], // products, departments or producers (id) to which it is applied - int(1…)
    "coupon" : "PROMO2013", // coupon code - string(0…32)
    "minSubtotal" : 50.00, // minimum cart subtotal (can be null) - decimal[8,2](0..)
    "maxSubtotal" : null, // maximum cart subtotal, can not be zero (can be null) - decimal[8,2](0..)
    "discountAmount" : 0.000, // discount amount on list price - decimal[8,3](0…)
    "discountPercent" : 25.000, // percent discount on list price - decimal[5,3](0…)
    "startTime" : "2016-01-09", // first promotion date - date
    "endTime" : "2016-05-30", // last promotion date - date
    "smallImage" : { // small image (can be null)
      "url" : "http://…", // URL - string(10…255)
      "width" : 200, // width in pixel - int(1…255)
      "height" : 180 // height in pixel - int(1…255)
    },
    "largeImage" : { // large image (can be null)
      "url" : "http://…", // URL - string(10…255)
      "width" : 800, // width in pixel - int(1…2500)
      "height" : 960 // height in pixel - int(1…2500)
    },
    "productsLayout" : { // products layout on the promotion page
      "products" : 12, // number of products per page, can be 0, 12, 24, 36, 48 or 72 - int
      "columns" : 4, // columns, can be 1, 2, 3, 4 or 6 - int
      "sortOrder" : "-Price", // sort order, can be "Position", "Name", "-Name", "Price", "-Price" - string
      "imageSize" : "Optimal", // image size, can be "Optimal", Small", "Medium" or "Large" - string
      "showDescription" : false // indicates if the description is displayed - bool
    },
    "seoTitle" : { // title for SEO - string(2) -> string(0…255)
      "en" : "",
      "it" : ""
    },
    "seoKeywords" : { // keywords for SEO - string(2) -> string(0…255)
      "en" : "",
      "it" : ""
    },
    "seoDescription" : { // description for SEO - string(2) -> string(0…255)
      "en" : "",
      "it" : ""
    },
    "canonicalURL" : { // canonical URL - string(2) -> string(10…)
      "en" : "https://www.site.com/Promo-2017",
      "it" : "https://www.site.com/it/Promo-2017",
      …    
    }
  }
}

promotions.count

Number of promotions that meet the given conditions.

JS
CR.api('commerce.promotions.count', request, function(response) { … });
HTTP
POST /open2b/api/v3/commerce.promotions.count

request

{
  "conditions" : { // counts only the promotions …
    "isActive" : true, // … that are active or no - bool
    "appliedTo" : "Carts", // … applied at this, can be "Products", "Departments", "Producers" or "Carts"
    "coupon" : "PROMO2016" // … with this coupon code - string(0…32)
  }
}

response

{
  "status" : "ok",
  "count" : 7 // number of promotions - int(0…)
}

promotions.create

Creates a new promotion.

JS
CR.api('commerce.promotions.create', request, function(response) { … });
HTTP
POST /open2b/api/v3/commerce.promotions.create

request

{
  "promotion" : { // promotion to create (required)
    "name" : { // name - string(2) -> string(0…60)
     "en" : "Promo 2016",
     "it" : "Promo 2016"
    },
    "summary" : { // summary description - string(2) -> string(0…65535)
      "en" : "…",
      "it" : "…"
    },
    "description" : { // detailed description - string(2) -> string(0…65535)
      "en" : "…",
      "it" : "…"
    },
    "type" : "PercentDiscount", // type, can be "FixedDiscount", "PercentDiscount" or "FixedPrice" (required) - string
    "appliedTo" : "Products", // indicates at what it is applied, can be "Products", "Departments", "Producers" or "Carts" (required) - string
    "elements" : [ 287, 98, … ], // products, departments or producers (id) to which it is applied - int(1…)
    "coupon" : "PROMO2016", // coupon code - string(0…32)
    "minSubtotal" : 50.00, // minimum cart subtotal (can be null) - decimal[8,2](0..)
    "maxSubtotal" : null, // maximum cart subtotal, can not be zero (can be null) - decimal[8,2](0..)
    "discountAmount" : 0.000, // discount amount on list price - decimal[8,3](0…)
    "discountPercent" : 25.000, // percent discount on list price - decimal[5,3](0…)
    "startTime" : "2016-01-09", // first promotion date - date
    "endTime" : "2016-05-30", // last promotion date - date
    "productsLayout" : { // products layout on the promotion page
      "products" : 12, // number of products per page, can be 0, 12, 24, 36, 48 or 72 - int
      "columns" : 4, // columns, can be 1, 2, 3, 4 or 6 - int
      "sortOrder" : "-Price", // sort order, can be "Position", "Name", "-Name", "Price", "-Price" - string
      "imageSize" : "Optimal", // image size, can be "Optimal", Small", "Medium" or "Large" - string
      "showDescription" : false // indicates if the description is displayed - bool
    },
    "seoTitle" : { // title for SEO - string(2) -> string(0…255)
      "en" : "",
      "it" : ""
    },
    "seoKeywords" : { // keywords for SEO - string(2) -> string(0…255)
      "en" : "",
      "it" : ""
    },
    "seoDescription" : { // description for SEO - string(2) -> string(0…255)
      "en" : "",
      "it" : ""
    }
  }
}

response

{
  "status" : "ok",
  "id" : 43 // identifier of the new promotion - int(1…)
}

Errors

Field Type Description
elements InvalidValue Carts promotions can not have elements
maxSubtotal InvalidValue Only Carts promotions can have a maximum subtotal
minSubtotal InvalidValue Only Carts promotions can have a minimum subtotal
type InvalidValue Carts promotions can not have a FixedPrice type

promotions.update

Updates a promotion. Any fields left out of the request will remain unchanged.

JS
CR.api('commerce.promotions.update', request, function(response) { … });
HTTP
POST /open2b/api/v3/commerce.promotions.update

request

{
  "id" : 43, // identifier of the promotion to update (required)
  "promotion" : { // promotion's fields to update (required)
    "name" : { // name - string(2) -> string(0…60)
     "en" : "Promo 2011",
     "it" : "Promo 2011"
    },
    "summary" : { // summary description - string(2) -> string(0…65535)
      "en" : "…",
      "it" : "…"
    },
    "description" : { // detailed description - string(2) -> string(0…65535)
      "en" : "…",
      "it" : "…"
    },
    "type" : "PercentDiscount", // type, can be "FixedDiscount", "PercentDiscount" or "FixedPrice" - string
    "elements" : [ 287, 98, … ], // products, departments or producers (id) to which it is applied - int(1…)
    "coupon" : "PROMO2016", // coupon code - string(0…32)
    "minSubtotal" : 50.00, // minimum cart subtotal (can be null) - decimal[8,2](0..)
    "maxSubtotal" : null, // maximum cart subtotal, can not be zero (can be null) - decimal[8,2](0..)
    "discountAmount" : 0.000, // discount amount on list price - decimal[8,3](0…)
    "discountPercent" : 25.000, // percent discount on list price - decimal[5,3](0…)
    "startTime" : "2016-01-09", // first promotion date - date
    "endTime" : "2016-05-30", // last promotion date - date
    "smallImage" : { // small image (can be null)
      "content" : "N3R…zaA==" // content encoded in base64 - string
    },
    "largeImage" : { // large image (can be null)
      "content" : "N3R…zaA==" // content encoded in base64 - string
    },
    "productsLayout" : { // products layout on the promotion page
      "products" : 12, // number of products per page, can be 0, 12, 24, 36, 48 or 72 - int
      "columns" : 4, // columns, can be 1, 2, 3, 4 or 6 - int
      "sortOrder" : "-Price", // sort order, can be "Position", "Name", "-Name", "Price", "-Price" - string
      "imageSize" : "Optimal", // image size, can be "Optimal", Small", "Medium" or "Large" - string
      "showDescription" : false // indicates if the description is displayed - bool
    },
    "seoTitle" : { // title for SEO - string(2) -> string(0…255)
      "en" : "",
      "it" : ""
    },
    "seoKeywords" : { // keywords for SEO - string(2) -> string(0…255)
      "en" : "",
      "it" : ""
    },
    "seoDescription" : { // description for SEO - string(2) -> string(0…255)
      "en" : "",
      "it" : ""
    }
  }
}

response

{
  "status" : "ok"
}

Errors

Field Type Description
id NotFound Promotion <id> does not exist
elements InvalidValue Carts promotions can not have elements
largeImage Malformed Image width and height must be less than 2500 pixels
largeImage Malformed File format is not a valid or supported format
maxSubtotal InvalidValue Only Carts promotions can have a maximum subtotal
minSubtotal InvalidValue Only Carts promotions can have a minimum subtotal
smallImage Malformed Image width and height must be less than 2500 pixels
smallImage Malformed File format is not a valid or supported format
type InvalidValue Carts promotions can not have a FixedPrice type

Notes

promotions.delete

Deletes one or more promotions.

JS
CR.api('commerce.promotions.delete', request, function(response) { … });
HTTP
POST /open2b/api/v3/commerce.promotions.delete

request

{
  "ids" : [ 43, 12, … ] // identifiers of the promotions to delete (required) - int(1…)
}

response

{
  "status" : "ok"
}