Build the order object to place orders

Overview

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 are 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. 

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":"example@email.com"
   },
   "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 in order to place an order with dynamic products, via API is:

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 catalog 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":"example@email.com"
   },
   "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.

In order 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, in order 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 Additional Fields 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":"example@email.com",
      "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).