How to Build an Order Create Request

At the end of a successful checkout flow, an OrderCreateRequest must be sent to the ROM Order API. An OrderCreateRequest requires many pieces of information, some of which must be gathered from responses from other services earlier in checkout. This page breaks a simple OrderCreateRequest message into logical chunks and explains how to build each.

Order Create API Request Message

Customer

A Customer is required for an Order. Aside from the basic customer fields, there are optional fields, including tax-exemption and loyalty program information.

Copy

<?xml version="1.0" encoding="UTF-8"?>
<OrderCreateRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
        requestId="123456789">
    <Order customerOrderId="12345">
        <Customer customerId="123abc"> <!-- see NOTE1 --> 
            <Name>
                <LastName>Doe</LastName> <!-- see NOTE2 -->
                <FirstName>John</FirstName> <!-- see NOTE3 --> 
                <EmailAddress>johndoe@gsicommerce.com</EmailAddress> <!-- see NOTE4 -->
            </Name>
        </Customer>        ...
    </Order>    ...
</OrderCreateRequest>

NOTE1	A unique identifier for the customer given from the order taking system.
NOTE2	The last name of the customer (required).
NOTE3	The first name of the customer (required).
NOTE4	The email address of the customer.

OrderItems

An Order can contain multiple OrderItem. Below is only the most commonly used fields. Different types of items should contain different fields. For different items see item examples.

Copy

<?xml version="1.0" encoding="UTF-8"?>
<OrderCreateRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
        requestId="123456789">
    <Order customerOrderId="12345">        ...
        <OrderItems>
            <OrderItem id="orderItem1"  
                       webLineId="1"> <!-- see NOTE1 NOTE2 -->
                <ItemId>12-345</ItemId> <!-- see NOTE3 --> 
                <Quantity>2</Quantity> <!-- see NOTE4 -->
                <Pricing>
                    <Merchandise> <!-- see NOTE5 -->
                        <Amount>24.68</Amount>
                        <TaxData> <!-- see NOTE6 --> 
                            ...
                        </TaxData>
                        <UnitPrice>12.34</UnitPrice>
                    </Merchandise>
                    <Shipping> <!-- see NOTE7 --> 
                        <Amount>1.23</Amount>
                        <TaxData> <!-- see NOTE8 --> 
                            ...
                        </TaxData>
                    </Shipping>
                </Pricing>
                <ShippingMethod displayText="Standard Ground">ANY_STD</ShippingMethod>  
                <!-- see NOTE9 -->
         <FulfillmentChannel>SHIP_TO_HOME</FulfillmentChannel> 
         <!-- see NOTE10 --> 
                <EstimatedDeliveryDate> <!-- see NOTE11 -->
                    <DeliveryWindow>
                        <From>2016-02-10T19:44:57Z</From>
                        <To>2016-02-15T19:44:57Z</To>
                    </DeliveryWindow>
                    <ShippingWindow>
                        <From>2016-02-08T19:44:57Z</From>
                        <To>2016-02-08T19:44:57Z</To>
                    </ShippingWindow>
                    <Mode>ENABLED</Mode>
                    <MessageType>DeliveryDate</MessageType>
                    <Template>Expect your items between %s and %s.</Template>
                </EstimatedDeliveryDate>
                <ReservationId>456def</ReservationId> <!-- see NOTE12 --> 
            </OrderItem>
        </OrderItems>        ...
    </Order>    ...
</OrderCreateRequest>

