Place orders with dynamic product information

Last updated: 18-Feb-2025

Rate this article:

Overview

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.

Supported payment methods

Credit/Debit cards: Visa, Visaelectron, MasterCard, Maestro, Amex, Discover, Dankort, Cartebleue, JCB. 2Checkout supports local Brazilian cards.
PayPal
Free orders (no payment information required).
2Pay.js

How to test?

Place test orders with dynamic product information by following the instructions from this article.

Requirements

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.

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.

Parameters

Parameters								Type/Description
Currency								Optional (string)
								The currency ISO code for the payment - ISO 4217. Example: “usd.”
Country								Optional (string)
								Shopper country. ISO 3166 two-letter code. Example: “us.”
Language								Optional (string)
								ISO 639-1 two-letter code. Language used for the purchase process. Example: “en.”
ExternalReference								Optional (string)
								Set external reference identifiers for orders. Enables you to replicate the functionality of the REF 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.
Source								Optional (string)
								The link source for the sales. Enables you to replicate the functionality of the SRC (separate link identifier) parameter when included into Buy Links. Use the SRC parameter to track sale sources. Maximum length 255 characters.
CustomerReference								Optional (Int)
								System-generated 2Checkout customer reference. Aggregate subscriptions under the same Customer account by adding the AV_CUSTOMERID (case sensitive) parameter to buy links. The 2Checkout system generates default customer numerical (integer) IDs (AV_CUSTOMERID) automatically for all orders containing products that feature subscriptions.
MachineId								Optional (string)
								Unique, system generated code for each unique customer, identifying returning customers.
Items								Required (array of objects)
								Details below.
			Code					Optional (string)
								Should be send as NULL. Any other value will be ignored.
			Quantity					Required (integer)
								Number of units
			isDynamic					Required (bool)
								Send true for creating orders with dynamic order information.
			Tangible					Required (bool)
								Send false for product delivered electronically.
			PurchaseType					Required (string)
								Purchase types available are: PRODUCT, TAX, SHIPPING and COUPON.
			PriceOptions					Optional (array of objects)
								Array of price option groups.
				Name				Optional (string)
								Name of the pricing option group. Mandatory for dynamic products.
				Options				Optional (array of objects)
								Array of pricing options.
					Name			Optional (string)
								Pricing option name. Mandatory for dynamic products.
					Value			Optional (string)
								Pricing option code. Mandatory for catalog products.
					Surcharge			Optional (double)
								Surcharge of the pricing option. For renewal orders, the renewal price includes the pricing option surcharge from the initial order. Mandatory for dynamic products.
			RecurringOptions					Optional (Object)
								Contains recurring options.
					CycleLength			Optional (int)
								The length of the recurring billing cycle.
					CycleUnit			Optional (string)
								Unit of measuring billing cycles (years, months).
					CycleAmount			Optional (int)
								The amount to be billed on each renewal.
					ContractLength			Optional (int)
								The contact length for which the recurring option will apply.
					ContractUnit			Optional
								Unit of measuring contact length (years, months).
			Price					Required (Object)
								Details below.
					Amount			Required (Int)
								Amount of the product.
					Type			Optional (string)
								Send "CUSTOM" for dynamic pricing.
			Trial					Optional (Object) – Can be NULL
								Details below.
					Period			Optional (integer)
								The length of the trial subscription lifetime in days.
					Price			Optional (double)
								Total trial price in the payment currency before 2Checkout deducts any taxes, discounts, etc.
			AdditionalFields					Optional (array of objects) – Can be NULL
					AdditionalFieldSet			Optional (Object) – Can be NULL
								Details below
							Code	Optional (string)
								Identifier code for the additional field.
							Text	Optional (string)
								Text displayed in the additional field.
							Value	Optional (string)
								Additional field value.
			SubscriptionStartDate					Optional (string)
								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. Send empty or NULL to activate subscriptions on the same date when customers purchase them. 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.
