How to Build an Order Create API 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.

<?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"> (1)
            <Name>
                <LastName>Doe</LastName> (2)
                <FirstName>John</FirstName> (3)
                <EmailAddress>johndoe@gsicommerce.com</EmailAddress> (4)
            </Name>
        </Customer>        ...
    </Order>    ...
</OrderCreateRequest>

1	A unique identifier for the customer given from the order taking system.
2	The last name of the customer (required).
3	The first name of the customer (required).
4	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.

<?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" (1)
                       webLineId="1"> (2)
                <ItemId>12-345</ItemId> (3)
                <Quantity>2</Quantity> (4)
                <Pricing>
                    <Merchandise> (5)
                        <Amount>24.68</Amount>
                        <TaxData> (6)
                            ...
                        </TaxData>
                        <UnitPrice>12.34</UnitPrice>
                    </Merchandise>
                    <Shipping> (7)
                        <Amount>1.23</Amount>
                        <TaxData> (8)
                            ...
                        </TaxData>
                    </Shipping>
                </Pricing>
                <ShippingMethod displayText="Standard Ground">ANY_STD</ShippingMethod> (9)
                <FulfillmentChannel>SHIP_TO_HOME</FulfillmentChannel> (10)
                <EstimatedDeliveryDate> (11)
                    <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> (12)
            </OrderItem>
        </OrderItems>        ...
    </Order>    ...
</OrderCreateRequest>

1	The id uniquely identifies the OrderItem within the xml just for xml references (required).
2	The webLineId uniquely identifies the OrderItem’s line within this order (required).
3	The SKU of the item (required).
4	The number of this item ordered (required).
5	The pricing for the item itself (required).
6	Tax data relating to the pricing of the item that is taken from the `TaxDutyQuoteResponse`. See mapping.
7	The pricing for the shipping of this item.
8	Tax data relating to the pricing of the shipping that is taken from the `TaxDutyQuoteResponse`. See mapping.
9	The name of the shipping method this item is to be shipped with (required).
10	The fulfillment channel for this item (ex. SHIP_TO_STORE, STORE_PICK_UP, SHIP_TO_HOME, STORE_RESERVATION).
11	The estimated shipping/delivery dates for this item. The `DeliveryWindow` and `ShippingWindow` elements are taken from the `InventoryDetailsResponseMessage`. See mapping.
12	The inventory reservation identifier that comes from the `AllocationResponseMessage`.

Shipping

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

ShipGroups group OrderItems as referenced by their xml id into groups by their chargeType and DestinationTarget as referenced by its xml id.
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).

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

<?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" (1)
                           id="shipGroup1"> (2)
                    <DestinationTarget ref="address1"/> (3)
                    <OrderItems>
                        <Item ref="orderItem1"/> (4)
                    </OrderItems>
                </ShipGroup>
            </ShipGroups>
            <Destinations>
                <MailingAddress id="address1"> (5)
                    <PersonName> (6)
                        <LastName>Doe</LastName>
                        <FirstName>John</FirstName>
                    </PersonName>
                    <Address> (7)
                        <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> (8)
                </MailingAddress>
            </Destinations>
        </Shipping>
        ...
    </Order>
    ...
</OrderCreateRequest>

1	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).
2	The id attribute is a unique identifier within the xml used for xml references (required).
3	The destination for this ship group. It should contain a reference to an element in the `Destinations` section (required).
4	The items that are part of this ship group. They should contain references to the `OrderItem` in the `OrderItems` section of the request.
5	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.
6	The person’s name for the mailing address (required).
7	The address itself (required).
8	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.

<OrderCreateRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
        requestId="123456789">
    <Order customerOrderId="12345">
        ...
        <Payment>
            <BillingAddress ref="address1"/> (1)
            <Payments>
                <CreditCard> (2)
                    <PaymentContext>
                        <PaymentSessionId>12345</PaymentSessionId> (3)
                        <TenderType>VC</TenderType> (4)
                        <PaymentAccountUniqueId isToken="true">456def</PaymentAccountUniqueId> (5)
                    </PaymentContext>
                    <PaymentRequestId>789ghi</PaymentRequestId> (6)
                    <CreateTimeStamp>2016-02-12T23:08:20+00:00</CreateTimeStamp> (7)
                    <Amount>25.91</Amount> (8)
                    <Authorization> (9)
                        <ResponseCode>APPROVED</ResponseCode> (10)
                        <BankAuthorizationCode>123456</BankAuthorizationCode>                        <CVV2ResponseCode>M</CVV2ResponseCode>                        <AVSResponseCode>Y</AVSResponseCode>                        <AmountAuthorized>25.91</AmountAuthorized>                    </Authorization>                    <ExpirationDate>2020-01</ExpirationDate> (11)
                </CreditCard>
            </Payments>
        </Payment>
        ...
    </Order>
    ...
</OrderCreateRequest>

1	The billing address for this order. It should just contain a reference to a `MailingAddress` in the `ShippingDestinations` section (required).
2	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.
3	The `PaymentSessionId` should always be the orderId (required).
4	The tender type, in this case VC (visa). See tender types for more examples (required).
5	The `PaymentAccountUniqueId` comes from the `CreditCardAuthReply` (required). See mapping.
6	The `PaymentRequestId` is the same as you sent in the `CreditCardAuthRequest` (required).
7	The time the payment was authorized (required).
8	The amount this payment method is for (should match with `AmountAuthorized`) (required).
9	Authorization results that come from `CreditCardAuthReply`. See mapping.
10	The `ResponseCode` requires a conversion from `CreditCardAuthReply`. See response code transform.
11	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.

<OrderCreateRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
        requestId="123456789"> (1)
    <Order customerOrderId="12345"> (2)
        <Customer>...</Customer>
        <CreateTime>2016-02-18T19:23:13.046Z</CreateTime> (3)
        <OrderItems>...</OrderItems>
        <Shipping>...</Shipping>
        <Payment>...</Payment>
        <Currency>USD</Currency> (4)
        <Locale>en_US</Locale> (5)
        <OrderTotal>25.91</OrderTotal> (6)
    </Order>
    <Context>...</Context>
</OrderCreateRequest>

1	A unique identifier for the request that the client is responsible for ensuring uniqueness across requests they make (required).
2	The order identifier that the order generating application gives (required).
3	The time the order generating application accepted the order (required).
4	The code that represents the type of currency being used for this order (required).
5	The locale code for this order (required).
6	The total cost of the order (including merchandise, shipping, tax, duties, fees, and promotions).