# Promotions

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

## Request parameters <a href="#parameters" id="parameters"></a>

<table><thead><tr><th width="386.13330078125">Parameter</th><th>Type / Description</th></tr></thead><tbody><tr><td><code>Promotion</code></td><td><strong>Object</strong></td></tr><tr><td><code>Promotion.Name</code></td><td><strong>Required (string)</strong><br>Promotion name</td></tr><tr><td><code>Promotion.Description</code></td><td><strong>Optional (string)</strong><br>Promotion description</td></tr><tr><td><code>Promotion.StartDate</code></td><td><p><strong>Optional (string)</strong><br>Starting date. The date when you set the promotion to start. Is NULL for promotions that start immediately after they're created.</p><p>Format: Y-m-d</p></td></tr><tr><td><code>Promotion.EndDate</code></td><td><p><strong>Optional (string)</strong><br>Ending date. The date when you set the promotion to end. Is NULL for promotions that you want active indefinitely.</p><p>Format: Y-m-d</p></td></tr><tr><td><code>Promotion.MaximumOrdersNumber</code></td><td><strong>Optional (integer)</strong><br>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.</td></tr><tr><td><code>Promotion.MaximumQuantity</code></td><td><strong>Optional (integer)</strong><br>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.</td></tr><tr><td><code>Promotion.InstantDiscount</code></td><td><strong>Optional (boolean)</strong><br>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.</td></tr><tr><td><code>Coupon</code></td><td><strong>Required (object)</strong></td></tr><tr><td><code>Coupon.Type</code></td><td><p><strong>String</strong> </p><ul><li>SINGLE: one coupon code-shared by all shoppers</li><li>MULTIPLE: array of unique coupon codes, each designed for individual use</li></ul></td></tr><tr><td><code>Coupon.Code/Codes</code></td><td><p><strong>Array of strings</strong></p><p>Varies according to type. Send:</p><ul><li>Code: 'single_code'; when Type = 'SINGLE';</li><li>Codes: ['code1', 'code2']; when Type = 'MULTIPLE';</li></ul></td></tr><tr><td><code>Enabled</code></td><td><p><strong>Optional (boolean)</strong></p><p>Possible values:</p><ul><li>TRUE - promotion is active.</li><li>FALSE - promotion is inactive</li></ul></td></tr><tr><td><code>ChannelType</code></td><td><p><strong>Required (string)</strong></p><p>Possible values:</p><ul><li>ECOMMERCE</li><li>CHANNEL_MANAGER</li><li>ALL</li></ul></td></tr><tr><td><code>Type</code></td><td><p><strong>Required (string)</strong></p><p>Possible values:</p><ul><li>REGULAR</li><li>GLOBAL</li><li>SPECIAL_PRICE (use in combination with <code>PriceMatrix</code> and <code>DefaultCurrency</code>)</li></ul></td></tr><tr><td><code>DefaultCurrency</code></td><td><strong>Required (string)</strong><br>Required for <code>SPECIAL_PRICE</code> promotions, represents the default currency of the promotion.</td></tr><tr><td><code>PriceMatrix</code></td><td><strong>Required (array of objects)</strong> (only for <code>SPECIAL_PRICE</code> type of promotion)<br>Is generated by the <code>getPriceMatrix</code> call and used to set promotion special prices.</td></tr><tr><td><code>ProductCode</code></td><td><strong>String</strong><br>Code of the product that is used by promotion.</td></tr><tr><td><code>PricingConfigurationCode</code></td><td><strong>String</strong><br>Code of pricing configuration used by promotion; must be related to the product.</td></tr><tr><td><code>OptionHash</code></td><td><strong>String</strong><br>Unique identifier of one combination of price configuration options.</td></tr><tr><td><code>Options</code></td><td><strong>Optional (array of objects)</strong><br>Describes price configuration options identified by <code>OptionHash</code>.</td></tr><tr><td><code>GroupName</code></td><td><strong>String</strong></td></tr><tr><td><code>OptionText</code></td><td><strong>String</strong></td></tr><tr><td><code>Prices</code></td><td><strong>Required (array of objects)</strong><br>Promotion prices by currency; the price for default currency is required.</td></tr><tr><td><code>Value</code></td><td><strong>Required (int)</strong><br>Decimal</td></tr><tr><td><code>Currency</code></td><td><strong>String</strong><br>ISO code</td></tr><tr><td><code>Discount</code></td><td><strong>Required (object)</strong></td></tr><tr><td><code>Discount.Type</code></td><td><p><strong>String</strong> </p><p>Discount type:</p><ul><li>PERCENT, use in combination with <code>Value</code></li><li>FIXED, use in combination with <code>Values</code> and <code>DefaultCurrency</code></li></ul></td></tr><tr><td><code>Discount.Value/Values</code></td><td><strong>Array of objects</strong></td></tr><tr><td> </td><td><ul><li>Value = Int, determines the discount percentage from 0 to 100</li><li>Values = Array of Value objects</li></ul></td></tr><tr><td><code>Discount.Value/Values.Currency</code></td><td><strong>String</strong><br>ISO currency code </td></tr><tr><td><code>Discount.Value/Values.Amount</code></td><td><strong>Integer</strong> <br>Discount amount in corresponding currency.</td></tr><tr><td><code>Discount.DefaultCurrency</code></td><td><strong>String</strong><br>ISO code</td></tr><tr><td><code>Products</code></td><td><strong>Optional (object)</strong></td></tr><tr><td><code>Products.Code</code></td><td><strong>Optional (integer)</strong><br>Unique product code that you control.</td></tr><tr><td><code>Products.PricingConfigurationCode</code></td><td><strong>Optional (string)</strong><br>Unique system generated pricing configuration code.</td></tr><tr><td><code>Products.PricingOptionCodes</code></td><td><strong>Optional (array of strings)</strong><br>Array of pricing option codes controlled by you.</td></tr><tr><td><code>PriceThreshold</code></td><td><strong>Optional (object)</strong><br>Limits discount use only when total order value (taxes included) exceeds the threshold you configure.</td></tr><tr><td><code>PriceThreshold.Amount</code></td><td><strong>Optional (decimal)</strong><br>The minimum threshold you defined for the default currency.</td></tr><tr><td><code>PriceThreshold.Currency</code></td><td><strong>Optional (string)</strong><br>Currency code available for the default currency of custom threshold settings.</td></tr><tr><td><code>Translations</code></td><td><strong>Optional (array of objects)</strong></td></tr><tr><td><code>Translations.PromotionTranslation</code></td><td><strong>Optional (object)</strong></td></tr><tr><td><code>Translations.PromotionTranslation.Name</code></td><td><p><strong>Optional (string)</strong><br>Localized name corresponding to translated language.</p><p>Name: Le product</p><p>Language: FR</p></td></tr><tr><td><code>Translations.PromotionTranslation.Language</code></td><td><strong>Optional (string)</strong><br>Language for localization.</td></tr><tr><td><code>Sources</code></td><td><strong>Optional (string array)</strong><br>Array of strings defining the sale source through the SRC parameter.</td></tr><tr><td><code>PublishToAffiliatesNetwork</code></td><td><p><strong>Optional (integer)</strong><br>1 - make promotion available in the Affiliates Network</p><p>0 - keep promotion unavailable for the Affiliates Network</p></td></tr><tr><td><code>ApplyRecurring</code></td><td><p><strong>Required (string)</strong></p><p>Choose whether to apply the discount to renewal orders. Possible values:</p><ul><li><strong>NONE</strong></li><li><strong>ALL</strong></li><li><strong>CUSTOM</strong></li></ul></td></tr><tr><td><code>RecurringChargesNumber</code></td><td><strong>Optional (integer)</strong><br>If <code>ApplyRecurring</code> is set to <strong>CUSTOM</strong>, you can offer discounts for a number of recurring billing charges beyond the initial purchase.</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.2checkout.com/soap-api-reference/soap-api-6.0/api-requests/promotions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.