commitOrder

This article contains the technical specifications of Paazl's SOAP API commitOrder call.

Use commitOrder to finalize pending orders that have been confirmed by customers.

Why commit orders?

When processing orders, Paazl uses two different order types to model the purchase transaction: a "pending order" and an "order". The pending order serves as a temporary reference point for available shipping options. When your customer selects an option and clicks "Buy", the pending order becomes an order and you have to commit it.

The following is a more detailed description of how this works:

1. A customer places an item in your webshop's shopping basket
2. Step 1 triggers an orderRequest call to Paazl with your reference code in the call's orderReference element
3. Paazl creates a pending order in its database using your reference code. The order is not yet visible on your account.
4. Your customer fills in his/her address details
5. Step 4 triggers a shippingOptionRequest call to Paazl, following which the returned options are displayed in your checkout
6. Your customer selects a shipping option, fills in his/her payment details, and clicks the "Buy" button
7. Step 5 triggers a commitOrderRequest call to Paazl. This call contains a reference to the pending order (pendingOrderReference) and a (new) reference for the order (orderReference)
8. Paazl creates the order in its database using the <orderReference> value, and displays the order in your webshop account

Example

Assume a customer is in your checkout and has filled in his/her address details. Using the orderRequest call's orderReference element, you tell Paazl that the reference code for the pending order is temp0001. That value is stored in Paazl's database but it is not visible in your webshop's Paazl account.

Your customer now clicks "Buy" and you send a commitOrder request to Paazl. You tell Paazl that the pending order concerned is temp0001 using the pendingOrderReference element. At the same time, using the orderReference element, you tell Paazl that the reference code you want to use for the committed order is order0001. Paazl creates the order with reference code order0001 and it appears in your Paazl account.

Shipping Address Formats

Carriers can have different requirements regarding how they want to format shipping addresses for each of the shipping options they offer. These requirements may affect the maximum length of fields, and the granularity of the address elements. Normally you supply Paazl with address information in a standard format and Paazl translates this into the format required by the carrier concerned. However, when you work internationally, local customs can change the way you work. For example, American webshop customers find it annoying to have to fill in address details in separate fields; Ireland does not use postal codes; and in France the address may be more a description of what the house looks like than a formal address. Such issues may require you to supply Paazl with information in a non-standard format.

The standard elements provided by Paazl for specifying addresses are:

• street
• housenumber
• addition (used for house number extension)
• zipcode
• city
• province
• country
• additionalAddressLine (used for the second line on a label)

In most cases it is a straightforward process to fill these fields. However, when shipping to different countries, things become more complicated. A small number of carriers require you to fill in all the data as a single string. Others require you to fill in the data using two strings, although they differ regarding which information goes where.

For single strings, Paazl uses the street element. When two strings are required, Paazl uses the street element for the first line of the label, and the additionalAddressLine for the second line. In addition, there may be restrictions on the number of characters you can use for any one element. Paazl's maximum field lengths are usually more restrictive than those of the various carriers — so just conforming with Paazl specifications is sufficient — but there are exceptions to this rule too.

Hopefully you won't bump into these issues during your implementation. If you do, the specific requirements of the carrier and shipping option concerned will have to be determined during the integration of your webshop with Paazl.

Request

Element specifications

