commerce/catalog/admin/discounts

Use the Discounts resource to define and manage discounts to apply to products, product categories, or orders. The discounts can be a specified amount off the price, percentage off the price, or for free shipping. You can create a coupon code that shoppers can use to redeem the discount.

Note for Variant Discounting: If you attempt to select a product using the product code of the base product, the API will select all variations of that product. If you want to reference a specific product variant, add the variant code to the end of the product code.

JSON Example

Discount Properties

Property	Description
amount	type: decimal The amount of the order-level adjustment, which can be a positive or negative amount.
amountType	type: string The type of discount amount, such as an amount or a percentage.
auditInfo	type: auditInfo Basic audit info about the object, including date, time, and user account. This data may be captured when creating, updating, and removing data.
auditInfo.createBy	type: string Identifier of the user that created the object. System created and read only.
auditInfo.createDate	type: DateTime The date and time in UTC format set when the object was created.
auditInfo.updateBy	type: string Identifier of the user that updated the entity most recently.
auditInfo.updateDate	type: DateTime The date and time in UTC format the object was updated most recently.
canBeDeleted	type: bool Signifies that the discount is not referenced and can be hard deleted
canBeStackedUpon	type: bool Boolean field, if true, this discount will allow discounts in the following layer to be stacked on top.
conditions	type: discountCondition List of conditions that must be met for the discount to apply.
discountCondition.categoriesToExcludeFromMinOrderTotal	type: list of categoryDiscountCondition
discountCondition.categoryDiscountCondition.categoryId	type: int ID of the relevant category.
discountCondition.couponCode	type: string The coupon code that a shopper uses to redeem an associated discount on a purchase. This is also the unique identifier of the coupon itself.
discountCondition.customerSegments	type: list of customerSegment List of customer segments associated with the discount. Shoppers who are members of an associated customer segment can redeem this discount.
discountCondition.customerSegment.id	type: int Unique identifier of the source property, such as a catalog, discount, order, or email template. For a product field it will be the name of the field. For a category ID, must be a positive integer not greater than 2000000. By default, Kibo eCommerce auto-generates a category ID when categories are created. If you want to specify an ID during creation (which preserves category link relationships when migrating tenant data from one sandbox to another), you must also include the useProvidedId query string in the endpoint. For example, api/commerce/catalog/admin/categories/?useProvidedId=true. Then, use the id property to specify the desired category ID. For a product attribute it will be the Attribute FQN. For a document, the ID must be specified as a 32 character, case-insensitive, alphanumeric string. You can specify the ID as 32 sequential characters or as groups separated by dashes in the format 8-4-4-4-12. For example, bba0a1a885e2413bb097ceacf7bac366 or bba0a1a8-85e2-413b-b097-ceacf7bac366. For email templates, the ID must be one of the following values: BackInStock OrderChanged OrderShipped OrderFulfillmentDetailsChanged ShopperLoginCreated ShopperPasswordReset ReturnCreated ReturnAuthorized ReturnUpdated ReturnRejected ReturnCancelled ReturnClosed RefundCreated StoreCreditCreated StoreCreditUpdated GiftCardCreated
discountCondition.excludedCategories	type: list of categoryDiscountCondition List of the product categories that are not eligible for the discount.
discountCondition.categoryDiscountCondition.categoryId	type: int ID of the relevant category.
discountCondition.excludedProducts	type: list of productDiscountCondition List of products that are not eligible for the discount.
discountCondition.productDiscountCondition.productCode	type: string The unique, user-defined product code of a product, used throughout Kibo eCommerce to reference and associate to a product.
discountCondition.expirationDate	type: DateTime Date and time in UTC format when a discount, credit, wish list, or cart expires. An expired discount no longer can be redeemed. An expired wish list is no longer available. An expired credit can no longer be redeemed for a purchase. Acart becomes inactive and expired based on a system-calculated interval. For example, if an anonymous shopper has 14 days of inactivity, the cart is considered abandoned after that period of inactivity. System-supplied and read-only.
discountCondition.includedCategories	type: list of categoryDiscountCondition List of product categories that are eligible for the discount.
discountCondition.categoryDiscountCondition.categoryId	type: int ID of the relevant category.
discountCondition.includedPaymentWorkflows	type: list of string List of payment types that trigger this discount to be valid.
discountCondition.includedProducts	type: list of productDiscountCondition List of products that are eligible for the discount.
discountCondition.productDiscountCondition.productCode	type: string The unique, user-defined product code of a product, used throughout Kibo eCommerce to reference and associate to a product.
discountCondition.maximumOrderAmount	type: decimal This allows you to set a maximum order total as a condition of a discount, so the discount only applies when the shopper has an order totaling less than that value. This allows you to have more control over when discounts should or should not apply in order to control costs, especially when combined with a minimum order value to create a range of order values that are eligible for the discount. This can be used in addition to other discount conditions as well.
discountCondition.maxRedemptionCount	type: int The maximum number of times the discount can be redeemed.
discountCondition.minimumCategorySubtotalBeforeDiscounts	type: decimal This specifies the minimum amount that must be purchased in the combined categories defined in IncludedCategories. This amount is calculated before discounting and it is not used if IncludedCategories is empty.
discountCondition.minimumLifetimeValueAmount	type: decimal The minimum customer lifetime value amount required to redeem this discount.
discountCondition.minimumOrderAmount	type: decimal The minimum order amount required to redeem this discount.
discountCondition.minimumQuantityProductsRequiredInCategories	type: int This specifies the minimum quantity of products in the categories specified in IncludedCategories, which must be purchased to qualify for the associated discount. This defaults to 1 if null, and IncludedCategories has values.
discountCondition.minimumQuantityRequiredProducts	type: int This specifies the minimum quantity of products in the specified IncludedProducts that must be purchased to qualify for the associated discount. This defaults to 1 if null, and IncludedProducts has values.
discountCondition.minimumRequiredQuantityPerRedemption	type: int minimumRequiredQuantityPerRedemption ApiType DOCUMENT_HERE
discountCondition.productsToExcludeFromMinOrderTotal	type: list of productDiscountCondition
discountCondition.productDiscountCondition.productCode	type: string The unique, user-defined product code of a product, used throughout Kibo eCommerce to reference and associate to a product.
discountCondition.requiresAuthenticatedUser	type: bool If true, only authenticated users can redeem the discount. If false, anonymous users can redeem the discount.
discountCondition.requiresCoupon	type: bool If true, redemption of this discount requires entry of a coupon code.
discountCondition.startDate	type: DateTime The earliest date and time this discount can be redeemed.
content	type: discountLocalizedContent Localizable content (such as a name and/or description) for an attribute. The content may be localized when displayed according to the locale code specified by the master catalog. Content can include descriptive text for product extensible attributes, catalog-level descriptions (displayed if isContentOverriden is true), product bundles, and customer account notes.
discountLocalizedContent.auditInfo	type: auditInfo Basic audit info about the object, including date, time, and user account. This data may be captured when creating, updating, and removing data.
discountLocalizedContent.auditInfo.createBy	type: string Identifier of the user that created the object. System created and read only.
discountLocalizedContent.auditInfo.createDate	type: DateTime The date and time in UTC format set when the object was created.
discountLocalizedContent.auditInfo.updateBy	type: string Identifier of the user that updated the entity most recently.
discountLocalizedContent.auditInfo.updateDate	type: DateTime The date and time in UTC format the object was updated most recently.
discountLocalizedContent.friendlyDescription	type: string The localizable, shopper-facing description defined for a discount or a storefront message.
discountLocalizedContent.localeCode	type: string The two character locale code, per the country code provided. This code determines the localized content to use and display.
discountLocalizedContent.name	type: string The user supplied name that appears in Admin. You can use this field for identification purposes.
currentRedemptionCount	type: int The number of times this discount has been redeemed.
doesNotApplyToMultiShipToOrders	type: bool True if the discount should not apply to orders with multiple shipments. For more information, refer to the topic on multiple shipments.
doesNotApplyToProductsWithSalePrice	type: bool Determines whether or not a discount applies to a items with a sale price. Applicable on order and line item discounts. For line items, when this is true, the discount will be disqualified. For order level discounts, when true, the discount will not be applied to those items have a sale price.
doesNotApplyToSalePrice	type: bool If true, this discount does not apply to a line item product with a defined sale price. The default is false, which applies the discount to products with and without defined sale prices.
hasPurchaseConditions	type: bool hasPurchaseConditions ApiType DOCUMENT_HERE
id	type: int Unique identifier of the source property, such as a catalog, discount, order, or email template. For a product field it will be the name of the field. For a category ID, must be a positive integer not greater than 2000000. By default, Kibo eCommerce auto-generates a category ID when categories are created. If you want to specify an ID during creation (which preserves category link relationships when migrating tenant data from one sandbox to another), you must also include the useProvidedId query string in the endpoint. For example, api/commerce/catalog/admin/categories/?useProvidedId=true. Then, use the id property to specify the desired category ID. For a product attribute it will be the Attribute FQN. For a document, the ID must be specified as a 32 character, case-insensitive, alphanumeric string. You can specify the ID as 32 sequential characters or as groups separated by dashes in the format 8-4-4-4-12. For example, bba0a1a885e2413bb097ceacf7bac366 or bba0a1a8-85e2-413b-b097-ceacf7bac366. For email templates, the ID must be one of the following values: BackInStock OrderChanged OrderShipped OrderFulfillmentDetailsChanged ShopperLoginCreated ShopperPasswordReset ReturnCreated ReturnAuthorized ReturnUpdated ReturnRejected ReturnCancelled ReturnClosed RefundCreated StoreCreditCreated StoreCreditUpdated GiftCardCreated
includedPriceLists	type: list of string Products receiving a price from a price list specified here or a child of a specified price list can be discounted.
isBxGx	type: bool This field is read-only and specifies whether the discount condition is one product or category, and matches the discount target.
maximumDiscountImpactPerOrder	type: decimal Maximum impact this discount can apply on a single order. Must be either null or greater than zero.
maximumDiscountImpactPerRedemption	type: decimal Maximum impact this discount can apply on a single line item. Must be either null or greater than zero.
maximumRedemptionsPerOrder	type: int Maximum number of redemptions allowed per order. If null, defaults to unlimited.
maximumUsesPerUser	type: int The maximum number of times an individual shopper can redeem the discount.
preventLineItemShippingDiscounts	type: bool
preventOrderProductDiscounts	type: bool
preventOrderShippingDiscounts	type: bool
purchaseRequirementType	type: string purchaseRequirementType ApiType DOCUMENT_HERE
scope	type: string The scope to which the discount applies, which is "Order" for order discounts or "LineItem" for individual product discounts.
stackingLayer	type: int Numerical field representing number of discount layer (up to 3) -Each discount can be assigned to a layer which is then used to determine the order of application. Discounts in the same layer will compete and provide the best value for the shopper.
status	type: string The current status of the object. This value is read only. Valid values for this field are: "Active", "Expired", and "Inactive".
target	type: discountTarget Targets represent the object, such as an item to apply discounts to(products or orders) or a view field for content. Targets are the dot notations that link to the source document property. For example, firstitem for the direct level or firstitem.seconditem.thirditem for a deeper property.
discountTarget.appliesToLeastExpensiveProductsFirst	type: bool Determines which way the discount is optimized. Consumers favor(default - false/null) or tenants favor (when this is set to true) Applies to discounts where target is not a specific product or list of products. May also impact behavior of Buy X Get Y so that X is the most expensive items and Y the least expensive.
discountTarget.categories	type: list of targetedCategory The list of all categories associated with the product. These categories contain products, can have discounts associated, and define the grouping of products to display on the storefront.
discountTarget.targetedCategory.id	type: int Unique identifier of the source property, such as a catalog, discount, order, or email template. For a product field it will be the name of the field. For a category ID, must be a positive integer not greater than 2000000. By default, Kibo eCommerce auto-generates a category ID when categories are created. If you want to specify an ID during creation (which preserves category link relationships when migrating tenant data from one sandbox to another), you must also include the useProvidedId query string in the endpoint. For example, api/commerce/catalog/admin/categories/?useProvidedId=true. Then, use the id property to specify the desired category ID. For a product attribute it will be the Attribute FQN. For a document, the ID must be specified as a 32 character, case-insensitive, alphanumeric string. You can specify the ID as 32 sequential characters or as groups separated by dashes in the format 8-4-4-4-12. For example, bba0a1a885e2413bb097ceacf7bac366 or bba0a1a8-85e2-413b-b097-ceacf7bac366. For email templates, the ID must be one of the following values: BackInStock OrderChanged OrderShipped OrderFulfillmentDetailsChanged ShopperLoginCreated ShopperPasswordReset ReturnCreated ReturnAuthorized ReturnUpdated ReturnRejected ReturnCancelled ReturnClosed RefundCreated StoreCreditCreated StoreCreditUpdated GiftCardCreated
discountTarget.excludedCategories	type: list of targetedCategory List of the product categories that are not eligible for the discount.
discountTarget.targetedCategory.id	type: int Unique identifier of the source property, such as a catalog, discount, order, or email template. For a product field it will be the name of the field. For a category ID, must be a positive integer not greater than 2000000. By default, Kibo eCommerce auto-generates a category ID when categories are created. If you want to specify an ID during creation (which preserves category link relationships when migrating tenant data from one sandbox to another), you must also include the useProvidedId query string in the endpoint. For example, api/commerce/catalog/admin/categories/?useProvidedId=true. Then, use the id property to specify the desired category ID. For a product attribute it will be the Attribute FQN. For a document, the ID must be specified as a 32 character, case-insensitive, alphanumeric string. You can specify the ID as 32 sequential characters or as groups separated by dashes in the format 8-4-4-4-12. For example, bba0a1a885e2413bb097ceacf7bac366 or bba0a1a8-85e2-413b-b097-ceacf7bac366. For email templates, the ID must be one of the following values: BackInStock OrderChanged OrderShipped OrderFulfillmentDetailsChanged ShopperLoginCreated ShopperPasswordReset ReturnCreated ReturnAuthorized ReturnUpdated ReturnRejected ReturnCancelled ReturnClosed RefundCreated StoreCreditCreated StoreCreditUpdated GiftCardCreated
discountTarget.excludedCategoriesOperator	type: string The operator to use on the excludedCategories field. Valid values are: "All" and "Any".
discountTarget.excludedProducts	type: list of targetedProduct List of products that are not eligible for the discount.
discountTarget.targetedProduct.productCode	type: string The unique, user-defined product code of a product, used throughout Kibo eCommerce to reference and associate to a product.
discountTarget.excludeItemsWithExistingProductDiscounts	type: bool Prevents order scoped discounts from layering over items that already have a product discount with the same type.
discountTarget.excludeItemsWithExistingShippingDiscounts	type: bool Prevents order scoped discounts from layering over items that already have a shipping discount with the same type.
discountTarget.includeAllProducts	type: bool If true, the target discount applies to all products sold on the site, regardless of product category.
discountTarget.includedCategoriesOperator	type: string The operator of the includedCategories field. Valid values are: "All" and "Any".
discountTarget.maximumQuantityPerRedemption	type: int When a condition is specified, this property limits the number of items that are targeted for each discount redemption with an order. If multiple redemptions are allowed for each order then multiples of this value are allowed in multiples of the associated condition. If no condition is specified, then this value is not used. If null and condition exists, then defaults to 1.
discountTarget.products	type: list of targetedProduct List of product codes that represent the products to which the discount can apply.
discountTarget.targetedProduct.productCode	type: string The unique, user-defined product code of a product, used throughout Kibo eCommerce to reference and associate to a product.
discountTarget.shippingMethods	type: list of targetedShippingMethod The list of shipping method codes that represents the shipping service types to which the discount can apply.
discountTarget.targetedShippingMethod.code	type: string The unique identifier of the object.
discountTarget.targetedShippingMethod.name	type: string The user supplied name that appears in Admin. You can use this field for identification purposes.
discountTarget.shippingZones	type: list of targetedShippingZone The list of shipping zones that are applicable for this discount.
discountTarget.targetedShippingZone.zone	type: string The zone string for the tenant domain.
discountTarget.type	type: string The type of scope, which is a developer account or production tenant.
thresholdMessage	type: thresholdMessage Information on where, when and what content to display in a threshold message to customers.
thresholdMessage.auditInfo	type: auditInfo Basic audit info about the object, including date, time, and user account. This data may be captured when creating, updating, and removing data.
thresholdMessage.auditInfo.createBy	type: string Identifier of the user that created the object. System created and read only.
thresholdMessage.auditInfo.createDate	type: DateTime The date and time in UTC format set when the object was created.
thresholdMessage.auditInfo.updateBy	type: string Identifier of the user that updated the entity most recently.
thresholdMessage.auditInfo.updateDate	type: DateTime The date and time in UTC format the object was updated most recently.
thresholdMessage.content	type: thresholdMessageLocalizedContent Localizable content (such as a name and/or description) for an attribute. The content may be localized when displayed according to the locale code specified by the master catalog. Content can include descriptive text for product extensible attributes, catalog-level descriptions (displayed if isContentOverriden is true), product bundles, and customer account notes.
thresholdMessage.thresholdMessageLocalizedContent.auditInfo	type: auditInfo Basic audit info about the object, including date, time, and user account. This data may be captured when creating, updating, and removing data.
thresholdMessage.thresholdMessageLocalizedContent.auditInfo.createBy	type: string Identifier of the user that created the object. System created and read only.
thresholdMessage.thresholdMessageLocalizedContent.auditInfo.createDate	type: DateTime The date and time in UTC format set when the object was created.
thresholdMessage.thresholdMessageLocalizedContent.auditInfo.updateBy	type: string Identifier of the user that updated the entity most recently.
thresholdMessage.thresholdMessageLocalizedContent.auditInfo.updateDate	type: DateTime The date and time in UTC format the object was updated most recently.
thresholdMessage.thresholdMessageLocalizedContent.localeCode	type: string The two character locale code, per the country code provided. This code determines the localized content to use and display.
thresholdMessage.thresholdMessageLocalizedContent.messageTemplate	type: string Locale-based contents of the Threshold Message that will be displayed.
thresholdMessage.discountId	type: int The unique identifier of the discount.
thresholdMessage.isActive	type: bool Indicates if the object or feature is active.
thresholdMessage.requiresCouponCode	type: bool Indicates if the threshold message will display when a promo code is evaluated
thresholdMessage.showInCart	type: bool Indicates if the threshold message will display in the cart
thresholdMessage.showOnCheckout	type: bool Indicates if the threshold message will display on the checkout page
thresholdMessage.thresholdValue	type: decimal The cart total amount that must be met before the threshold message is displayed

