Promotions

Last updated: 24-Feb-2026

Rate this article:

Overview

Use the Promotion object to create/update and update information on discounts/promotions you set up for your account.

Parameters

Parameters							Type/Description
Promotion							Object
				Name			String / Required
							Promotion name
				Description			String / Optional
							Promotion description
				StartDate			String / Optional
							Starting date. The date when you set the promotion to start. Is NULL for promotions that start immediately after they're created. Format: Y-m-d
				EndDate			String / Optional
							Ending date. The date when you set the promotion to end. Is NULL for promotions that you want active indefinitely. Format: Y-m-d
				MaximumOrdersNumber			Integer / Optional
							2Checkout stops offering the discount when the promotion reaches the maximum number of orders. Can be NULL if you want the promotion to apply to an unlimited number of orders.
				MaximumQuantity			Integer / Optional
							Discount only applies to a specific number of products, smaller than the maximum quantity you defined. Can be NULL if you want the promotion to apply to an unlimited number of units. Any extra quantity added to the cart will be sold at full price.
				InstantDiscount			Boolean / Optional
							Selecting the instant discount option will auto-apply the discount for ALL the selected products for all shoppers, without the need to enter the discount coupon.
Coupon							Object / Required
		Type					String
							SINGLE = one coupon code-shared by all shoppers MULTIPLE = array of unique coupon codes, each designed for individual use
		Code/Codes					Array of strings
							Varies according to type. Send: Code = 'single_code'; when Type = 'SINGLE'; Codes = ['code1', 'code2']; when Type = 'MULTIPLE';
Enabled							Bolean / Optional
							Possible values: TRUE - promotion is active. FALSE - promotion is inactive
ChannelType							String / Required
							Possible values: ECOMMERCE CHANNEL_MANAGER ALL
Type							String / Required
							Possible values: REGULAR GLOBAL SPECIAL_PRICE (use in combination with PriceMatrix and DefaultCurrency) CUMULATIVE (use in combination with ProductTaxCategoryUUID)
DefaultCurrency							String/Required
							Required for SPECIAL_PRICE promotions, represents the default currency of the promotion.
PriceMatrix							Array of objects (only for SPECIAL_PRICE type of promotion)/Required
							Is generated by the getPriceMatrix call and used to set promotion special prices.
ProductCode							String
							Code of the product that is used by promotion.
ProductTaxCategoryUUID							String or NULL
							The UUID of the tax category used for the product. Must be a category existent on your account. Required only for Cumulative promotions.
PricingConfigurationCode							String
							Code of pricing configuration used by promotion; must be related to the product.
OptionHash							String
							Unique identifier of one combination of price configuration options.
Options							Array of objects/Optional
							Describes price configuration options identified by OptionHash.
GroupName							String
OptionText							String
Prices							Array of objects/Required
							Promotion prices by currency; the price for default currency is required.
Value							Int/Required
							Decimal
Currency							String
							ISO code
Discount							Object / Required
			Type				String
							Discount type: PERCENT, use in combination with Value FIXED, use in combination with Values and DefaultCurrency
			Value / Values				Array of objects
							Value = Int, determines the discount percentage from 0 to 100 Values = Array of Value objects
						Value	Object
						Currency	String
							ISO currency code
						Amount	Integer
							Discount amount in corresponding currency.
			DefaultCurrency				String
							ISO code
Products							Object/ Optional
			Code				Integer/ Optional
							Unique product code that you control.
			PricingConfigurationCode				String / Optional
							Unique system generated pricing configuration code.
			PricingOptionCodes				Array of strings / Optional
							Array of pricing option codes controlled by you.
PriceThreshold							Object / Optional
							Limits discount use only when total order value (taxes included) exceeds the threshold you configure.
	Amount						Decimal / Optional
							The minimum threshold you defined for the default currency.
	Currency						String / Optional
							Currency code available for the default currency of custom threshold settings.
Translations							Array of objects / Optional
	PromotionTranslation						Object / Optional
					Name		String / Optional
							Localized name corresponding to translated language. Name: Le product Language: FR
					Language		String / Optional
							Language for localization.
Sources							StringArray / Optional
							Array of strings defining the sale source through the SRC parameter.
PublishToAffiliatesNetwork							Integer / Optional
							1 - make promotion available in the Affiliates Network 0 - keep promotion unavailable for the Affiliates Network
ApplyRecurring							String / Required
							Choose whether to apply the discount to renewal orders. Possible values: NONE ALL CUSTOM
RecurringChargesNumber							Integer / Optional
							If ApplyRecurring is set to CUSTOM, you can offer discounts for a number of recurring billing charges beyond the initial purchase.

Rate this article:

Global eCommerce

In-Person Payments

Business Tools

Petroleum & Convenience

APIs

2Checkout API Reference 6.0

Promotions

Promotions

Overview

Parameters

Need help?

Not yet a Verifone customer?