Build the order object to place orders

An order is the most common way to collect payment from your shoppers and is at the heart of the 2Checkout platform.

The Order object

While the full order object can be very extensive (the full object structure can be found here), the minimum information needed for placing an order is the billing details, the payment details, and the order items.

The Billing Details

The billing details are mandatory information when placing an order, and they are used in the processing of an order, as they appear on the invoice of the order.

Parameter	Type / Description
FirstName	Required (string) Shopper' name or their first name
LastName	Required (string) Shopper' surname or their last name
CountryCode	Required (string) Shopper's country, ISO 3166 two-letter code formatted.
State	Required (string) The state in the shopper's country. Mandatory when the billing country is the USA, Turkey, India, or Romania. Use case insensitive UTF8 strings for the full name, or just the two-letter code.
City	Required (string) Shopper's city.
Address1	Required (string) Shopper's address.
Address2	Optional (string) Shopper's address, when additional information is needed.
Zip	Required (string) Shopper's address zip/postal code.
Email	Required (string) Shopper's email address.
Phone	Optional (string) Shopper's phone number.
Company	Optional (string) Company name, can be null for end users. When provided, FiscalCode needs to be also present.
FiscalCode	Optional (string) Can be NULL for end-users; 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. Exceptions: Mandatory when the Billing Country is set to Brazil. For Brazilian customers, it represents the Fiscal Code (CPF/CNPJ). Mandatory when the Billing Country is set to India, and the purchase is made by a company.

The payment details

The payment details are used in processing the order and contain information specific for the payment method used. For example, for a Credit Card payment, this is where you would be sending the Card Holder Name, Card Number, Card Type, Expiration Date, and CVV.

Due to the wide range of payment methods supported in the 2Checkout API, the payment details object can differ extensively between payment methods.

The various payment details objects will be explained and detailed in the Payments flow article.

The items

The items object required when placing an order is an array of item objects. The items are the products that the shopper is buying when placing the order.

The 2Checkout API supports either catalog or dynamic products. Mixed orders, with both catalog and dynamic products is not supported.

For each product in the item list, the quantity is optional and can be left out. In this case, the quantity will be set to 1 by default.

Catalog products

Catalog products are products that you have defined in your product catalog, either via your Merchant Control Panel or via API.

The minimum information needed in order to place an order with catalog products, via API, is the alphanumeric product code (not to be confused with the product id).

The JSON for this would look like:

"Items":[
      {
         "Code":"5DCB30C6B0",
         "Quantity":1
      }
   ]

The full list of fields available for catalog products can be found here.

The full JSON for an order with catalog products would look like:

{
   "Language":"en",
   "Country":"US",
   "CustomerIP":"10.10.10.10",
   "Source":"Website",
   "ExternalCustomerReference":"externalCustomerId",
   "Currency":"USD",
   "MachineId":"123456789",
   "Items":[
      {
         "Code":"5DCB30C6B0",
         "Quantity":1
      }
   ],
   "BillingDetails":{
      "FirstName":"Customer First Name",
      "LastName":"Customer Last Name",
      "CountryCode":"US",
      "State":"California",
      "City":"San Francisco",
      "Address1":"Example Street",
      "Zip":"90210",
      "Email":"[email protected]"
   },
   "PaymentDetails":{
      "Type":"TEST",
      "Currency":"USD",
      "PaymentMethod":{
         "CardNumber":"4111111111111111",
         "CardType":"VISA",
         "ExpirationYear":"2023",
         "ExpirationMonth":"12",
         "HolderName":"Red Doe",
         "CCID":"123",
         "Vendor3DSReturnURL":"http:\/\/yoursuccessurl.com",
         "Vendor3DSCancelURL":"http:\/\/yourcancelurl.com"
      },
      "CustomerIP":"10.10.10.10"
   }
}

Dynamic products

Dynamic products are products generated on the fly when placing orders.

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.

The minimum information needed to place an order with dynamic products, via API, is:

