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.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.