promotions

promotions.find

Returns the promotions that meet the given conditions.

Request

Admin SDK
Admin.api('commerce.promotions.find', request, function(response) { … });
HTTP POST
/api/v6/commerce.promotions.find
{
  "conditions" : { // returns the promotions …
    "ids" : [ 281, 89, 12, … ], // … with these identifiers - int(1…)
    "isActive" : true, // … that are active or no - bool
    "type" : "DiscountedItems", // … of this type, can be "DiscountedItems", "DiscountedSubtotal" or "DiscountedShippings" - string
    "resourcesType" : "Product", // … with resources of this type (can be null), can be "Product", "Department", "Producer" or "AttributeValue" - string
    "group" : 5, // … that are also applied to this customer group (id) - int(1…255)
    "coupon" : "PROMO2017", // … with this coupon code (can be null) - string(1…32)
    "after" : 43 // … with identifier after this value - int(0…)
  },
  "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",
                        // "priority, "-priority", "type", "-type", "startTime", "-startTime", "endTime" and "-endTime" - string
  "limit" : 10, // maximum number of promotions to return - int(1…)
  "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
    "priority" : 50, // priority, 1 is higher and 100 is lower - int(1…100)
    "type" : "DiscountedItems", // type, can be "DiscountedItems", "DiscountedSubtotal" or "DiscountedShippings" - string
    "resources" : { // resources to which it is applied (can be null)
      "type" : "Product", // type of resources, can be "Product", "Department", "Producer" or "AttributeValue" - string
      "ids" : [ 287, 98, … ] // products, departments, producers or attribute values (id) - int(1…)
    },
    "shippingMethods" : [ 3, 5, … ], // shipping methods (id) (can be null) - int(1…)
    "groups" : [ 5, 7, … ], // customer groups (id) (can be null) - int(1…255)
    "coupon" : "PROMO2017", // coupon code (can be null) - string(1…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..)
    "discount" : { // discount
      "type" : "PercentOff", // discount type, can be "PercentOff", "AmountOff" or "FixedPrice" - string
      "value" : 20.000 // discount value - decimal[8,3](0…)
    },
    "startTime" : "2017-11-15", // first promotion date - date
    "endTime" : "2018-01-15", // last promotion date - date
    "combinationRule" : "Discounted", // combination rule, can be "None", "Discounted", "Subsequent" or "DiscountedAndSubsequent" - string
    "smallImage" : { // small image (can be null)
      "url" : "http://…", // URL - string(10…255)
      "width" : 200, // width in pixel - int(1…2500)
      "height" : 180 // height in pixel - int(1…2500)
    },
    "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" or "Date" - 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.

Request

Admin SDK
Admin.api('commerce.promotions.get', request, function(response) { … });
HTTP POST
/api/v6/commerce.promotions.get
{
  "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
    "priority" : 50, // priority, 1 is higher and 100 is lower - int(1…100)
    "type" : "DiscountedItems", // type, can be "DiscountedItems", "DiscountedSubtotal" or "DiscountedShippings" - string
    "resources" : { // resources to which it is applied (can be null)
      "type" : "Product", // type of resources, can be "Product", "Department", "Producer" or "AttributeValue" - string
      "ids" : [ 287, 98, … ] // products, departments, producers or attribute values (id) - int(1…)
    },
    "shippingMethods" : [ 3, 5, … ], // shipping methods (id) (can be null) - int(1…)
    "groups" : [ 5, 7, … ], // customer groups (id) (can be null) - int(1…255)
    "coupon" : "PROMO2017", // coupon code (can be null) - string(1…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..)
    "discount" : { // discount
      "type" : "PercentOff", // discount type, can be "PercentOff", "AmountOff" or "FixedPrice" - string
      "value" : 20.000 // discount value - decimal[8,3](0…)
    },
    "startTime" : "2017-11-15", // first promotion date - date
    "endTime" : "2018-01-15", // last promotion date - date
    "combinationRule" : "Discounted", // combination rule, can be "None", "Discounted", "Subsequent" or "DiscountedAndSubsequent" - string
    "smallImage" : { // small image (can be null)
      "url" : "http://…", // URL - string(10…255)
      "width" : 200, // width in pixel - int(1…2500)
      "height" : 180 // height in pixel - int(1…2500)
    },
    "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" or "Date" - 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.

Request

Admin SDK
Admin.api('commerce.promotions.count', request, function(response) { … });
HTTP POST
/api/v6/commerce.promotions.count
{
  "conditions" : { // counts only the promotions …
    "ids" : [ 281, 89, 12, … ], // … with these identifiers - int(1…)
    "isActive" : true, // … that are active or no - bool
    "type" : "DiscountedItems", // … of this type, can be "DiscountedItems", "DiscountedSubtotal" or "DiscountedShippings" - string
    "resourcesType" : "Product", // … with resources of this type (can be null), can be "Product", "Department", "Producer" or "AttributeValue" - string
    "group" : 5, // … that are also applied to this customer group (id) - int(1…255)
    "coupon" : "PROMO2017", // … with this coupon code (can be null) - string(1…32)
    "after" : 43 // … with identifier after this value - int(0…)
  }
}

Response

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

promotions.create

Creates a new promotion.

Request

Admin SDK
Admin.api('commerce.promotions.create', request, function(response) { … });
HTTP POST
/api/v6/commerce.promotions.create
{
  "promotion" : { // promotion to create (required)
    "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" : "…"
    },
    "priority" : 50, // priority, 1 is higher and 100 is lower - int(1…100)
    "type" : "DiscountedItems", // type, can be "DiscountedItems", "DiscountedSubtotal" or "DiscountedShippings" - string
    "resources" : { // resources to which it is applied (can be null)
      "type" : "Product", // type of resources, can be "Product", "Department", "Producer" or "AttributeValue" - string
      "ids" : [ 287, 98, … ] // products, departments, producers or attribute values (id) - int(1…)
    },
    "shippingMethods" : [ 3, 5, … ], // shipping methods (id) (can be null) - int(1…)
    "groups" : [ 5, 7, … ], // customer groups (id) (can be null) - int(1…255)
    "coupon" : "PROMO2017", // coupon code (can be null) - string(1…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..)
    "discount" : { // discount
      "type" : "PercentOff", // discount type, can be "PercentOff", "AmountOff" or "FixedPrice" - string
      "value" : 20.000 // discount value - decimal[8,3](0…)
    },
    "startTime" : "2017-11-15", // first promotion date - date
    "endTime" : "2018-01-15", // last promotion date - date
    "combinationRule" : "Discounted", // combination rule, can be "None", "Discounted", "Subsequent" or "DiscountedAndSubsequent" - 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" or "Date" - 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
coupon Malformed Coupon cannot start or end with spaces
discount InvalidValue Discount type cannot be 'FixedPrice' for 'DiscountSubtotal' promotions
discount InvalidValue Discount value must be less then 100 for 'PercentOff' discounts
endTime InvalidValue End time must be less than or equal to start time
groups Malformed There must be no more than 20 groups
groups NotFound Customer group <group> does not exist
promotion InvalidValue Promotions are not available for this installation
resources InvalidValue 'DiscountSubtotal' and 'DiscountShippings' promotions cannot have resources
resources Malformed There must be no more than 16.000 resources
shippingMethods Malformed There must be no more than 20 shipping methods
shippingMethods NotFound Shipping method <method> does not exist
shippingMethods InvalidValue Only 'DiscountedShippings' promotions can have shipping methods

promotions.update

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

Request

Admin SDK
Admin.api('commerce.promotions.update', request, function(response) { … });
HTTP POST
/api/v6/commerce.promotions.update
{
  "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 2017",
      "it" : "Promo 2017"
    },
    "summary" : { // summary description - string(2) -> string(0…65535)
      "en" : "…",
      "it" : "…"
    },
    "description" : { // detailed description - string(2) -> string(0…65535)
      "en" : "…",
      "it" : "…"
    },
    "priority" : 50, // priority, 1 is higher and 100 is lower - int(1…100)
    "resources" : { // resources to which it is applied (can be null)
        "type" : "Product", // type of resources, can be "Product", "Department", "Producer" or "AttributeValue" - string
        "ids" : [ 287, 98, … ] // products, departments, producers or attribute values (id) - int(1…)
    },
    "shippingMethods" : [ 3, 5, … ], // shipping methods (id) (can be null) - int(1…)
    "groups" : [ 5, 7, … ], // customer groups (id) (can be null) - int(1…255)
    "coupon" : "PROMO2017", // coupon code (can be null) - string(1…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..)
    "discount" : { // discount
      "type" : "PercentOff", // discount type, can be "PercentOff", "AmountOff" or "FixedPrice" - string
      "value" : 20.000 // discount value - decimal[8,3](0…)
    },
    "startTime" : "2017-11-15", // first promotion date - date
    "endTime" : "2018-01-15", // last promotion date - date
    "combinationRule" : "Discounted", // combination rule, can be "None", "Discounted", "Subsequent" or "DiscountedAndSubsequent" - 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" or "Date" - 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
coupon Malformed Coupon cannot start or end with spaces
discount InvalidValue Discount type cannot be 'FixedPrice' for 'DiscountSubtotal' promotions
discount InvalidValue Discount value must be less then 100 for 'PercentOff' discounts
endTime InvalidValue End time must be less than or equal to start time
id NotFound Promotion <id> does not exist
groups Malformed A customer group is repeated
groups Malformed There must be no more than 20 groups
groups NotFound Customer group <group> does not exist
largeImage Malformed File format is not a valid or supported format
largeImage Malformed Image width and height must be less than 2500 pixel
promotion InvalidValue Promotions are not available for this installation
resources InvalidValue 'DiscountSubtotal' and 'DiscountShippings' promotions cannot have resources
resources Malformed There must be no more than 16.000 resources
shippingMethods InvalidValue Only 'DiscountedShippings' promotions can have shipping methods
shippingMethods Malformed There must be no more than 20 shipping methods
shippingMethods NotFound Shipping method <method> does not exist
smallImage Malformed File format is not a valid or supported format
smallImage Malformed Image width and height must be less than 2500 pixel
startTime InvalidValue Start time must be less than or equal to end time

Notes

promotions.delete

Deletes one or more promotions.

Request

Admin SDK
Admin.api('commerce.promotions.delete', request, function(response) { … });
HTTP POST
/api/v6/commerce.promotions.delete
{
  "ids" : [ 43, 12, … ] // identifiers of the promotions to delete (required) - int(1…)
}

Response

{
  "status" : "ok"
}
`