BillingDetails								Required (Object)
								Details below.
	Person							Object
								Details below.
		FirstName						Required (string)
								Shopper name.
		LastName						Required (string)
								Shopper surname.
		CountryCode						Optional (string)
								Shopper country. ISO 3166 two-letter code.
		State						String/Optional – Required for US, Canada, Brazil, Turkey, India and Romania
								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.
		City						Optional (string)
								Shopper city.
		Address1						Optional (string)
								Shopper address.
		Address2						Optional (string)
								Shopper address.
		Zip						Optional (string)
								ZIP/ Postal code.
		Email						Optional (string)
								Shopper email address.
		Phone						Optional (string)
								Shopper phone number. Mandatory when you set Brazil as the Billing Country. Can be NULL.
		Company						Optional (string)
								Company name. Can be null for end users. When present, you also need to provide the FiscalCode.
		TaxExemptionId						Optional (string)
								Tax Exempt Certification id used to deduct taxes for US orders Example: `1b80eecc349v`
	FiscalCode							Optional (string) – Required for Brazil
								• 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 setPaymentDetails. When present, you also need to provide the Company name. • Mandatory when you set Brazil as the Billing Country. For Brazilian customers it represents the Fiscal Code (CPF/CNPJ). • Mandatory when you set India as the Billing Country, and purchase is made by a Company. • Can be NULL for end users.
DeliveryDetails								Required (Object)
								Details below.
	Person							Object
								Details below.
		FirstName						Required (string)
								Shopper name from the delivery details.
		LastName						Required (string)
								Shopper surname from the delivery details.
		CountryCode						Optional (string)
								Shopper country. ISO 3166 two-letter code from the delivery details.
		State						String/Optional – Required for US, Canada, Brazil, Turkey, India and Romania
								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.
		City						Optional (string)
								Shopper city from the delivery details.
		Address1						Optional (string)
								Shopper address from the delivery details.
		Address2						Optional (string)
								Shopper address from the delivery details.
		Zip						Optional (string)
								ZIP/ Postal code from the delivery details.
		Email						Optional (string)
								Shopper email address from the delivery details.
		Phone						Optional (string)
								Shopper phone number from the delivery details. Mandatory when you set Brazil as the Billing Country. Can be NULL.
		Company						Optional (string)
								Company name from the delivery details. Can be null for end users. When present, you also need to provide the FiscalCode.