Parameter	Type / Description
Code	Required (string) Always NULL for dynamic products.
IsDynamic	Required (boolean) Boolean flag that signals a dynamic product.
PurchaseType	Required (string) The type of product that is being used, possible values: - PRODUCT - SHIPPING - TAX - COUPON
Tangible	Required (boolean) Defines the product delivery type - either a digital product (tangible is false) or a physical product (tangible is true).
Name	Required (string) The name of the product will be used in the 2Checkout systems (order reports, invoices if generated).
PriceAmount	Required (float) The price of the product. The price amount and type must be grouped under a price object.
PriceType	Required (string) Must be set to “CUSTOM”; Price amount and type must be grouped under a price object.

The items in the JSON body of the request would look like:

 "Items":[
      {
         "Code":null,
         "IsDynamic":true,
         "PurchaseType":"PRODUCT",
         "Tangible":false,
         "Name":"My Dynamic Product",
         "Quantity":1,
         "Price":{
            "Amount":1,
            "Type":"CUSTOM"
         }
      }
   ]

The full list of fields available for dynamic products can be found here.

The full JSON for an order with dynamic products would look like:

{
   "Items":[
      {
         "Code":null,
         "IsDynamic":true,
         "PurchaseType":"PRODUCT",
         "Tangible":false,
         "Name":"My Dynamic Product",
         "Quantity":1,
         "Price":{
            "Amount":1,
            "Type":"CUSTOM"
         }
      }
   ],
   "BillingDetails":{
      "FirstName":"Customer First Name",
      "LastName":"Customer Last Name",
      "CountryCode":"US",
      "State":"California",
      "City":"San Francisco",
      "Address1":"Example Street",
      "Zip":"90210",
      "Email":"[email protected]"
   },
   "PaymentDetails":{
      "Type":"TEST",
      "Currency":"USD",
      "CustomerIP":"10.10.10.10",
      "PaymentMethod":{
         "CardNumber":"4111111111111111",
         "CardType":"VISA",
         "ExpirationYear":"2020",
         "ExpirationMonth":"12",
         "CCID":"123",
         "HolderName":"John Doe",
         "Vendor3DSReturnURL":"https:\/\/example.com",
         "Vendor3DSCancelURL":"https:\/\/example.com"
      }
   }
}

Extending the order object

There's a wide range of use cases that can be supported by the order object, such as, but not limited to, adding customer information on an order, affiliate information, promotions, or additional fields.

To add this information, a new object with the corresponding name must be added at the root level of the order object, with the appropriate structure.

For example, to add delivery details that were collected from the shopper, a new object named “DeliveryDetails” needs to be added in the order object (on the same level as the "Billing Details").

The Delivery Details object has the same structure as the Billing Details object.

Let’s assume we also want to add some additional information to the order. This could be done by adding a new AdditionalFields array of Additional Field objects.

The additional field object contains three fields:

• a code (the internal code in the merchant's systems)

• a text (that could be displayed to the shoppers)

• a value (the actual value of the additional field for that order)

Adding delivery details and additional fields to an order would look like this:

 "DeliveryDetails":{
      "FirstName":"Customer First Name",
      "LastName":"Customer Last Name",
      "Address1":"Example Street 42",
      "Address2":"2nd line of the address",
      "City":"San Francisco",
      "State":"California",
      "CountryCode":"US",
      "Phone":"555-5555",
      "Email":"[email protected]",
      "Zip":"90210"
   },
   "AdditionalFields":[
      {
         "Code":"ABC1234",
         "Text":"Additional field text",
         "Value":"Additional field value"
      }
   ]

Integration use cases

There are several test credit cards (available here) that can be used to test your integration as described in these steps:

1. Create a test product in the Merchant Control Panel.

2. Using the product code of the newly created product, place an order based on the request example above, and check that an order is placed.

3. Starting from the minimum requirements for a catalog product order, extend the information you send to 2Checkout and check on every new parameter that the order is placed successfully.

4. If you need to create products on the fly via dynamic products, first of all, make sure your account supports dynamic products (available only for 2Sell and 2Subscribe accounts, if you handle your own tax and invoice management).

5. Starting from the minimum requirements for a dynamic product order, start adding all the information you need to send to 2Checkout while checking that the order is successfully placed.

6. Check that making a placeOrder API call returns an order object.

7. Once an order object is obtained via API, check the order in the Merchant Control Panel. Under Orders & customers → Order search, you can filter by the order reference of the newly created order (the RefNo property).