# Place orders with dynamic product information

Use this object to create new orders and collect payments from shoppers using products with dynamic information. 

Purchase types available are **PRODUCT**, **TAX**, **SHIPPING,** and **COUPON**. The surcharge defined in the pricing option is used for calculating the **order renewal price**, when applicable.

You can find a list of common errors that may arise when using the **placeOrder** call via APIv6 [here](https://verifone.cloud/docs/2checkout/API-Integration/JSON-RPC_API_6.0/API-6.0-Error-Codes).

{% hint style="info" %}
This functionality is available only for merchants on the 2Sell and 2Subscribe accounts (PSP business model), for orders that are placed both through ConvertPlus/InLine ordering engines and API calls and for 2Monetize accounts (MoR business model) only for orders placed through API calls.
{% endhint %}

## Supported payment methods

1. [Credit / debit cards](/soap-api-reference/soap-api-6.0/api-requests/place-orders-with-dynamic-product-information/use-credit-cards.md): Visa, Visa electron, MasterCard, Maestro, Amex, Discover, Dankort, Carte Bleue, JCB. 2Checkout supports local Brazilian cards.
2. [PayPal](/soap-api-reference/soap-api-6.0/api-requests/place-orders-with-dynamic-product-information/use-paypal.md)
3. [Free orders](/soap-api-reference/soap-api-6.0/api-requests/place-orders-with-dynamic-product-information/use-free-orders.md) (no payment information required).
4. [2Pay.js](/2checkout-apis/2checkout-apis/2pay.js-payments-solution-integration-guide/use-cases/place-orders-via-api-using-a-2pay.js-token.md)

<details>

<summary><strong>How to test?</strong></summary>

Place test orders with dynamic product information by following the instructions from [this](/soap-api-reference/soap-api-6.0/api-requests/place-orders-with-dynamic-product-information/place-test-orders.md) article.

</details>

## Requirements

The product code must be sent as **null**. The order currency must **match** with the payment currency, otherwise, an error is thrown. The `isDynamic` parameter of the `Items` object must be **true**.

For credit card orders placed using API 5.0 or newer versions, you need to pass through additional parameters that support the 3D Secure flow. 3D Secure works by redirecting customers to pages provided by their banks, where they need to enter additional security tokens or passwords to trigger the completion of the charge. By using 3D Secure, you get additional protection from liability for fraudulent card payments, with customers having to go through an extra layer of authentication.

Send the following parameters as part of the `PaymentMethod` object:

<table><thead><tr><th width="194.7999267578125">Parameter</th><th>Type / Description</th></tr></thead><tbody><tr><td><code>Vendor3DSReturnURL</code></td><td><strong>Required (string)</strong><br>URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized.</td></tr><tr><td><code>Vendor3DSCancelURL</code></td><td><strong>Required (string)</strong><br>URL address to which customers are redirected if the 3DS details were not validated or the order could not be authorized.</td></tr><tr><td><code>WSOrder</code></td><td><strong>String (optional)</strong><br>The WSOrder parameter is used to control the website URL displayed in the email messages shoppers receive after they place an order. By default, 2Checkout reports the URL set as Homepage in the Account information area. Adding WSOrder to the buy-links for your products will cause the optional website address set by using the parameter to override and replace the Homepage URL in the email notifications sent to customers. The behavior is similar to the WS_ORDER parameter supported on checkout/cart pages and described <a href="https://verifone.cloud/docs/2checkout/Documentation/07Commerce/Checkout-links-and-options/Manage-store-URLs-for-shopper-emails">here</a>.</td></tr></tbody></table>

### **Limitations**

Placing an order with both catalog and dynamic product information **is not possible**. Recurring options can be set only for purchase type **PRODUCT** and **TAX**.

For **MoR business model**, the purchase type can only be **PRODUCT** and **COUPON**.&#x20;

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

<table><thead><tr><th width="428.4000244140625">Parameter</th><th>Type / Description</th></tr></thead><tbody><tr><td><code>Currency</code></td><td><strong>Optional (string)</strong><br>The currency ISO code for the payment - ISO 4217. Example: “usd.”</td></tr><tr><td><code>Country</code></td><td><strong>Optional (string)</strong><br>Shopper country. ISO 3166 two-letter code. Example: “us.”</td></tr><tr><td><code>Language</code></td><td><strong>Optional (string)</strong><br>ISO 639-1 two-letter code. Language used for the purchase process. Example: “en.”</td></tr><tr><td><code>ExternalReference</code></td><td><strong>Optional (string)</strong><br>Set external reference identifiers for orders. Enables you to replicate the functionality of the <code>REF</code> parameter included into Buy Links. Maximum 100 characters. If there is a need for longer references, you can apply an md5 hash for any string value, resulting in a 32 characters string. You can verify the hash after the order notification, on the client side.</td></tr><tr><td><code>Source</code></td><td><p><strong>Optional (string)</strong><br>The link source for the sales. Enables you to replicate the functionality of the <strong>SRC</strong> (separate link identifier) parameter when included into Buy Links. Use the SRC parameter to track sale sources.</p><p>Maximum length 255 characters.</p></td></tr><tr><td><code>CustomerReference</code></td><td><strong>Optional (Int)</strong><br>External customer ID you can attach to the customer.</td></tr><tr><td><code>Affiliate</code></td><td><strong>Optional (object)</strong></td></tr><tr><td><code>Affiliate.AffiliateCode</code></td><td><strong>Required (string)</strong><br>The affiliate unique code (as returned by the affiliates API methods).</td></tr><tr><td><code>Affiliate.AffiliateSource</code></td><td><strong>Optional (string)</strong><br>The affiliate source.</td></tr><tr><td><code>MachineId</code></td><td><strong>Optional (string)</strong><br>Unique, system generated code for each unique customer, identifying returning customers.</td></tr><tr><td><code>Items</code></td><td><strong>Required (array of objects)</strong><br>Details below. </td></tr><tr><td><code>Items.Code</code></td><td><strong>Optional (string)</strong><br>Should be <strong>sent as NULL</strong>. Any other value is ignored.</td></tr><tr><td><code>Items.Quantity</code></td><td><strong>Required (integer)</strong><br>Number of units purchased.</td></tr><tr><td><code>Items.IsDynamic</code></td><td><strong>Required (bool)</strong><br>Send <strong>TRUE</strong> for orders with dynamic product information.</td></tr><tr><td><code>Items.Tangible</code></td><td><p><strong>Required (bool)</strong></p><p>Possible values:</p><ul><li><strong>FALSE</strong> for products delivered electronically.</li><li><strong>TRUE</strong> for tangible products, that require physical delivery.</li></ul></td></tr><tr><td><code>Items.PurchaseType</code></td><td><p><strong>Required (string)</strong></p><p>Purchase types available are:</p><ul><li><strong>PRODUCT -</strong> item purchased by the customer. Can have pricing options and recurring properties attached.</li><li><strong>TAX -</strong> additional handling fee added to the purchase.</li><li><strong>SHIPPING -</strong> shipping fee applied to purchase.</li><li><strong>COUPON -</strong> amount deducted from total order price<strong>. Send positive values.</strong></li></ul></td></tr><tr><td><code>Items.PriceOptions</code></td><td><strong>Optional (array of objects)</strong><br>Array of price option groups.</td></tr><tr><td><code>Items.PriceOptions.Name</code></td><td><strong>Optional (string)</strong><br>Name of the pricing option group.</td></tr><tr><td><code>Items.PriceOptions.Options</code></td><td><strong>Optional (array of objects)</strong><br>Array of pricing options.</td></tr><tr><td><code>Items.PriceOptions.Options.Name</code></td><td><strong>Optional (string)</strong><br>Pricing option name.</td></tr><tr><td><code>Items.PriceOptions.Options.Value</code></td><td><strong>Optional (string)</strong><br>Pricing option code.</td></tr><tr><td><code>Items.PriceOptions.Options.Surcharge</code></td><td><strong>Optional (double)</strong><br>Surcharge of the pricing option. For renewal orders, the renewal price includes the pricing option surcharge from the initial order. </td></tr><tr><td><code>Items.RecurringOptions</code></td><td><strong>Optional (Object)</strong><br>Contains recurring options.</td></tr><tr><td><code>Items.RecurringOptions.CycleLenght</code></td><td><strong>Optional (int)</strong><br>The length of the recurring billing cycle.</td></tr><tr><td><code>Items.RecurringOptions.CycleUnit</code></td><td><strong>Optional (string)</strong><br>Unit of measuring billing cycles (years, months).</td></tr><tr><td><code>Items.RecurringOptions.CycleAmount</code></td><td><strong>Optional (int)</strong><br>The amount to be billed on each renewal.</td></tr><tr><td><code>Items.RecurringOptions.ContractLenght</code></td><td><strong>Optional (int)</strong><br>The contact length for which the recurring option will apply.</td></tr><tr><td><code>Items.RecurringOptions.ContractUnit</code></td><td><strong>Optional</strong><br>Unit of measuring contact length (years, months).</td></tr><tr><td><code>Items.Name</code></td><td><strong>Required (string)</strong><br>Product name.</td></tr><tr><td><code>Items.Price</code></td><td><strong>Required (object)</strong><br>Details below.</td></tr><tr><td><code>Items.Price.Amount</code></td><td><strong>Required (int)</strong><br>Amount of the product.</td></tr><tr><td><code>Items.Price.Type</code></td><td><strong>Optional (string)</strong><br>Send "<strong>CUSTOM</strong>" for dynamic pricing.</td></tr><tr><td><code>Items.ProductTaxCategoryUUID</code></td><td><p><strong>Required (String)</strong><br>The UUID of the tax category used for the product. Must be a category existent on your account.</p><p>Must be passed as NULL on PSP business model.</p></td></tr><tr><td><code>Items.PriceType</code></td><td><p><strong>Optional (String)</strong><br>Possible values:</p><ul><li><strong>GROSS</strong> - with taxes included</li><li><strong>NET</strong> - without taxes</li></ul><p>If parameter is not sent, the default PriceType applied is GROSS.</p></td></tr><tr><td><code>Items.Trial</code></td><td><p><strong>Optional (Object)</strong></p><p><strong>Can be NULL</strong><br>Details below.</p></td></tr><tr><td><code>Items.Trial.Period</code></td><td><strong>Optional (integer)</strong><br>The length of the trial subscription lifetime in days.</td></tr><tr><td><code>Items.Trial.Price</code></td><td><strong>Optional (double)</strong><br>Total trial price in the payment currency before 2Checkout deducts any taxes, discounts, etc.</td></tr><tr><td><code>Items.AdditionalFields</code></td><td><p><strong>Optional (array of objects)</strong></p><p><strong>Can be NULL</strong></p></td></tr><tr><td><code>Items.AdditionalFields.AdditionalFieldSet</code></td><td><p><strong>Optional (Object)</strong></p><p><strong>Can be NULL</strong><br>Details below</p></td></tr><tr><td><code>Items.AdditionalFields.AdditionalFieldSet.Code</code></td><td><strong>Optional (string)</strong><br>Identifier code for the additional field.</td></tr><tr><td><code>Items.AdditionalFields.AdditionalFieldSet.Text</code></td><td><strong>Optional (string)</strong><br>Text displayed in the additional field.</td></tr><tr><td><code>Items.AdditionalFields.AdditionalFieldSet.Value</code></td><td><strong>Optional (string)</strong><br>Additional field value.</td></tr><tr><td><code>Items.SubscriptionStartDate</code></td><td><p><strong>Optional (string)</strong><br>Specify the date time stamp when the subscription becomes active. Format 2016-07-02 22:22:22 (YYYY-MM-DD HH:mm:ss). Available for JSON-RPC and REST.</p><p>Send empty or NULL to activate subscriptions on the same date when customers purchase them.</p><p>You can exclude HH:mm:ss when sending the date and include only YYYY-MM-DD. In this case, 2Checkout uses 00:00:01. Default time zone GMT+02:00.</p></td></tr><tr><td><code>BillingDetails</code></td><td><strong>Required (Object)</strong><br>Details below. </td></tr><tr><td> <code>BillingDetails.FirstName</code></td><td><strong>Required (string)</strong><br>Shopper name.</td></tr><tr><td><code>BillingDetails.LastName</code></td><td><strong>Required (string)</strong><br>Shopper surname.</td></tr><tr><td><code>BillingDetails.CountryCode</code></td><td><strong>Required (string)</strong><br>Shopper country. ISO 3166 two-letter code.</td></tr><tr><td><code>BillingDetails.State</code></td><td><strong>String/Optional</strong> – Required for US, Canada, Brazil, Turkey, India and Romania<br>The state in the shopper's country. Mandatory when you set the Billing Country to US, Canada, Brazil, Turkey, India and Romania. Use case insensitive utf8 strings for the full name, or just the two-letter code.</td></tr><tr><td><code>BillingDetails.City</code></td><td><strong>Required (string)</strong><br>Shopper city.</td></tr><tr><td><code>BillingDetails.Address1</code></td><td><strong>Required (string)</strong><br>Shopper address.</td></tr><tr><td><code>BillingDetails.Address2</code></td><td><strong>Optional (string)</strong><br>Shopper address.</td></tr><tr><td><code>BillingDetails.Zip</code></td><td><strong>Required (string)</strong><br>ZIP/ Postal code.</td></tr><tr><td><code>BillingDetails.Email</code></td><td><strong>Required (string)</strong><br>Shopper email address.</td></tr><tr><td><code>BillingDetails.Phone</code></td><td><strong>Optional (string)</strong><br>Shopper phone number. Mandatory when you set Brazil as the Billing Country. Can be NULL.</td></tr><tr><td><code>BillingDetails.Company</code></td><td><strong>Optional (string)</strong><br>Company name. Can be null for end users. When present, you also need to provide the FiscalCode.</td></tr><tr><td><code>BillingDetails.FiscalCode</code></td><td><p><strong>Optional (string) –</strong> Required for Brazil<br>• For companies, it needs to be the VAT ID. 2Checkout will validate the value provided and throw an error if the VAT ID is invalid/incorrect when calling <strong>setPaymentDetails</strong>. When present, you also need to provide the <strong>Company name</strong>.</p><p>• Mandatory when you set Brazil as the Billing Country. For Brazilian customers it represents the Fiscal Code (CPF/CNPJ).</p><p>• Mandatory when you set India as the Billing Country, and purchase is made by a Company.</p><p>• Can be NULL for end users.</p></td></tr><tr><td><code>BillingDetails.TaxExemptionId</code></td><td><strong>Optional (string)</strong><br>Tax Exempt Certification id used to deduct taxes for US orders.<br>Example: <code>1b80eecc349v</code></td></tr><tr><td><code>DeliveryDetails</code></td><td><strong>Required (Object)</strong><br>Details below. </td></tr><tr><td><code>DeliveryDetails.FirstName</code></td><td><strong>Required (string)</strong><br>Shopper name from the delivery details.</td></tr><tr><td><code>DeliveryDetails.LastName</code></td><td><strong>Required (string)</strong><br>Shopper surname from the delivery details.</td></tr><tr><td><code>DeliveryDetails.CountryCode</code></td><td><strong>Optional (string)</strong><br>Shopper country. ISO 3166 two-letter code from the delivery details.</td></tr><tr><td> <code>DeliveryDetails.State</code></td><td><strong>String/Optional</strong> – Required for US, Canada, Brazil, Turkey, India and Romania<br>The state in the shopper's country. Mandatory when you set the Billing Country to US, Canada, Brazil, Turkey, India and Romania. Use case insensitive utf8 strings for the full name, or just the two-letter code.</td></tr><tr><td><code>DeliveryDetails.City</code></td><td><strong>Optional (string)</strong><br>Shopper city from the delivery details.</td></tr><tr><td><code>DeliveryDetails.Address1</code></td><td><strong>Optional (string)</strong><br>Shopper address from the delivery details.</td></tr><tr><td><code>DeliveryDetails.Address2</code></td><td><strong>Optional (string)</strong><br>Shopper address from the delivery details.</td></tr><tr><td><code>DeliveryDetails.Zip</code></td><td><strong>Optional (string)</strong><br>ZIP/ Postal code from the delivery details.</td></tr><tr><td><code>DeliveryDetails.Email</code></td><td><strong>Optional (string)</strong><br>Shopper email address from the delivery details.</td></tr><tr><td><code>DeliveryDetails.Phone</code></td><td><strong>Optional (string)</strong><br>Shopper phone number from the delivery details. Mandatory when you set Brazil as the Billing Country. Can be NULL.</td></tr><tr><td><code>DeliveryDetails.Company</code></td><td><strong>Optional (string)</strong><br>Company name from the delivery details. Can be null for end users. When present, you also need to provide the FiscalCode.</td></tr><tr><td><code>DeliveryInformation</code></td><td><p><strong>Object / Optional</strong></p><p>For products that require physical delivery, use this object to send the shipping method.</p></td></tr><tr><td><code>DeliveryInformation.ShippingMethod</code></td><td><p><strong>Object</strong></p><p>Details below</p></td></tr><tr><td><code>DeliveryInformation.ShippingMethod.Code</code></td><td> <strong>String</strong><br>System-generated identified for your shipping method configuration.</td></tr><tr><td><code>PaymentDetails</code></td><td><strong>Required (Object)</strong><br>Adapt this object to the desired payment method.</td></tr><tr><td><code>PaymentDetails.Type</code></td><td><p><strong>Required (string)</strong></p><p>The payment method:</p><ul><li><strong>CC</strong> (credit/debit card - including local Brazilian cards).</li><li><strong>ENCRYPTED_PAYMENT_DATA</strong> (client-side encryption)</li><li><strong>PAYPAL</strong></li><li><strong>PAYPAL_EXPRESS</strong></li><li><strong>TEST</strong> (for test orders).</li><li><strong>PREVIOUS_ORDER</strong>(place new orders using the reference of a previous order).</li><li><strong>EXISTING_PAYMENT_DATA</strong> (use a card one of your customers already used to purchase from your account).</li><li><strong>WIRE</strong> – the placeOrder response includes Wire payment details.</li><li><strong>CHECK</strong> – the placeOrder response includes Check payment details.</li><li><strong>WE_CHAT_PAY</strong> (for WeChat payments).</li><li><strong>IDEAL</strong> (for iDEAL payments).</li><li><strong>PURCHASEORDER</strong> - use for orders with POs.</li><li><strong>FREE –</strong> for 0 value orders for which you’re not requiring customers to provide payment details.</li><li><strong>EES_TOKEN_PAYMENT</strong> (2Pay.js)</li><li><strong>GOOGLE PAY</strong></li></ul></td></tr><tr><td><code>PaymentDetails.Currency</code></td><td><strong>Required (string)</strong><br>The currency ISO code for the payment - ISO 4217. Example: “usd.”</td></tr><tr><td><code>PaymentDetails.RecurringEnabled</code></td><td><p><strong>Optional (boolean)</strong><br><strong>true</strong> – shopper checks the auto-renewal checkbox and 2Checkout charges subscription renewals using a recurring billing process.</p><p><strong>false</strong> – shopper doesn’t check the auto-renewal checkbox.</p></td></tr><tr><td><code>PaymentDetails.PaymentMethod</code></td><td><p><strong>Optional (object)</strong><br>Object structure and parameters differ according to payment method selected and API method (placing orders (POST) vs. retrieving order data (GET)).</p><p><strong>NULL</strong> for 0 value orders for which you’re not requiring customers to enter payment details.</p></td></tr><tr><td><code>PaymentDetails.PaymentMethod.CardPayment</code></td><td><strong>Optional (object)</strong><br>Details below. </td></tr><tr><td><code>PaymentDetails.PaymentMethod.CardPayment.CardNumber</code></td><td><strong>Required (string)</strong><br>The credit/debit card number.</td></tr><tr><td><code>PaymentDetails.PaymentMethod.CardPayment.CardType</code></td><td><strong>Required (string)</strong><br>visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo</td></tr><tr><td><code>PaymentDetails.PaymentMethod.CardPayment.ExpirationYear</code></td><td><strong>Required (string)</strong><br>The year in which the card expires.</td></tr><tr><td><code>PaymentDetails.PaymentMethod.CardPayment.ExpirationMonth</code></td><td><strong>Required (string)</strong><br>The month in which the card expires.</td></tr><tr><td><code>PaymentDetails.PaymentMethod.CardPayment.HolderName</code></td><td><strong>Required (string)</strong><br>Cardholder name.</td></tr><tr><td><code>PaymentDetails.PaymentMethod.CardPayment.Vendor3DSReturnURL</code></td><td><strong>Required (string)</strong><br>URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized.</td></tr><tr><td><code>PaymentDetails.PaymentMethod.CardPayment.Vendor3DSCancelURL</code></td><td><strong>Required (string)</strong><br>URL address to which customers are redirected if the 3DS details were not validated or the order could not be authorized.</td></tr><tr><td><code>PaymentDetails.PaymentMethod.CardPayment.CCID</code></td><td><strong>Optional (string)</strong><br>Credit Card Identification - an extra ID printed on the card, usually a 3-4 digit number, the CVC2/CVV2.</td></tr><tr><td><code>PaymentDetails.PaymentMethod.CardPayment.HolderNameTime</code></td><td><p><strong>Optional (float)</strong><br>The interval of time in seconds in which shoppers enter their name in the HolderName field. An abnormally short interval is usually a red flag for fraud attempts.</p><p>Can be NULL, but not a negative number.</p></td></tr><tr><td><code>PaymentDetails.PaymentMethod.CardPayment.CardNumberTime</code></td><td><p><strong>Optional (float)</strong></p><p>The interval of time in seconds in which shopper enter their card number in the CardNumber field. An abnormally short interval is usually a red flag for fraud attempts.</p><p>Can be NULL, but not a negative number.</p></td></tr><tr><td><code>PaymentDetails.PaymentMethod.CardPayment.InstallmentsNumber</code> </td><td><strong>Optional (Int)</strong><br>Number of installments. Available only when customers un Brazil pay with Visa or MasterCard using Brazilian Real as the order currency. Use <strong>1</strong> or exclude the parameter for full payments. </td></tr><tr><td><code>PaymentDetails.CustomerIP</code></td><td><strong>Optional (string)</strong><br>Shopper IP.</td></tr><tr><td><code>Promotions</code></td><td><strong>Optional (Array of strings)</strong><br>Array of promotion codes.</td></tr><tr><td><code>LocalTime</code></td><td><p><strong>Optional (string)</strong><br>Local shopper time in the following format: Y-m-d H:i:s.</p><p>This parameter can impact the fraud score of an order when it's missing, NULL or incorrectly formatted.</p></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/place-orders-with-dynamic-product-information.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.