Sample request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:mat="http://www.paazl.com/schemas/matrix">
   <soapenv:Header/>
   <soapenv:Body>
      <mat:commitOrderRequest>
         <!--You may enter the following 14 items in any order-->
         <mat:hash>3ae71f4e69e43a32e2c474d4b4ac0c63632de560</mat:hash>
         <mat:webshop>491</mat:webshop>
         <!--Optional:-->
         <mat:targetWebshop></mat:targetWebshop>
         <mat:orderReference>order0001</mat:orderReference>
         <mat:pendingOrderReference>pending0001</mat:pendingOrderReference>
         <mat:totalAmount>1</mat:totalAmount>
         <!--Optional:-->
         <mat:totalAmountCurrency>EUR</mat:totalAmountCurrency>
         <!--Optional:-->
         <mat:language></mat:language>
         <mat:customerEmail>qa@paazl.com</mat:customerEmail>
         <!--Optional:-->
         <mat:customerPhoneNumber></mat:customerPhoneNumber>
         <mat:shippingMethod>
            <mat:type>delivery</mat:type>
            <!--Optional:-->
            <mat:distributor>TNT</mat:distributor>
            <mat:identifier></mat:identifier>
            <mat:option>AVG</mat:option>
            <!--Optional:-->
            <mat:returnContract>
               <mat:type>fixed</mat:type>
               <!--Optional:-->
               <mat:contract>123456789</mat:contract>
            </mat:returnContract>
            <!--Optional:-->
            <mat:servicepointAccountNumber></mat:servicepointAccountNumber>
            <!--Optional:-->
            <mat:servicepointNotificationEmail></mat:servicepointNotificationEmail>
            <!--Optional:-->
            <mat:servicepointNotificationMobile></mat:servicepointNotificationMobile>
            <!--Optional:-->
            <mat:price></mat:price>
            <!--Optional:-->
            <mat:shippingPaymentType></mat:shippingPaymentType>
            <!--Optional:-->
            <mat:billingAccountNumber></mat:billingAccountNumber>
            <!--Optional:-->
            <mat:invoiceNumber></mat:invoiceNumber>
            <!--Optional:-->
            <mat:packagingWeight></mat:packagingWeight>
            <!--Optional:-->
            <mat:customsValue></mat:customsValue>
            <!--Optional:-->
            <mat:customsValueCurrency>EUR</mat:customsValueCurrency>
            <!--Optional:-->
            <mat:dutiesPaymentType></mat:dutiesPaymentType>
            <!--Optional:-->
            <mat:dutiesAccountNumber></mat:dutiesAccountNumber>
            <!--Optional:-->
            <mat:orderWeight></mat:orderWeight>
            <!--Optional:-->
            <mat:assuredAmount></mat:assuredAmount>
            <!--Optional:-->
            <mat:assuredAmountCurrency>EUR</mat:assuredAmountCurrency>
            <!--Optional:-->
            <mat:collo></mat:collo>
            <!--Optional:-->
            <mat:packageCount></mat:packageCount>
            <!--Optional:-->
            <mat:maxLabels></mat:maxLabels>
            <!--Optional:-->
            <mat:packagingType></mat:packagingType>
            <!--Optional:-->
            <mat:preferredDeliveryDate></mat:preferredDeliveryDate>
            <!--Optional:-->
            <mat:preferredDateChosen></mat:preferredDateChosen>
            <!--Optional:-->
            <mat:description></mat:description>
         </mat:shippingMethod>

         <mat:shippingAddress>
            <!--Optional:-->
            <mat:accountNumber></mat:accountNumber>
            <mat:customerName>Paazl</mat:customerName>
            <!--Optional:-->
            <mat:companyName></mat:companyName>
            <!--Optional:-->
            <mat:nameOther></mat:nameOther>
            <mat:street>Veembroederhof</mat:street>
            <mat:housenumber>93</mat:housenumber>
            <!--Optional:-->
            <mat:addition></mat:addition>
            <!--Zero or more repetitions:-->
            <mat:additionalAddressLine></mat:additionalAddressLine>
            <mat:zipcode>1019HD</mat:zipcode>
            <mat:city>Amsterdam</mat:city>
            <!--Optional:-->
            <mat:province></mat:province>
            <!--Optional:-->
            <mat:country>NL</mat:country>
            <!--Optional:-->
            <mat:localAddressValidation>true</mat:localAddressValidation>
            <!--Optional:-->
            <mat:additionalInstruction></mat:additionalInstruction>
         </mat:shippingAddress>
      </mat:commitOrderRequest>
   </soapenv:Body>
</soapenv:Envelope>

Response

The commitOrder response consists of a simple message indicating whether or not the request has succeeded.

Sample response

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <commitOrderResponse xmlns="http://www.paazl.com/schemas/matrix">
         <succes>Order successfully saved</succes>
      </commitOrderResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>