Operations

Operation Name	Request URI	Description
CreateDiscount	POST %3fresponseFields%3d%7bresponseFields%7d	Creates a new discount or coupon to apply to a product, category, order, or shipping.
DeleteDiscount	DELETE %7bdiscountId%7d	Deletes a discount specified by its discount ID.
GenerateRandomCoupon	GET generate-random-coupon%3fresponseFields%3d%7bresponseFields%7d	Generates a random code for a coupon.
GetDiscount	GET %7bdiscountId%7d%3fresponseFields%3d%7bresponseFields%7d	Retrieves the details of a single discount.
GetDiscountContent	GET %7bdiscountId%7d%2fcontent%3fresponseFields%3d%7bresponseFields%7d	Retrieves the localized content specified for the specified discount.
GetDiscounts	GET %3fstartIndex%3d%7bstartIndex%7d%26pageSize%3d%7bpageSize%7d%26sortBy%3d%7bsortBy%7d%26filter%3d%7bfilter%7d%26responseFields%3d%7bresponseFields%7d	Retrieves a list of discounts according to any specified filter criteria and sort options.
UpdateDiscount	PUT %7bdiscountId%7d%3fresponseFields%3d%7bresponseFields%7d	Updates one or more properties of the specified discount.
UpdateDiscountContent	PUT %7bdiscountId%7d%2fcontent%3fresponseFields%3d%7bresponseFields%7d	Updates the localizable content for the specified discount or renames the discount without modifying its other properties.