Module promotions

threshold: The quantity of eligible products required.

discount: The discount applied to the bonus product; typically fixed_price, percentage, or amount.

eligibleQuantity: The number of eligible products that earn the bonus.

requireExactEligibleQuantity: Determines if exactly the eligible quantity is required, rather than at least.

filters: A list of filters that are logically combined by an operator.

operator: The logical operator that is used to combine the filters.

must: List of queries to be evaluated as an AND operator.

mustNot: List of queries to be evaluated as a NOT operator.

should: List of queries to be evaluated as an OR operator.

campaignId: The ID of the campaign.

• Min Length: 1
• Max Length: 256

coupons: The array of assigned coupon IDs, not sorted.

creationDate: Returns the value of attribute 'creationDate'.

customerGroups: The array of assigned customer groups, not sorted.

description: The description of the campaign.

• Max Length: 4000

enabled: The enabled flag for campaign.

endDate: The date the scenario ends.

lastModified: Returns the value of attribute 'lastModified'.

sourceCodeGroups: The array of assigned source code groups, not sorted.

startDate: The date the scenario begins.

type: The kind of discount.

amount: The monetary value, for amount, fixed_price, total_fixed_price, and fixed_price_shipping discounts.

percentage: The percentage off, for percentage and percent_off_options discounts.

priceBookId: The price book the discounted price is taken from, for a price_book_price discount.

• Max Length: 256

bonusProducts: The bonus products offered, for bonus and bonus_choice discounts.

promotionRule: The discount rule for this promotion. Its shape is selected by the parent promotion's promotionClass (product, order, or shipping) and holds the discount, tiers, BOGO, thresholds, max-applications, and class-specific flags.

qualifyingProducts: The products a customer must purchase for the promotion to apply.

discountedProducts: The products that receive the discount. Valid only for a product-class promotion; supplying it for an order or shipping promotion is rejected with a 400.

excludedProducts: The products excluded from both qualifying for and receiving the discount. Valid only for an order-class promotion; supplying it for a product or shipping promotion is rejected with a 400.

paymentMethodQualifiers: The payment methods the promotion is restricted to.

title: A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization

• Max Length: 256

type: A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per [RFC3986], Section 5.

• Max Length: 2048

detail: A human-readable explanation specific to this occurrence of the problem.

instance: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per [RFC3986], Section 5.

• Max Length: 2048

boolFilter:

queryFilter:

range2Filter:

rangeFilter:

termFilter:

filter:

query:

currencyMnemonic: A three letter uppercase currency code conforming to the ISO 4217 standard, or the string N/A indicating that a currency is not applicable.

• Pattern: /^([A-Z][A-Z][A-Z]|N/A)$/

value: The amount of money for the given currency.

path: The path to the nested document.

• Max Length: 2048

query:

scoreMode: Indicates how scores for matching child objects affect the root parent document’s relevance score.

promotionClass: The promotion class discriminator. Always order for an order promotion rule.

discount: The discount applied by this rule.

tiers: The tiered discounts, applied by threshold. Empty or absent for a non-tiered rule.

discountOnlyQualifyingProducts: Determines if only the qualifying products are discounted.

excludeDiscountedProducts: Determines if products that already received a product-level discount are excluded.

disableGlobalExcludedProducts: Determines if this rule ignores the site-level global product exclusions. Distinct from the promotion-level disableGloballyExcluded flag.

enableUpsells: Determines if the promotion is returned as an approaching promotion to encourage upsell.

upsellThreshold: The amount by which the merchandise total may fall short of the purchase condition and still upsell.

offset: The zero-based index of the first hit/data to include in the result.

limit: Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter limit of the endpoint returning this schema.

total: The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

query:

sorts: The sorting that was applied to the result.

hits: The sorted array of search hits. Can be empty.

offset: The zero-based index of the first hit/data to include in the result.

limit: Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter limit of the endpoint returning this schema.

total: The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

type: The kind of product condition.

