Vai alla vecchia documentazione
Open2b versione 7.5

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/v10/commerce.promotions.find
{
  "conditions" : { // returns the promotions …
    "ids" : [ 281, 89, 12, … ], // … with these identifiers - int(1…)
    "isActive" : true, // … that are active or no - bool
    "inActivityRange" : true, // … for which current time is between promotion's startTime and endTime -- 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" : "PROMO2020", // … 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 2020",
      "it" : "Promo 2020"
    },
    "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
    "inActivityRange" : true, // indicates if current time is between promotion's startTime and endTime -- 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…)
    },
    "discountedQuantity" : { // quantity that will be discounted (can be null)
      "quantity" : 4, // quantity of discounted items - int(1..)
      "excludeMinQuantity" : false // indicates if the minimum quantity is excluded from the discount - bool
    },
    "shippingMethods" : [ 3, 5, … ], // shipping methods (id) (can be null) - int(1…)
    "groups" : [ 5, 7, … ], // customer groups (id) (can be null) - int(1…255)
    "coupon" : "PROMO2020", // 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..)
    "minQuantity" : { // minimum quantity to purchase (can be null)
      "quantity" : 4, // minimum quantity of items in the cart - int(0..)
      "groupBy" : "Item" // how to group purchased quantity. Can be "Item", "Product" or "Cart" - string
    },
    "discount" : { // discount
      "type" : "PercentOff", // discount type, can be "PercentOff", "AmountOff" or "FixedPrice" - string
      "value" : 20.000 // discount value - decimal[8,3](0…)
    },
    "startTime" : "2020-11-15 12:00:00", // first promotion date and time - datetime
    "endTime" : "2020-01-15 12:00:00", // last promotion date and time - datetime
    "hourLimits" : { // Hours during which the promotion is active (can be null)
      "start" : 12, // Hour of promotion activation - int(0..23)
      "end" : 18 // Hour of promotion deactivation - int(0..23)
    }, 
    "combinationRule" : "Discounted", // combination rule, can be "None", "Discounted", "Subsequent" or "DiscountedAndSubsequent" - string
    "smallImage" : { // small image (can be null)
      "url" : "https://…", // 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" : "https://…", // 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" : ""
    },
    "seoDescription" : { // description for SEO - string(2) -> string(0…255)
      "en" : "",
      "it" : ""
    },
    "canonicalURL" : { // canonical URL - string(2) -> string(10…)
      "en" : "https://www.site.com/promo-2020",
      "it" : "https://www.site.com/it/promo-2020",
      …
    }
  }, … ]
}

promotions.get

Returns a promotion given its identifier.

Request

Admin SDK
Admin.api('commerce.promotions.get', request, function(response) { … });
HTTP POST
/api/v10/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 2020",
      "it" : "Promo 2020"
    },
    "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
    "inActivityRange" : true, // indicates if current time is between promotion's startTime and endTime -- 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…)
    },
    "discountedQuantity" : { // quantity that will be discounted (can be null)
      "quantity" : 4, // quantity of discounted items - int(1..)
      "excludeMinQuantity" : false // indicates if the minimum quantity is excluded from the discount - bool
    },
    "shippingMethods" : [ 3, 5, … ], // shipping methods (id) (can be null) - int(1…)
    "groups" : [ 5, 7, … ], // customer groups (id) (can be null) - int(1…255)
    "coupon" : "PROMO2020", // 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..)
    "minQuantity" : { // minimum quantity to purchase (can be null)
      "quantity" : 4, // minimum quantity of items in the cart - int(0..)
      "groupBy" : "Item" // how to group purchased quantity. Can be "Item", "Product" or "Cart" - string
    },
    "discount" : { // discount
      "type" : "PercentOff", // discount type, can be "PercentOff", "AmountOff" or "FixedPrice" - string
      "value" : 20.000 // discount value - decimal[8,3](0…)
    },
    "startTime" : "2020-11-15 12:00:00", // first promotion date and time - datetime
    "endTime" : "2020-01-15 12:00:00", // last promotion date and time - datetime
    "hourLimits" : { // Hours during which the promotion is active (can be null)
      "start" : 12, // Hour of promotion activation - int(0..23)
      "end" : 18 // Hour of promotion deactivation - int(0..23)
    }, 
    "combinationRule" : "Discounted", // combination rule, can be "None", "Discounted", "Subsequent" or "DiscountedAndSubsequent" - string
    "smallImage" : { // small image (can be null)
      "url" : "https://…", // 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" : "https://…", // 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" : ""
    },
    "seoDescription" : { // description for SEO - string(2) -> string(0…255)
      "en" : "",
      "it" : ""
    },
    "canonicalURL" : { // canonical URL - string(2) -> string(10…)
      "en" : "https://www.site.com/promo-2020",
      "it" : "https://www.site.com/it/promo-2020",
      …
    }
  }
}

promotions.count

Number of promotions that meet the given conditions.

Request