PaymentDetails								Required (Object)
								Adapt this object to the desired payment method.
	Type							Required (string)
								The payment method: CC (credit/debit card - including local Brazilian cards). ENCRYPTED_PAYMENT_DATA (client-side encryption) PAYPAL PAYPAL_EXPRESS CCNOPCI(credit/debit card for non-PCI certified merchants). TEST (for test orders). PREVIOUS_ORDER(place new orders using the reference of a previous order). EXISTING_PAYMENT_DATA (use a card one of your customers already used to purchase from your account). WIRE – the placeOrder response includes Wire payment details. CHECK – the placeOrder response includes Check payment details. WE_CHAT_PAY (for WeChat payments). IDEAL (for iDEAL payments). PURCHASEORDER - use for orders with POs. FREE – for 0 value orders for which you’re not requiring customers to provide payment details. EES_TOKEN_PAYMENT (2Pay.js)
	Currency							Required (string)
								The currency ISO code for the payment - ISO 4217. Example: “usd.”
	RecurringEnabled							Optional (boolean)
								true – shopper checks the auto renewal checkbox and 2Checkout charges subscription renewals using a recurring billing process. false – shopper doesn’t check the auto renewal checkbox.
	PaymentMethod							Optional (object)
								Object structure and parameters differ according to payment method selected and API method (placing orders (POST) vs. retrieving order data (GET)). NULL for 0 value orders for which you’re not requiring customers to enter payment details.
				CardPayment				Optional (object)
								Details below.
						CardNumber		Required (string)
								The credit/debit card number.
						CardType		Required (string)
								visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo
						ExpirationYear		Required (string)
								The year in which the card expires.
						ExpirationMonth		Required (string)
								The month in which the card expires.
						HolderName		Required (string)
								Card holder name.
						Vendor3DSReturnURL		Required (string)
								URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized.
						Vendor3DSCancelURL		Required (string)
								URL address to which customers are redirected if the 3DS details were not validated or the order could not be authorized.
						CCID		Optional (string)
								Credit Card Identification - an extra ID printed on the card, usually a 3-4 digit number, the CVC2/CVV2.
						HolderNameTime		Optional (float)
								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. Can be NULL, but not a negative number.
						CardNumberTime		Optional (float)
								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. Can be NULL, but not a negative number.
						InstallmentsNumber		Optional (Int)
								Number of installments. Available only when customers un Brazil pay with Visa or MasterCard using Brazilian Real as the order currency. Use 1 or exclude the parameter for full payments.
				PayPalExpress				Optional (object)
								Details below.
						Email		Optional (string)
								Email address customers use for their PayPal account.
						ReturnURL		Optional (string)
								The PayPal Express Checkout redirect URL returned by calling the getPayPalExpressCheckoutRedirectURL method. The return URL is the page on your website to which PayPal redirects your buyer's browser after the buyer logs in to PayPal and approves the payment. Typically, this is a secure page (https://...) on your site.
						CancelURL		Optional (string)
								The cancel URL is the page on your website to which PayPal redirects your buyer's browser if the buyer does not approve the payment. Typically, this is the secure page (https://...) on your site from which you redirected the buyer to PayPal.
				PreviousOrder				Optional (Object)
								Details below.
						RefNo		Optional (string)
								Order reference a previous purchase that reached the Approved/Complete status. You can use order for which customers paid with credit/debit cards or with PayPal. The status of order should be AUTHRECEIVED or COMPLETE. Check the validity of references with the isValidOrderReference method. The 2Checkout system blocks you from using references for fraudulent or potentially fraudulent orders.
				PurchaseOrderPaymentDetails				Optional (Object)
								Details below.
						InternalPONumber		Optional (string)
								Identifier that business customers use internally in their organization to track and manage Purchase Orders (PO). Can be NULL.
						AutoApprove		Optional (boolean)
								TRUE - requires activation of the PO AutoApprove package (If the package is inactive 2Checkout returns an error). Please contact 2Checkout. When AutoApprove is TRUE, 2Checkout no longer requires that business customers upload a PO document. As such, PO orders are automatically approved for your account, without a PO doc. 2Checkout sets the PURCHASE_PENDING status for auto-approved PO orders. FALSE - Default. Send this if the PO AUtoApprove package is not available for your account. 2Checkout uses the same flow as cart purchases with Purchase Orders for business customers placing orders with POs via API. This means that customers receive the same emails as if they made the purchase using the cart and need to update the PO document, which is reviewed by 2Checkout and that you need to approve. 2Checkout sets the AVAITING_UPLOAD status for POs andUnfinished for their orders. Can be NULL.
				WE_CHAT_PAY				Optional (string)
								Details below
						ReturnURL		Optional (string)
								The return URL is the page to which your customers are redirected after their successful payment.
						CancelURL		Optional (string)
								The cancel URL is the page to which your customers are redirected after their failed payment attempt.
				IDEAL				Optional (string)
								Details below
						ReturnURL		Optional (string)
								The return URL is the page to which your customers are redirected after their successful payment.
						CancelURL		Optional (string)
								The cancel URL is the page to which your customers are redirected after their failed payment attempt.
						BankCode		Required (string)
								String contains the SWIFT code of the bank, the plus sign "+", and the first 3 characters from the bank name. E.q.: in the case of Rabobank, code parameter is "RABONL2U+RAB".
				EXISTING_PAYMENT_DATA				Optional (Object)
								By using EXISTING_PAYMENT_DATA you no longer require shoppers to enter any payment details.
						TransientToken		Optional (string)
								Returned as a part of the process of retrieving customer information by SSOToken.
	CustomerIP							Optional (string)
								Shopper IP.
Promotions								Optional (Array of strings)
								Array of promotion codes.
LocalTime								Optional (string)
								Local shopper time in the following format: Y-m-d H:i:s. This parameter can impact the fraud score of an order when it's missing, NULL or incorrectly formatted.

Rate this article:

Global eCommerce

In-Person Payments

Business Tools

Petroleum & Convenience

APIs

Place orders with dynamic product information