operator: The comparison operator, as a lower_snake_case token. The valid set depends on the condition type: category: is_equal, is_exactly, is_direct_child_of, is_child_of, is_direct_parent_of, is_parent_of, is_sibling_of; brand: exists, does_not_exist, is_equal, is_not_equal, starts_with, ends_with, contains, does_not_contain; product_id: is_equal, is_not_equal, starts_with, ends_with, contains, does_not_contain; price: less_than, greater_than, ends_with; inventory: less_than, greater_than; attribute: less_than, greater_than, equals, is_not_equal, exists, does_not_exist, starts_with, ends_with, contains, does_not_contain; product_set: is_equal, exists; price_book: storefront_price_in_recursive, storefront_price_in, price_in; option: is_equal, exists, does_not_exist.

• Max Length: 256

values: The values compared against.

catalogId: The id of the catalog that owns the categories listed in values. Required when type is `category; ignored for every other condition type.

• Max Length: 256

attributeId: The id of the custom product attribute to compare. Required when type is attribute; ignored for every other condition type.

• Max Length: 256

optionId: The id of the product option to compare. Required when type is option; ignored for every other condition type.

• Max Length: 256

conditions: The conditions in this group.

promotionClass: The promotion class discriminator. Always product for a product promotion rule.

discount: The discount applied by this rule.

tiers: The tiered discounts, applied by threshold. Empty or absent for a non-tiered rule.

bogo: The buy-one-get-one discount. Present only for a buy-X-get-Y product promotion.

maxApplications: The maximum number of times the discount can be applied.

identicalProducts: Determines if the qualifying and discounted products must all be identical.

prorate: Determines if the discount is prorated across the eligible items.

disableGlobalExcludedProducts: Determines if this rule ignores the site-level global product exclusions. Distinct from the promotion-level disableGloballyExcluded flag.

includedProducts: The condition groups a product must match.

excludedProducts: The condition groups that exclude a product.

methodIds: The payment method IDs. Each is either a payment method ID or a credit card type prefixed with CREDIT_CARD (for example CREDIT_CARD.Visa).

methodIds: The shipping method IDs.

archived: Determines if this promotion is archived. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.

assignmentInformation: Information about the assignments and assignment schedules of this promotion.

creationDate: Returns the value of attribute 'creationDate'.

currencyCode: The ISO 4217 mnemonic code of the currency this promotion is restricted to. If not populated, then there is no currency restriction on the promotion.

• Max Length: 3

disableGloballyExcluded: Determines if this promotion ignores the global product exclusions for promotions.

enabled: Determines if this promotion is enabled. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.

exclusivity: Determines if the promotion can be combined with other promotions of the same promotion class or if it cannot be combined with any other promotions. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.

id: The ID for the promotion.

lastModified: Returns the value of attribute 'lastModified'.

name: The user supplied name of this promotion, which can be localized.

promotionClass: The class of the promotion. If the promotion class is modified, then the promotion rule and all of its values, such as whether or not to disable global product exclusions, are reset.

tags: Returns the list of tags assigned to this promotion. If used to set the tags on a promotion, the promotion will only have the tags passed in the input. Any existing tags are removed.

abtestDescription:

abtestId:

enabled:

schedule:

segmentDescription:

segmentId:

abtestId: If there is only one assignment, and that assignment is an A/B test segment, the ID of the A/B test the segment belongs to. Otherwise, empty.

abtestSegmentId: If there is only one assignment, and that assignment is an A/B test segment, the ID of the A/B test segment. Otherwise, empty.

active: True if the individual assignment or the multiple assignments are currently active.

activeAbtestAssignments: A list of currently active A/B tests this is assigned to.

activeCampaignAssignments: A list of currently active campaigns this is assigned to.

campaignId: If there is only one assignment, and that assignment is a campaign, the ID of the campaign. Otherwise, empty.

enabled:

endDate: The end date of the container of the assignment (a Campaign or ABTest). If scheduleType is scheduleType : "multiple" or scheduleType : "none", then then result is null. Also, a null date returns null.

schedule: The schedule of the assignment (a Campaign or ABTest). If scheduleType is scheduleType : "multiple" or scheduleType : "none", then then result is null.

scheduleType: If there is only one active assignment, or no active assignments and one upcoming assignment, this is that type of assignment (scheduleType : "campaign" or scheduleType : "abtest"). If there are no assignments, it is scheduleType : "none", otherwise, scheduleType : "multiple".

startDate: The start date of the container of the assignment (a Campaign or ABTest). If scheduleType is scheduleType : "multiple" or scheduleType : "none", then then result is null. Also, a null date returns null.

upcomingAbtestAssignments: A list of upcoming A/B tests this is assigned to.

upcomingCampaignAssignments: A list of upcoming campaigns this is assigned to.

campaign: The campaign.

campaignId: The ID of the campaign.

• Min Length: 1
• Max Length: 256

coupons: The sorted array of assigned coupon IDs.

customerGroups: The sorted array of assigned customer groups.

description: The description of the promotion campaign assignment.

• Max Length: 4000

enabled: True if the assignment resource is enabled.

promotion: The promotion.

promotionId: The ID of the promotion.

• Min Length: 1
• Max Length: 256

rank: The rank of promotion campaign assignment.

schedule: The schedule of the assignment resource.

sourceCodeGroups: The sorted array of assigned source code groups.

exclusivity: Determines if the promotion can be combined with other promotions of the same promotion class, cannot be combined with any other promotion, or has no exclusivity restriction.

exclusivityGroup: The ID of the exclusivity group this promotion belongs to. Only meaningful when exclusivity restricts combination to promotions within the same group.

• Max Length: 256

combinablePromotions: The set of promotion or promotion-group IDs this promotion can be combined with.

mutuallyExclusivePromotions: The set of promotion or promotion-group IDs this promotion cannot be combined with.

hits: The sorted array of promotion search hits. Can be empty.

query:

sorts: The sorting that was applied to the result.

offset: The zero-based index of the first hit/data to include in the result.

limit: Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter limit of the endpoint returning this schema.

total: The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

boolQuery:

filteredQuery:

matchAllQuery: Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

nestedQuery:

termQuery:

textQuery:

query:

filterMode: Compare mode: overlap, containing, or contained.

fromField: The field name of the field that starts the first range.

• Max Length: 260

fromInclusive: A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to false.

fromValue: The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.

toField: The field name of the field that ends the first range.

• Max Length: 260

toInclusive: A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to false.

toValue: The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

field: The search field.

• Max Length: 260

from:

fromInclusive: A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to false.

to:

toInclusive: A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to false.

dayOfWeek: The days of week for recurrence.

timeOfDay: The time of the day for recurrence.

limit: Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter limit of the endpoint returning this schema.

total: The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

startDate: The date to start validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.

endDate: The date to end of validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.

recurrence: The recurrence of the schedule by day of week and time of day. Not all schedules support a recurrence.

limit: Maximum records to retrieve per request, not to exceed 200.

query:

sorts: The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.

offset: The zero-based index of the first hit/data to include in the result.

promotionClass: The promotion class discriminator. Always shipping for a shipping promotion rule.

discount: The discount applied by this rule.

tiers: The tiered discounts, applied by threshold. Empty or absent for a non-tiered rule.

shippingMethodQualifiers: The shipping methods the promotion applies to. Shipping-class only.

prohibitNonqualifyingProducts: Determines if the shipment must contain only qualifying products for the discount to apply.

disableGlobalExcludedProducts: Determines if this rule ignores the site-level global product exclusions. Distinct from the promotion-level disableGloballyExcluded flag.

maxApplications: The maximum number of times the discount can be applied.

field: The name of the field to sort on.

• Max Length: 256

sortOrder: The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.

tagId: The ID of the tag.

field: The filter field.

• Max Length: 260

operator: The operator used to compare the field's values with the given values.

values: The filter values.

fields: The document fields that the values are matched against, combined with the operator.

operator: Returns the operator to use for the term query.

values: The values that the fields are compared against, combined with the operator.

fields: The document fields that the search phrase matches against.

searchPhrase: A search phrase, which can include multiple terms separated by spaces.

threshold: The threshold at which this tier's discount applies.

conditionType: The kind of threshold. All tiers in the same rule MUST send the same value. Valid values depend on the promotion class - product: product_quantity, product_amount; order: order_total, product_quantity, product_combination; shipping: shipment_total, product_quantity, product_combination.

discount: The discount applied at this tier.

timeFrom: The time to start from. Time format: HH:mm or HH:mm:ss. Seconds are ignored and set to 0.

• Pattern: /^([01][0-9]|2[0-3]):[0-5]0-9?$/

timeTo: The time to end on. Time format: HH:mm or HH:mm:ss. Seconds are ignored and set to 0.

• Pattern: /^([01][0-9]|2[0-3]):[0-5]0-9?$/