Admin SDK
Admin.api('commerce.promotions.count', request, function(response) { … });
HTTP POST
/api/v10/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
    "inActivityRange" : true, // … for which current time is between promotion's startTime and endTime -- 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" : "PROMO2020", // … 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/v10/commerce.promotions.create
{
  "promotion" : { // promotion to create (required)
    "name" : { // name - string(2) -> string(0…60)
      "en" : "Promo 2020",
      "it" : "Promo 2020"
    },
    "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…)
    },
    "discountedQuantity" : { // quantity that will be discounted (can be null)
      "quantity" : 4, // quantity of discounted items - int(1..)
      "excludeMinQuantity" : false // indicates if the minimum quantity is excluded from the discount - bool
    },
    "shippingMethods" : [ 3, 5, … ], // shipping methods (id) (can be null) - int(1…)
    "groups" : [ 5, 7, … ], // customer groups (id) (can be null) - int(1…255)
    "coupon" : "PROMO2020", // 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..)
    "minQuantity" : { // minimum quantity to purchase (can be null)
      "quantity" : 4, // minimum quantity of items in the cart - int(0..)
      "groupBy" : "Item" // how to group purchased quantity. Can be "Item", "Product" or "Cart" - string
    },
    "discount" : { // discount
      "type" : "PercentOff", // discount type, can be "PercentOff", "AmountOff" or "FixedPrice" - string
      "value" : 20.000 // discount value - decimal[8,3](0…)
    },
    "startTime" : "2020-11-15 12:00:00", // first promotion date and time - datetime
    "endTime" : "2020-01-15 12:00:00", // last promotion date and time - datetime
    "hourLimits" : { // Hours during which the promotion is active (can be null)
      "start" : 12, // Hour of promotion activation - int(0..23)
      "end" : 18 // Hour of promotion deactivation - int(0..23)
    },
    "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" : ""
    },
    "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 than 100 for 'PercentOff' discounts
discountedQuantity InvalidCombination Discounted quantity cannot be null for 'DiscountedItems' promotions
discountedQuantity InvalidCombination Discounted quantity must be null for <type> promotions
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
hourLimits Malformed start and end cannot be equal
minQuantity InvalidCombination Minimum quantity cannot be null for 'DiscountedItems' promotions
minQuantity InvalidCombination Minimum quantity must be null for <type> promotions
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/v10/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 2020",
      "it" : "Promo 2020"
    },
    "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…)
    },
    "discountedQuantity" : { // quantity that will be discounted (can be null)
      "quantity" : 4, // quantity of discounted items - int(1..)
      "excludeMinQuantity" : false // indicates if the minimum quantity is excluded from the discount - bool
    },
    "shippingMethods" : [ 3, 5, … ], // shipping methods (id) (can be null) - int(1…)
    "groups" : [ 5, 7, … ], // customer groups (id) (can be null) - int(1…255)
    "coupon" : "PROMO2020", // 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..)
    "minQuantity" : { // minimum quantity to purchase (can be null)
      "quantity" : 4, // minimum quantity of items in the cart - int(0..)
      "groupBy" : "Item" // how to group purchased quantity. Can be "Item", "Product" or "Cart" - string
    },
    "discount" : { // discount
      "type" : "PercentOff", // discount type, can be "PercentOff", "AmountOff" or "FixedPrice" - string
      "value" : 20.000 // discount value - decimal[8,3](0…)
    },
    "startTime" : "2020-11-15 12:00:00", // first promotion date and time - datetime
    "endTime" : "2020-01-15 12:00:00", // last promotion date and time - datetime
    "hourLimits" : { // Hours during which the promotion is active (can be null)
      "start" : 12, // Hour of promotion activation - int(0..23)
      "end" : 18 // Hour of promotion deactivation - int(0..23)
    },
    "combinationRule" : "Discounted", // combination rule, can be "None", "Discounted", "Subsequent" or "DiscountedAndSubsequent" - string
    "smallImage" : { // small image (can be null)
      "name" : "small.jpg", // file name - string(1…255)
      "content" : "N3R…zaA==" // content encoded in Base64 - string
    },
    "largeImage" : { // large image (can be null)
      "name" : "large.jpg", // file name - string(1…255)
      "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" 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" : ""
    },
    "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 than 100 for 'PercentOff' discounts
discountedQuantity InvalidCombination Discounted quantity cannot be null for 'DiscountedItems' promotions
discountedQuantity InvalidCombination Discounted quantity must be null for <type> promotions
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
hourLimits Malformed start and end cannot be equal
largeImage Malformed File format is not a valid or supported format
largeImage Malformed Image width and height must be less than 2500 pixel
minQuantity InvalidCombination Minimum quantity cannot be null for 'DiscountedItems' promotions
minQuantity InvalidCombination Minimum quantity must be null for <type> promotions
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/v10/commerce.promotions.delete
{
  "ids" : [ 43, 12, … ] // identifiers of the promotions to delete (required) - int(1…)
}

Response

{
  "status" : "ok"
}