NOTE1	The id uniquely identifies the OrderItem within the xml just for xml references (required).
NOTE2	The webLineId uniquely identifies the OrderItem’s line within this order (required).
NOTE3	The SKU of the item (required).
NOTE4	The number of this item ordered (required).
NOTE5	The pricing for the item itself (required).
NOTE6	Tax data relating to the pricing of the item that is taken from the `TaxDutyQuoteResponse`. See mapping.
NOTE7	The pricing for the shipping of this item.
NOTE8	Tax data relating to the pricing of the shipping, should match the values from the `TaxDutyQuoteResponse`. The default TaxClass value for shipping is 93000. See mapping.
NOTE9	The name of the shipping method this item is to be shipped with (required).
NOTE10	The fulfillment channel for this item (ex. SHIP_TO_STORE, STORE_PICK_UP, SHIP_TO_HOME, STORE_RESERVATION).
NOTE11	The estimated shipping/delivery dates for this item. The `DeliveryWindow` and `ShippingWindow` elements are taken from the `InventoryDetailsResponseMessage`. See mapping.
NOTE12	The inventory reservation identifier that comes from the `AllocationResponseMessage`.

Shipping

The Shipping element of an Order contains two kinds of subordinate elements:

Destinations is a list of MailingAddress, StoreLocation, and Email elements that contain xml ids that are referenced throughout the rest of the Order (like the DestinationTarget mentioned above and the BillingAddress mentioned in the Payment section). Because the Billing Address is a required Mailing Address and all Mailing Addresses must come before all Store or Email Addresses, the Billing Address should always be the first Destination.
ShipGroups group OrderItems as referenced by their xml id into groups by their chargeType and DestinationTarget as referenced by its xml id.

This example just includes a basic MailingAddress. For other destinations see shipping examples.

Copy

<?xml version="1.0" encoding="UTF-8"?>
<OrderCreateRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
        requestId="123456789">
    <Order customerOrderId="12345">
        ...
        <Shipping>
            <ShipGroups>
                <ShipGroup chargeType="FLATRATE" 
                           id="shipGroup1"> <!-- see NOTE1 NOTE2 --> 
                    <DestinationTarget ref="address1"/> <!-- see NOTE3 -->
                    <OrderItems>
                        <Item ref="orderItem1"/> <!-- see NOTE4 -->
                    </OrderItems>
                </ShipGroup>
            </ShipGroups>
            <Destinations>
                <MailingAddress id="address1"> <!-- see NOTE5 -->
                    <PersonName> <!-- see NOTE6 -->
                        <LastName>Doe</LastName>
                        <FirstName>John</FirstName>
                    </PersonName>
                    <Address> <!-- see NOTE7 -->
                        <Line1>935 1st Ave</Line1>
                        <City>King of Prussia</City>
                        <MainDivision>PA</MainDivision>
                        <CountryCode>US</CountryCode>
                        <PostalCode>19406</PostalCode>
                    </Address>
                    <Phone>555-555-5555</Phone> <!-- see NOTE8 --> 
                </MailingAddress>
            </Destinations>
        </Shipping>
        ...
    </Order>
    ...
</OrderCreateRequest>

NOTE1	ShipGroups are a grouping of items by DestinationTarget and chargeType. The chargeType is the type of shipping charge like FLAT, WEIGHT, etc and is needed in case taxes need to be calculated (required).
NOTE2	The id attribute is a unique identifier within the xml used for xml references (required).
NOTE3	The destination for this ship group. It should contain a reference to an element in the `Destinations` section (required).
NOTE4	The items that are part of this ship group. They should contain references to the `OrderItem` in the `OrderItems` section of the request.
NOTE5	Address are defined here and referenced throughout other parts of the order like in `ShipGroups` and `BillingAddress`. There can also be `StoreLocation` and `Email` elements here. See examples.
NOTE6	The person’s name for the mailing address (required).
NOTE7	The address itself (required).
NOTE8	The phone number for the mailing address (required).

Payment

The Payment section contains exactly one BillingAddress which is a reference to a MailingAddress in the Shipping section above. It also contains one or more payments. Each payment has its own element type. Here we just have a CreditCard example. See payment examples for the other types.

BillingAddress must always be the first element.

Copy

<OrderCreateRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
        requestId="123456789">
    <Order customerOrderId="12345">
        ...
        <Payment>
            <BillingAddress ref="address1"/> <!-- see NOTE1 -->
            <Payments>
                <CreditCard> <!-- see NOTE2 --> 
                    <PaymentContext>
                        <PaymentSessionId>12345</PaymentSessionId> 
            <!-- see NOTE3 --> 
                        <TenderType>VC</TenderType> <!-- see NOTE4 -->
                        <PaymentAccountUniqueId isToken="true">
                456def</PaymentAccountUniqueId> 
            <!-- see NOTE5 -->
                    </PaymentContext>
                    <PaymentRequestId>789ghi</PaymentRequestId> <!-- see NOTE6 --> 
                    <CreateTimeStamp>2016-02-12T23:08:20+00:00</CreateTimeStamp> 
            <!-- see NOTE7 --> 
                    <Amount>25.91</Amount> <!-- see NOTE8 -->
                    <Authorization> <!-- see NOTE9 --> 
                        <ResponseCode>APPROVED</ResponseCode> <!-- see NOTE1O -->
                        <BankAuthorizationCode>123456</BankAuthorizationCode>
                        <CVV2ResponseCode>M</CVV2ResponseCode>
                        <AVSResponseCode>Y</AVSResponseCode>
                        <AmountAuthorized>25.91</AmountAuthorized>
                    </Authorization>
                    <ExpirationDate>2021-01</ExpirationDate> <!-- see NOTE11 --> 
                </CreditCard>
            </Payments>
        </Payment>
        ...
    </Order>
    ...
</OrderCreateRequest>

NOTE1	The billing address for this order. It should just contain a reference to a `MailingAddress` in the `ShippingDestinations` section (required). It must always come first.
NOTE2	A parent payment element. Different types of payments have different element names, this one is a credit card. See payment examples for other examples. There can be multiple payments.
NOTE3	The `PaymentSessionId` should always be the orderId (required).
NOTE4	The tender type, in this case VC (visa). See tender types for more examples (required).
NOTE5	The `PaymentAccountUniqueId` comes from the `CreditCardAuthReply` (required). See mapping.
NOTE6	The `PaymentRequestId` is the same as you sent in the `CreditCardAuthRequest` (required).
NOTE7	The time the payment was authorized (required).
NOTE8	The amount this payment method is for (should match with `AmountAuthorized`) (required).
NOTE9	Authorization results that come from `CreditCardAuthReply`. See mapping.
NOTE10	The `ResponseCode` requires a conversion from `CreditCardAuthReply`. See response code transform.
NOTE11	The expiration date of the credit card.

Context

The Context element of an OrderCreateRequest is required and used for fraud processing. This data comes from the customer’s web browser at the time the order is submitted. It includes the integration of a fraud detection component called the JavaScript Collector. To read more about the various fields and the JavaScript Collector visit these links:

Miscellaneous Elements

After the sections listed above, there are a few other fields in an Order. Below is an example containing the commonly used ones.

Copy

<OrderCreateRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
        requestId="123456789"> <!-- see NOTE1 -->
    <Order customerOrderId="12345"> <!-- see NOTE2 --> 
        <Customer>...</Customer>
        <CreateTime>2016-02-18T19:23:13.046Z</CreateTime> <!-- see NOTE3 --> 
        <OrderItems>...</OrderItems>
        <Shipping>...</Shipping>
        <Payment>...</Payment>
        <Currency>USD</Currency> <!-- see NOTE4 --> 
        <Locale>en_US</Locale> <!-- see NOTE5 --> 
        <OrderTotal>25.91</OrderTotal> <!-- see NOTE6 --> 
    </Order>
    <Context>...</Context>
</OrderCreateRequest>

NOTE1	A unique identifier for the request that the client is responsible for ensuring uniqueness across requests they make (required).
NOTE2	The order identifier that the order generating application gives (required).
NOTE3	The time the order generating application accepted the order (required).
NOTE4	The code that represents the type of currency being used for this order (required).
NOTE5	The locale code for this order (required).
NOTE6	The total cost of the order (including merchandise, shipping, tax, duties, fees, and promotions).