How To

Checkout Report XML Interface

The ChannelAdvisor Checkout Report XML Interface is a mechanism for ChannelAdvisor sellers to download checkout report information in an automated fashion over an HTTPS connection. The data content provided through this interface is identical to that already provided in the ChannelAdvisor downloadable CSV reports, but through the use of XML formatting is better structured for integration into a ChannelAdvisor seller’s internal systems. Data is accessed by passing specific query string parameters to a URL provided by ChannelAdvisor, and returned via securely streamed XML page content.

NOTE: This method is no longer the recommended way to download order information from your ChannelAdvisor account.  For an improved developer experience, please consider using one of our newer SOAP or REST based APIs.  Information on these methods can be found in our API Integration Guide.

 

Tasks to Complete


 


This page will describe the protocol for these request parameters and the response content, as well as provide some sample data to view this interface in action.

Return to top

Requesting Reports



Requests for report data are currently made via the use of query string parameters added to the following base URL:

https://merchant.ChannelAdvisor.com/Export/CFExport.dll?CheckoutReport?<PARAMETERS_HERE>

The following table describes the available parameters:

 Parameter Name  Description  Required?  Sample Value 
 pid  Account Profile ID. A numeric value unique to each ChannelAdvisor Account (see section below to locate this ID)  Yes  10055350 
 mn  Login MemberName – login id provided by ChannelAdvisor to access your reports, typically an e-mail address. If you do not have a login id or wish to create a limited access ID just for these reports, please contact your ChannelAdvisor Account Manager.  Yes  CheckoutTest@ChannelAdvisor.com 
 pw  Login password – corresponding password to the login id specified by “mn”.  Yes  FETCHIT! 
 ver  Report version. Currently must be set to version “2” or version "3" Yes  3
 rid  Report ID. Use this to query a specific report ID, as shown on the Checkout Reports section of the application. If this and “dt” are omitted, the most recently run report will be returned.  No  36892 
 dt  Report Date/Time. Use this to query the report that spans the date-time passed in. Useful when a specific report ID is not known. Timezone should match that set for the account matching the “pid” value passed in and should be in this format: MM/DD/YY HH:MM:SS, where HH is in 24 hour time.  No  6/15/09 10:00:00 
 sep  Show Encrypted Password. Pass a value of “1” to return an encrypted/encoded version of the “pw” parameter to be used for the “pe” parameter below. No report will be returned.  No  1 
 pe  Encrypted password. Use the results of the “sep=1” command for this parameter to be used in place of the “pw” parameter if you wish to encrypt your password in the URL query string.  No  *UeTN%5C8p 

Return to top

Locating your Account Profile ID (“pid” parameter)


To determine your Account Profile ID in ChannelAdvisor:

  1. Navigate to My Account > Utilities > Company Setup.
  2. Locate the Profile ID in the Company Information section.

Note: This number also appears in the URL of most pages in the application after "?apid=.

 
Return to top

Sample Requests


This request will return a sample report for account “10055350” and report “36892”:

https://merchant.ChannelAdvisor.com/Export/CFExport.dll?CheckoutReport?mn=CheckoutTest@ChannelAdvisor.com&pw=fetchit!&pid=10055350&rid=36892&ver=3

Note how the data included in this report matches exactly that data included in the corresponding .CSV file you may be more accustomed to.

This next request will return the same report, but uses the “dt” date parameter rather than the “rid” parameter to return a particular report. This is especially useful for locating old reports when you do not know the particular report ID (note that report IDs are currently not consecutive per-account, but this may be something added down the road). The datetime value passed in should be in the timezone configured for that account, and should be of the MM-DD-YY HH:MM:SS format. Some HTTP client software may require you to URL encode this value as well.

https://merchant.ChannelAdvisor.com/Export/CFExport.dll?CheckoutReport?mn=CheckoutTest@ChannelAdvisor.com&pw=fetchit!&pid=10055350&ver=3&dt=6/15/09 10:15:00

The above link returns report 36892 because the input time of 6/15/09 10:15:00 is greater than or equal to the start of this report range, 6/15/2009 12:00:00 AM (ET), and less than the end of this report range, 6/15/2009 11:00:00 AM (ET). Similarly this will return 36892:

https://merchant.ChannelAdvisor.com/Export/CFExport.dll?CheckoutReport?mn=CheckoutTest@ChannelAdvisor.com&pw=fetchit!&pid=10055350&ver=3&dt=6/15/09 00:00:00

But this will return the next report for this account, 36927:

https://merchant.ChannelAdvisor.com/Export/CFExport.dll?CheckoutReport?mn=CheckoutTest@ChannelAdvisor.com&pw=fetchit!&pid=10055350&ver=3&dt=6/15/09 11:00:00

If you wish to pass your password in an encrypted format, first use the “sep” parameter to return your encrypted password, for example:

https://merchant.ChannelAdvisor.com/Export/CFExport.dll?CheckoutReport?mn=CheckoutTest@ChannelAdvisor.com&pw=fetchit!&pid=10055350&sep=1

And then use the result for the “pe” parameter (rather than “pw”) in all subsequent requests:

https://merchant.ChannelAdvisor.com/Export/CFExport.dll?CheckoutReport?mn=CheckoutTest@ChannelAdvisor.com&pid=10055350&rid=36892&ver=3&pe=*UeTN%5C8p

Return to top

Automating Report Retrieval


The method used for automating your report retrieval depends heavily on the checkout report frequency configured for your account (Run checkout reports every setting on the Sales > Orders/Transactions > Checkout Report Settings in ChannelAdvisor) and your desired workflow.

There are two primary methods for automating your checkout retrieval requests:

  1. Always retrieve the most recently generated report
  2. Retrieve reports based on date

Both are described below.
 
Return to top

Retrieving Most Recently Generated Report


You can retrieve the most recently generated report by omitting the “rid” and “dt” parameters, for example:

https://merchant.ChannelAdvisor.com/Export/CFExport.dll?CheckoutReport?mn=CheckoutTest@ChannelAdvisor.com&pw=fetchit!&pid=10055350&ver=3

This approach allows an automated task to hit the same URL at predefined intervals based on the report frequency configured for your account. Care must be taken in this approach, though. Although ChannelAdvisor makes every attempt to generate all reports within an hour, the actual elapsed time may vary due to current system load and scheduled or unscheduled system outages.

The recommended client implementation would cache the latest “ReportPeriodEnd” value returned (more on this below), and schedule a retry if the ReportPeriodEnd matches a ReportPeriodEnd already processed on an earlier attempt. Any scheduled retries should be attempted at intervals smaller than the configured report generation frequency, so for example if you run reports every 24 hours and an attempt at 12:30 AM fails, you may want to retry again at 2:30 AM. To reduce overall system load, we ask that you limit retries to an as-needed basis.

This approach works well for long report durations, say 12 or 24 hours. For shorter durations, you may want to use the “retrieve reports based on date” method.
 
Return to top

Retrieving Reports Based on Date


In this approach, the “dt” parameter would also be used to target a specific report spanning a specific time range. This approach is better suited for shorter report intervals, say anything less than every 12 hours, but does come at the cost of additional implementation complexity.

In this method, you should continue to cache the ReportPeriodEnd returned by any prior queries, as explained above, but on subsequent calls you should pass that same ReportPeriodEnd value via the “dt” parameter. So, for example, if your first query returned a ReportPeriodEnd value 6/15/2009 11:00:00, you could pass in your next call a dt value of “6/15/2009 11:00:00”. If the new report has not yet been generated, you will not receive a new ReportPeriodEnd value in response. If it has been generated, you can cache this new value and specify this in your “dt” parameter for your next scheduled attempt. Suitable retries should be scheduled based on your report frequency to guarantee all data is downloaded in a timely fashion.
 
Return to top

Planning for Scheduled and Unscheduled System Outages


Although ChannelAdvisor makes every attempt to provide access to its reporting system on a 24/7 basis, there are windows of scheduled and unscheduled system downtime that should be accounted for in any client polling architecture.

The ChannelAdvisor checkout reports will always span contiguous ranges of time regardless of configured report frequency or report generation time. Therefore, if the ChannelAdvisor system is scheduled to be brought offline from 4am to 8am for a planned maintenance cycle, but your report generation frequency is set to a shorter time duration of 1 hour, the reports generated could span a time range longer than that 1 hour. Thus in this scenario the 2:00 AM - 3:00 AM report would run normally since the reporting system is still online after 3:00 AM. The 3:00 AM - 4:00 AM report, though, would not run since the system is currently offline (reports are run after the close of the hour). Similarly the report system would not run after 5:00 AM, 6:00 AM, or 7:00 AM. Once the system is brought back online at 8:00 AM, though, the report generation task would detect the gap and generate a report spanning the 3:00 AM - 8:00 AM time span. From there processing would continue as normal for reports spanning 8:00 AM - 9:00 AM, 9:00 AM - 10:00 AM, and so forth.

This behavior is by design and should be taken under consideration for any client polling implementations.
 
Return to top

Response Report XML Format



The response XML returned by the above queries are encoded in ISO-8859-1 format and follow the tag structure defined below. CDATA tags are indicated for those string values that could potentially contain markup characters that could confuse an XML parser. Here is an example of such a tag:

<BillingDayPhone><![CDATA[919-847-5555]]></BillingDayPhone>

View the report tag data hierarchy.

Return to top


Sample XML Responses


This is an order with two invoices, with one item included in the first invoice and two in the second.

<?xml version="1.0" encoding="iso-8859-1"?>
<CheckoutReport>
<MerchantName>ChannelAdvisor Enterprise Demos 1</MerchantName>
<ReportId>36892</ReportId>
<ReportPeriodStart>6/15/2009 12:00:00 AM (ET)</ReportPeriodStart>
<ReportPeriodEnd>6/16/2009 11:00:00 AM (ET)</ReportPeriodEnd>
<Version>2.0</Version>
<PurchaseList>
<BuyerPurchase>
    <TransactionInfo>
    <InvoiceNumber>5647151</InvoiceNumber>
    <CheckoutDate>06/15/2009 10:47:37 AM</CheckoutDate>
    <TotalInvoiceAmount>102.48</TotalInvoiceAmount>
    <PaymentType>VI</PaymentType>
    <PaymentId><![CDATA[4111-1111-1111-1111]]></PaymentId>
    <ExpDate>5/2004</ExpDate>
    <CVVNbr></CVVNbr>
    <PaymentTransID><![CDATA[]]></PaymentTransID>
    <TransRefOut><![CDATA[]]></TransRefOut>
    <TotalTax>5.99</TotalTax>
    <OrderID><![CDATA[119]]></OrderID>
    <OtherCost><![CDATA[0.00]]></OtherCost>
    <BillingNameTitle>Mr.</BillingNameTitle>
    <BillingFirstName><![CDATA[Bill]]></BillingFirstName>
    <BillingLastName><![CDATA[Isham]]></BillingLastName>
    <BillingNameSuffix><![CDATA[III]]></BillingNameSuffix>
    <BillingBuyerCompany><![CDATA[IshamCorpTechnologies]]></BillingBuyerCompany>
    <BillingBuyerTitle><![CDATA[Chief Executive Officer]]></BillingBuyerTitle>
    <BillingAddress1><![CDATA[12 Main St.]]></BillingAddress1>
    <BillingAddress2><![CDATA[]]></BillingAddress2>
    <BillingCity><![CDATA[Raleigh]]></BillingCity>
    <BillingRegion>NC</BillingRegion>
    <BillingZip><![CDATA[27613]]></BillingZip>
    <BillingCountry><![CDATA[US]]></BillingCountry>
    <BillingDayPhone><![CDATA[919-847-5555]]></BillingDayPhone>
    <BillingEveningPhone><![CDATA[]]></BillingEveningPhone>
    <BillingReserved1><![CDATA[]]></BillingReserved1>
    <MarketplaceEmail><![CDATA[isham@ChannelAdvisor.com]]></MarketplaceEmail>
    <BuyerEmailOptIn>0</BuyerEmailOptIn>
    <ResellerID><![CDATA[]]></ResellerID>
    <CustomField1><![CDATA[]]></CustomField1>
    <CustomField2><![CDATA[]]></CustomField2>
    <CustomField3><![CDATA[]]></CustomField3>
    <CustomField4><![CDATA[]]></CustomField4>
    <CustomField5><![CDATA[]]></CustomField5>
    </TransactionInfo>
    <ShipmentList>
    <Shipment>
    <ShipmentNumber>1</ShipmentNumber>
    <ShipNameTitle>Dr.</ShipNameTitle>
    <ShipFirstName><![CDATA[Mark]]></ShipFirstName>
    <ShipLastName><![CDATA[Isham]]></ShipLastName>
    <ShipNameSuffix><![CDATA[Sr.]]></ShipNameSuffix>
    <ShipBuyerCompany><![CDATA[ChannelAdvisor Inc.]]></ShipBuyerCompany>
    <ShipBuyerTitle><![CDATA[Sr. Software Engineer]]></ShipBuyerTitle>
    <ShipAddress1><![CDATA[2701 Aerial Center Parkway]]></ShipAddress1>
    <ShipAddress2><![CDATA[Suite 100]]></ShipAddress2>
    <ShipCity><![CDATA[Morrisville]]></ShipCity>
    <ShipRegion>NC</ShipRegion>
    <ShipZip><![CDATA[27560]]></ShipZip>
    <ShipCountry><![CDATA[US]]></ShipCountry>
    <ShipDayPhone><![CDATA[919-465-5680]]></ShipDayPhone>
    <ShipEvePhone><![CDATA[919-465-5555]]></ShipEvePhone>
    <ShipInstructions><![CDATA[Leave with receptionist!]]></ShipInstructions>
    <ShipCarrier>UPS</ShipCarrier>
    <ShipClass>Ground</ShipClass>
    <ShipCharge>10.99</ShipCharge>
    <ShipInsurance>0.00</ShipInsurance>
    <ShipTaxRate></ShipTaxRate>
    <ShipmentTax>5.99</ShipmentTax>
    <ShipmentOther></ShipmentOther>
    <ShipmentSubTotal>85.50</ShipmentSubTotal>
    <ShippingReserved1><![CDATA[]]></ShippingReserved1>
    <ShippingReserved2><![CDATA[]]></ShippingReserved2>
    <Items>
        <Item>
        <LotTitle><![CDATA[Sample Checkout Item 1]]></LotTitle>
        <SKU><![CDATA[SCI1]]></SKU>
        <SiteName><![CDATA[Checkout Direct]]></SiteName>
        <MarketplaceUserID>isham@ChannelAdvisor.com</MarketplaceUserID>
        <SiteAuctionID><![CDATA[100000234]]></SiteAuctionID>
        <SiteTransactionID><![CDATA[0]]></SiteTransactionID>
        <QtyWon>1.00</QtyWon>
        <Bid>85.50</Bid>
        <ClosingTimeLTz>06/15/2009 10:44:43 AM</ClosingTimeLTz>
        <UnitWeight>1.5</UnitWeight>
        <WarehouseLocationNumber><![CDATA[]]></WarehouseLocationNumber>
        <Classification><![CDATA[]]></Classification>
        <ItemReserved1><![CDATA[]]></ItemReserved1>
        <ItemReserved2><![CDATA[]]></ItemReserved2>
        </Item>
    </Items>
    </Shipment>
    </ShipmentList>
    </BuyerPurchase>
    <BuyerPurchase>
    <TransactionInfo>
    <InvoiceNumber>5647152</InvoiceNumber>
    <CheckoutDate>06/15/2009 10:51:37 AM</CheckoutDate>
    <TotalInvoiceAmount>484.47</TotalInvoiceAmount>
    <PaymentType>MO</PaymentType>
    <PaymentId><![CDATA[]]></PaymentId>
    <ExpDate>0/0</ExpDate>
    <CVVNbr></CVVNbr>
    <PaymentTransID><![CDATA[]]></PaymentTransID>
    <TransRefOut><![CDATA[]]></TransRefOut>
    <TotalTax>0.00</TotalTax>
    <OrderID><![CDATA[120]]></OrderID>
    <OtherCost><![CDATA[0.00]]></OtherCost>
    <BillingNameTitle>Mr.</BillingNameTitle>
    <BillingFirstName><![CDATA[John]]></BillingFirstName>
    <BillingLastName><![CDATA[Smith]]></BillingLastName>
    <BillingNameSuffix><![CDATA[]]></BillingNameSuffix>
    <BillingBuyerCompany><![CDATA[]]></BillingBuyerCompany>
    <BillingBuyerTitle><![CDATA[]]></BillingBuyerTitle>
    <BillingAddress1><![CDATA[15 Smith Lane]]></BillingAddress1>
    <BillingAddress2><![CDATA[]]></BillingAddress2>
    <BillingCity><![CDATA[Boston]]></BillingCity>
    <BillingRegion>MA</BillingRegion>
    <BillingZip><![CDATA[02116-6501]]></BillingZip>
    <BillingCountry><![CDATA[US]]></BillingCountry>
    <BillingDayPhone><![CDATA[617-555-5555]]></BillingDayPhone>
    <BillingEveningPhone><![CDATA[]]></BillingEveningPhone>
    <BillingReserved1><![CDATA[]]></BillingReserved1>
    <MarketplaceEmail><![CDATA[mark@ChannelAdvisor.com]]></MarketplaceEmail>
    <BuyerEmailOptIn>0</BuyerEmailOptIn>
    <ResellerID><![CDATA[]]></ResellerID>
    <CustomField1><![CDATA[]]></CustomField1>
    <CustomField2><![CDATA[]]></CustomField2>
    <CustomField3><![CDATA[]]></CustomField3>
    <CustomField4><![CDATA[]]></CustomField4>
    <CustomField5><![CDATA[]]></CustomField5>
    </TransactionInfo>
    <ShipmentList>
    <Shipment>
    <ShipmentNumber>1</ShipmentNumber>
    <ShipNameTitle>Mr.</ShipNameTitle>
    <ShipFirstName><![CDATA[John]]></ShipFirstName>
    <ShipLastName><![CDATA[Smith]]></ShipLastName>
    <ShipNameSuffix><![CDATA[]]></ShipNameSuffix>
    <ShipBuyerCompany><![CDATA[]]></ShipBuyerCompany>
    <ShipBuyerTitle><![CDATA[]]></ShipBuyerTitle>
    <ShipAddress1><![CDATA[15 Smith Lane]]></ShipAddress1>
    <ShipAddress2><![CDATA[]]></ShipAddress2>
    <ShipCity><![CDATA[Boston]]></ShipCity>
    <ShipRegion>MA</ShipRegion>
    <ShipZip><![CDATA[02116-6501]]></ShipZip>
    <ShipCountry><![CDATA[US]]></ShipCountry>
    <ShipDayPhone><![CDATA[617-555-5555]]></ShipDayPhone>
    <ShipEvePhone><![CDATA[]]></ShipEvePhone>
    <ShipInstructions><![CDATA[]]></ShipInstructions>
    <ShipCarrier>FedEx</ShipCarrier>
    <ShipClass>Ground</ShipClass>
    <ShipCharge>57.97</ShipCharge>
    <ShipInsurance>0.00</ShipInsurance>
    <ShipTaxRate></ShipTaxRate>
    <ShipmentTax>0.00</ShipmentTax>
    <ShipmentOther></ShipmentOther>
    <ShipmentSubTotal>426.50</ShipmentSubTotal>
    <ShippingReserved1><![CDATA[]]></ShippingReserved1>
    <ShippingReserved2><![CDATA[]]></ShippingReserved2>
    <Items>
        <Item>
        <LotTitle><![CDATA[Sample Checkout Item 1]]></LotTitle>
        <SKU><![CDATA[SCI1]]></SKU>
        <SiteName><![CDATA[Checkout Direct]]></SiteName>
        <MarketplaceUserID>mark@ChannelAdvisor.com</MarketplaceUserID>
        <SiteAuctionID><![CDATA[100000235]]></SiteAuctionID>
        <SiteTransactionID><![CDATA[0]]></SiteTransactionID>
        <QtyWon>2.00</QtyWon> <Bid>85.50</Bid>
        <ClosingTimeLTz>06/15/2009 10:48:05 AM</ClosingTimeLTz>
        <UnitWeight>1.5</UnitWeight>
        <WarehouseLocationNumber><![CDATA[]]></WarehouseLocationNumber>
        <Classification><![CDATA[]]></Classification>
        <ItemReserved1><![CDATA[]]></ItemReserved1>
        <ItemReserved2><![CDATA[]]></ItemReserved2>
        </Item>
        <Item>
        <LotTitle><![CDATA[Sample Checkout Item 2]]></LotTitle>
        <SKU><![CDATA[SCI2]]></SKU>
        <SiteName><![CDATA[Checkout Direct]]></SiteName>
        <MarketplaceUserID>mark@ChannelAdvisor.com</MarketplaceUserID>
        <SiteAuctionID><![CDATA[100000236]]></SiteAuctionID>
        <SiteTransactionID><![CDATA[0]]></SiteTransactionID>
        <QtyWon>1.00</QtyWon> <Bid>255.50</Bid>
        <ClosingTimeLTz>06/15/2009 10:48:22 AM</ClosingTimeLTz>
        <UnitWeight>10</UnitWeight>
        <WarehouseLocationNumber><![CDATA[]]></WarehouseLocationNumber>
        <Classification><![CDATA[]]></Classification>
        <ItemReserved1><![CDATA[]]></ItemReserved1>
        <ItemReserved2><![CDATA[]]></ItemReserved2>
        </Item>
    </Items>
    </Shipment>
    </ShipmentList>
</BuyerPurchase>
</PurchaseList>
</CheckoutReport> 


This report contains no invoices:

<?xml version="1.0" encoding="iso-8859-1"?>
<CheckoutReport>
<MerchantName>ChannelAdvisor Enterprise Demos 1</MerchantName>
<ReportId>36927</ReportId>
<ReportPeriodStart>6/15/2009 12:00:00 AM (ET)</ReportPeriodStart>
<ReportPeriodEnd>6/16/2009 11:00:00 AM (ET)</ReportPeriodEnd>
<Version>2.0</Version>
<PurchaseList>
</PurchaseList>
</CheckoutReport>

And here is an example of an error:

<Error>Report ID 36891 does not exist for account 10055350</Error>

 Return to top

The ChannelAdvisor Checkout Report XML Interface is a mechanism for ChannelAdvisor sellers to download checkout report information in an automated fashion over an HTTPS connection. The data content provided through this interface is identical to that already provided in the ChannelAdvisor downloadable CSV reports, but through the use of XML formatting is better structured for integration into a ChannelAdvisor seller’s internal systems. Data is accessed by passing specific query string parameters to a URL provided by ChannelAdvisor, and returned via securely streamed XML page content.

NOTE: This method is no longer the recommended way to download order information from your ChannelAdvisor account.  For an improved developer experience, please consider using one of our newer SOAP or REST based APIs.  Information on these methods can be found in our API Integration Guide.

 

Tasks to Complete


 


This page will describe the protocol for these request parameters and the response content, as well as provide some sample data to view this interface in action.

Return to top

Requesting Reports



Requests for report data are currently made via the use of query string parameters added to the following base URL:

https://merchant.ChannelAdvisor.com/Export/CFExport.dll?CheckoutReport?<PARAMETERS_HERE>

The following table describes the available parameters:

 Parameter Name  Description  Required?  Sample Value 
 pid  Account Profile ID. A numeric value unique to each ChannelAdvisor Account (see section below to locate this ID)  Yes  10055350 
 mn  Login MemberName – login id provided by ChannelAdvisor to access your reports, typically an e-mail address. If you do not have a login id or wish to create a limited access ID just for these reports, please contact your ChannelAdvisor Account Manager.  Yes  CheckoutTest@ChannelAdvisor.com 
 pw  Login password – corresponding password to the login id specified by “mn”.  Yes  FETCHIT! 
 ver  Report version. Currently must be set to version “2” or version "3" Yes  3
 rid  Report ID. Use this to query a specific report ID, as shown on the Checkout Reports section of the application. If this and “dt” are omitted, the most recently run report will be returned.  No  36892 
 dt  Report Date/Time. Use this to query the report that spans the date-time passed in. Useful when a specific report ID is not known. Timezone should match that set for the account matching the “pid” value passed in and should be in this format: MM/DD/YY HH:MM:SS, where HH is in 24 hour time.  No  6/15/09 10:00:00 
 sep  Show Encrypted Password. Pass a value of “1” to return an encrypted/encoded version of the “pw” parameter to be used for the “pe” parameter below. No report will be returned.  No  1 
 pe  Encrypted password. Use the results of the “sep=1” command for this parameter to be used in place of the “pw” parameter if you wish to encrypt your password in the URL query string.  No  *UeTN%5C8p 

Return to top

Locating your Account Profile ID (“pid” parameter)


To determine your Account Profile ID in ChannelAdvisor:

  1. Navigate to My Account > Utilities > Company Setup.
  2. Locate the Profile ID in the Company Information section.

Note: This number also appears in the URL of most pages in the application after "?apid=.

 
Return to top

Sample Requests


This request will return a sample report for account “10055350” and report “36892”:

https://merchant.ChannelAdvisor.com/Export/CFExport.dll?CheckoutReport?mn=CheckoutTest@ChannelAdvisor.com&pw=fetchit!&pid=10055350&rid=36892&ver=3

Note how the data included in this report matches exactly that data included in the corresponding .CSV file you may be more accustomed to.

This next request will return the same report, but uses the “dt” date parameter rather than the “rid” parameter to return a particular report. This is especially useful for locating old reports when you do not know the particular report ID (note that report IDs are currently not consecutive per-account, but this may be something added down the road). The datetime value passed in should be in the timezone configured for that account, and should be of the MM-DD-YY HH:MM:SS format. Some HTTP client software may require you to URL encode this value as well.

https://merchant.ChannelAdvisor.com/Export/CFExport.dll?CheckoutReport?mn=CheckoutTest@ChannelAdvisor.com&pw=fetchit!&pid=10055350&ver=3&dt=6/15/09 10:15:00

The above link returns report 36892 because the input time of 6/15/09 10:15:00 is greater than or equal to the start of this report range, 6/15/2009 12:00:00 AM (ET), and less than the end of this report range, 6/15/2009 11:00:00 AM (ET). Similarly this will return 36892:

https://merchant.ChannelAdvisor.com/Export/CFExport.dll?CheckoutReport?mn=CheckoutTest@ChannelAdvisor.com&pw=fetchit!&pid=10055350&ver=3&dt=6/15/09 00:00:00

But this will return the next report for this account, 36927:

https://merchant.ChannelAdvisor.com/Export/CFExport.dll?CheckoutReport?mn=CheckoutTest@ChannelAdvisor.com&pw=fetchit!&pid=10055350&ver=3&dt=6/15/09 11:00:00

If you wish to pass your password in an encrypted format, first use the “sep” parameter to return your encrypted password, for example:

https://merchant.ChannelAdvisor.com/Export/CFExport.dll?CheckoutReport?mn=CheckoutTest@ChannelAdvisor.com&pw=fetchit!&pid=10055350&sep=1

And then use the result for the “pe” parameter (rather than “pw”) in all subsequent requests:

https://merchant.ChannelAdvisor.com/Export/CFExport.dll?CheckoutReport?mn=CheckoutTest@ChannelAdvisor.com&pid=10055350&rid=36892&ver=3&pe=*UeTN%5C8p

Return to top

Automating Report Retrieval


The method used for automating your report retrieval depends heavily on the checkout report frequency configured for your account (Run checkout reports every setting on the Sales > Orders/Transactions > Checkout Report Settings in ChannelAdvisor) and your desired workflow.

There are two primary methods for automating your checkout retrieval requests:

  1. Always retrieve the most recently generated report
  2. Retrieve reports based on date

Both are described below.
 
Return to top

Retrieving Most Recently Generated Report


You can retrieve the most recently generated report by omitting the “rid” and “dt” parameters, for example:

https://merchant.ChannelAdvisor.com/Export/CFExport.dll?CheckoutReport?mn=CheckoutTest@ChannelAdvisor.com&pw=fetchit!&pid=10055350&ver=3

This approach allows an automated task to hit the same URL at predefined intervals based on the report frequency configured for your account. Care must be taken in this approach, though. Although ChannelAdvisor makes every attempt to generate all reports within an hour, the actual elapsed time may vary due to current system load and scheduled or unscheduled system outages.

The recommended client implementation would cache the latest “ReportPeriodEnd” value returned (more on this below), and schedule a retry if the ReportPeriodEnd matches a ReportPeriodEnd already processed on an earlier attempt. Any scheduled retries should be attempted at intervals smaller than the configured report generation frequency, so for example if you run reports every 24 hours and an attempt at 12:30 AM fails, you may want to retry again at 2:30 AM. To reduce overall system load, we ask that you limit retries to an as-needed basis.

This approach works well for long report durations, say 12 or 24 hours. For shorter durations, you may want to use the “retrieve reports based on date” method.
 
Return to top

Retrieving Reports Based on Date


In this approach, the “dt” parameter would also be used to target a specific report spanning a specific time range. This approach is better suited for shorter report intervals, say anything less than every 12 hours, but does come at the cost of additional implementation complexity.

In this method, you should continue to cache the ReportPeriodEnd returned by any prior queries, as explained above, but on subsequent calls you should pass that same ReportPeriodEnd value via the “dt” parameter. So, for example, if your first query returned a ReportPeriodEnd value 6/15/2009 11:00:00, you could pass in your next call a dt value of “6/15/2009 11:00:00”. If the new report has not yet been generated, you will not receive a new ReportPeriodEnd value in response. If it has been generated, you can cache this new value and specify this in your “dt” parameter for your next scheduled attempt. Suitable retries should be scheduled based on your report frequency to guarantee all data is downloaded in a timely fashion.
 
Return to top

Planning for Scheduled and Unscheduled System Outages


Although ChannelAdvisor makes every attempt to provide access to its reporting system on a 24/7 basis, there are windows of scheduled and unscheduled system downtime that should be accounted for in any client polling architecture.

The ChannelAdvisor checkout reports will always span contiguous ranges of time regardless of configured report frequency or report generation time. Therefore, if the ChannelAdvisor system is scheduled to be brought offline from 4am to 8am for a planned maintenance cycle, but your report generation frequency is set to a shorter time duration of 1 hour, the reports generated could span a time range longer than that 1 hour. Thus in this scenario the 2:00 AM - 3:00 AM report would run normally since the reporting system is still online after 3:00 AM. The 3:00 AM - 4:00 AM report, though, would not run since the system is currently offline (reports are run after the close of the hour). Similarly the report system would not run after 5:00 AM, 6:00 AM, or 7:00 AM. Once the system is brought back online at 8:00 AM, though, the report generation task would detect the gap and generate a report spanning the 3:00 AM - 8:00 AM time span. From there processing would continue as normal for reports spanning 8:00 AM - 9:00 AM, 9:00 AM - 10:00 AM, and so forth.

This behavior is by design and should be taken under consideration for any client polling implementations.
 
Return to top

Response Report XML Format



The response XML returned by the above queries are encoded in ISO-8859-1 format and follow the tag structure defined below. CDATA tags are indicated for those string values that could potentially contain markup characters that could confuse an XML parser. Here is an example of such a tag:

<BillingDayPhone><![CDATA[919-847-5555]]></BillingDayPhone>

View the report tag data hierarchy.

Return to top


Sample XML Responses


This is an order with two invoices, with one item included in the first invoice and two in the second.

<?xml version="1.0" encoding="iso-8859-1"?>
<CheckoutReport>
<MerchantName>ChannelAdvisor Enterprise Demos 1</MerchantName>
<ReportId>36892</ReportId>
<ReportPeriodStart>6/15/2009 12:00:00 AM (ET)</ReportPeriodStart>
<ReportPeriodEnd>6/16/2009 11:00:00 AM (ET)</ReportPeriodEnd>
<Version>2.0</Version>
<PurchaseList>
<BuyerPurchase>
    <TransactionInfo>
    <InvoiceNumber>5647151</InvoiceNumber>
    <CheckoutDate>06/15/2009 10:47:37 AM</CheckoutDate>
    <TotalInvoiceAmount>102.48</TotalInvoiceAmount>
    <PaymentType>VI</PaymentType>
    <PaymentId><![CDATA[4111-1111-1111-1111]]></PaymentId>
    <ExpDate>5/2004</ExpDate>
    <CVVNbr></CVVNbr>
    <PaymentTransID><![CDATA[]]></PaymentTransID>
    <TransRefOut><![CDATA[]]></TransRefOut>
    <TotalTax>5.99</TotalTax>
    <OrderID><![CDATA[119]]></OrderID>
    <OtherCost><![CDATA[0.00]]></OtherCost>
    <BillingNameTitle>Mr.</BillingNameTitle>
    <BillingFirstName><![CDATA[Bill]]></BillingFirstName>
    <BillingLastName><![CDATA[Isham]]></BillingLastName>
    <BillingNameSuffix><![CDATA[III]]></BillingNameSuffix>
    <BillingBuyerCompany><![CDATA[IshamCorpTechnologies]]></BillingBuyerCompany>
    <BillingBuyerTitle><![CDATA[Chief Executive Officer]]></BillingBuyerTitle>
    <BillingAddress1><![CDATA[12 Main St.]]></BillingAddress1>
    <BillingAddress2><![CDATA[]]></BillingAddress2>
    <BillingCity><![CDATA[Raleigh]]></BillingCity>
    <BillingRegion>NC</BillingRegion>
    <BillingZip><![CDATA[27613]]></BillingZip>
    <BillingCountry><![CDATA[US]]></BillingCountry>
    <BillingDayPhone><![CDATA[919-847-5555]]></BillingDayPhone>
    <BillingEveningPhone><![CDATA[]]></BillingEveningPhone>
    <BillingReserved1><![CDATA[]]></BillingReserved1>
    <MarketplaceEmail><![CDATA[isham@ChannelAdvisor.com]]></MarketplaceEmail>
    <BuyerEmailOptIn>0</BuyerEmailOptIn>
    <ResellerID><![CDATA[]]></ResellerID>
    <CustomField1><![CDATA[]]></CustomField1>
    <CustomField2><![CDATA[]]></CustomField2>
    <CustomField3><![CDATA[]]></CustomField3>
    <CustomField4><![CDATA[]]></CustomField4>
    <CustomField5><![CDATA[]]></CustomField5>
    </TransactionInfo>
    <ShipmentList>
    <Shipment>
    <ShipmentNumber>1</ShipmentNumber>
    <ShipNameTitle>Dr.</ShipNameTitle>
    <ShipFirstName><![CDATA[Mark]]></ShipFirstName>
    <ShipLastName><![CDATA[Isham]]></ShipLastName>
    <ShipNameSuffix><![CDATA[Sr.]]></ShipNameSuffix>
    <ShipBuyerCompany><![CDATA[ChannelAdvisor Inc.]]></ShipBuyerCompany>
    <ShipBuyerTitle><![CDATA[Sr. Software Engineer]]></ShipBuyerTitle>
    <ShipAddress1><![CDATA[2701 Aerial Center Parkway]]></ShipAddress1>
    <ShipAddress2><![CDATA[Suite 100]]></ShipAddress2>
    <ShipCity><![CDATA[Morrisville]]></ShipCity>
    <ShipRegion>NC</ShipRegion>
    <ShipZip><![CDATA[27560]]></ShipZip>
    <ShipCountry><![CDATA[US]]></ShipCountry>
    <ShipDayPhone><![CDATA[919-465-5680]]></ShipDayPhone>
    <ShipEvePhone><![CDATA[919-465-5555]]></ShipEvePhone>
    <ShipInstructions><![CDATA[Leave with receptionist!]]></ShipInstructions>
    <ShipCarrier>UPS</ShipCarrier>
    <ShipClass>Ground</ShipClass>
    <ShipCharge>10.99</ShipCharge>
    <ShipInsurance>0.00</ShipInsurance>
    <ShipTaxRate></ShipTaxRate>
    <ShipmentTax>5.99</ShipmentTax>
    <ShipmentOther></ShipmentOther>
    <ShipmentSubTotal>85.50</ShipmentSubTotal>
    <ShippingReserved1><![CDATA[]]></ShippingReserved1>
    <ShippingReserved2><![CDATA[]]></ShippingReserved2>
    <Items>
        <Item>
        <LotTitle><![CDATA[Sample Checkout Item 1]]></LotTitle>
        <SKU><![CDATA[SCI1]]></SKU>
        <SiteName><![CDATA[Checkout Direct]]></SiteName>
        <MarketplaceUserID>isham@ChannelAdvisor.com</MarketplaceUserID>
        <SiteAuctionID><![CDATA[100000234]]></SiteAuctionID>
        <SiteTransactionID><![CDATA[0]]></SiteTransactionID>
        <QtyWon>1.00</QtyWon>
        <Bid>85.50</Bid>
        <ClosingTimeLTz>06/15/2009 10:44:43 AM</ClosingTimeLTz>
        <UnitWeight>1.5</UnitWeight>
        <WarehouseLocationNumber><![CDATA[]]></WarehouseLocationNumber>
        <Classification><![CDATA[]]></Classification>
        <ItemReserved1><![CDATA[]]></ItemReserved1>
        <ItemReserved2><![CDATA[]]></ItemReserved2>
        </Item>
    </Items>
    </Shipment>
    </ShipmentList>
    </BuyerPurchase>
    <BuyerPurchase>
    <TransactionInfo>
    <InvoiceNumber>5647152</InvoiceNumber>
    <CheckoutDate>06/15/2009 10:51:37 AM</CheckoutDate>
    <TotalInvoiceAmount>484.47</TotalInvoiceAmount>
    <PaymentType>MO</PaymentType>
    <PaymentId><![CDATA[]]></PaymentId>
    <ExpDate>0/0</ExpDate>
    <CVVNbr></CVVNbr>
    <PaymentTransID><![CDATA[]]></PaymentTransID>
    <TransRefOut><![CDATA[]]></TransRefOut>
    <TotalTax>0.00</TotalTax>
    <OrderID><![CDATA[120]]></OrderID>
    <OtherCost><![CDATA[0.00]]></OtherCost>
    <BillingNameTitle>Mr.</BillingNameTitle>
    <BillingFirstName><![CDATA[John]]></BillingFirstName>
    <BillingLastName><![CDATA[Smith]]></BillingLastName>
    <BillingNameSuffix><![CDATA[]]></BillingNameSuffix>
    <BillingBuyerCompany><![CDATA[]]></BillingBuyerCompany>
    <BillingBuyerTitle><![CDATA[]]></BillingBuyerTitle>
    <BillingAddress1><![CDATA[15 Smith Lane]]></BillingAddress1>
    <BillingAddress2><![CDATA[]]></BillingAddress2>
    <BillingCity><![CDATA[Boston]]></BillingCity>
    <BillingRegion>MA</BillingRegion>
    <BillingZip><![CDATA[02116-6501]]></BillingZip>
    <BillingCountry><![CDATA[US]]></BillingCountry>
    <BillingDayPhone><![CDATA[617-555-5555]]></BillingDayPhone>
    <BillingEveningPhone><![CDATA[]]></BillingEveningPhone>
    <BillingReserved1><![CDATA[]]></BillingReserved1>
    <MarketplaceEmail><![CDATA[mark@ChannelAdvisor.com]]></MarketplaceEmail>
    <BuyerEmailOptIn>0</BuyerEmailOptIn>
    <ResellerID><![CDATA[]]></ResellerID>
    <CustomField1><![CDATA[]]></CustomField1>
    <CustomField2><![CDATA[]]></CustomField2>
    <CustomField3><![CDATA[]]></CustomField3>
    <CustomField4><![CDATA[]]></CustomField4>
    <CustomField5><![CDATA[]]></CustomField5>
    </TransactionInfo>
    <ShipmentList>
    <Shipment>
    <ShipmentNumber>1</ShipmentNumber>
    <ShipNameTitle>Mr.</ShipNameTitle>
    <ShipFirstName><![CDATA[John]]></ShipFirstName>
    <ShipLastName><![CDATA[Smith]]></ShipLastName>
    <ShipNameSuffix><![CDATA[]]></ShipNameSuffix>
    <ShipBuyerCompany><![CDATA[]]></ShipBuyerCompany>
    <ShipBuyerTitle><![CDATA[]]></ShipBuyerTitle>
    <ShipAddress1><![CDATA[15 Smith Lane]]></ShipAddress1>
    <ShipAddress2><![CDATA[]]></ShipAddress2>
    <ShipCity><![CDATA[Boston]]></ShipCity>
    <ShipRegion>MA</ShipRegion>
    <ShipZip><![CDATA[02116-6501]]></ShipZip>
    <ShipCountry><![CDATA[US]]></ShipCountry>
    <ShipDayPhone><![CDATA[617-555-5555]]></ShipDayPhone>
    <ShipEvePhone><![CDATA[]]></ShipEvePhone>
    <ShipInstructions><![CDATA[]]></ShipInstructions>
    <ShipCarrier>FedEx</ShipCarrier>
    <ShipClass>Ground</ShipClass>
    <ShipCharge>57.97</ShipCharge>
    <ShipInsurance>0.00</ShipInsurance>
    <ShipTaxRate></ShipTaxRate>
    <ShipmentTax>0.00</ShipmentTax>
    <ShipmentOther></ShipmentOther>
    <ShipmentSubTotal>426.50</ShipmentSubTotal>
    <ShippingReserved1><![CDATA[]]></ShippingReserved1>
    <ShippingReserved2><![CDATA[]]></ShippingReserved2>
    <Items>
        <Item>
        <LotTitle><![CDATA[Sample Checkout Item 1]]></LotTitle>
        <SKU><![CDATA[SCI1]]></SKU>
        <SiteName><![CDATA[Checkout Direct]]></SiteName>
        <MarketplaceUserID>mark@ChannelAdvisor.com</MarketplaceUserID>
        <SiteAuctionID><![CDATA[100000235]]></SiteAuctionID>
        <SiteTransactionID><![CDATA[0]]></SiteTransactionID>
        <QtyWon>2.00</QtyWon> <Bid>85.50</Bid>
        <ClosingTimeLTz>06/15/2009 10:48:05 AM</ClosingTimeLTz>
        <UnitWeight>1.5</UnitWeight>
        <WarehouseLocationNumber><![CDATA[]]></WarehouseLocationNumber>
        <Classification><![CDATA[]]></Classification>
        <ItemReserved1><![CDATA[]]></ItemReserved1>
        <ItemReserved2><![CDATA[]]></ItemReserved2>
        </Item>
        <Item>
        <LotTitle><![CDATA[Sample Checkout Item 2]]></LotTitle>
        <SKU><![CDATA[SCI2]]></SKU>
        <SiteName><![CDATA[Checkout Direct]]></SiteName>
        <MarketplaceUserID>mark@ChannelAdvisor.com</MarketplaceUserID>
        <SiteAuctionID><![CDATA[100000236]]></SiteAuctionID>
        <SiteTransactionID><![CDATA[0]]></SiteTransactionID>
        <QtyWon>1.00</QtyWon> <Bid>255.50</Bid>
        <ClosingTimeLTz>06/15/2009 10:48:22 AM</ClosingTimeLTz>
        <UnitWeight>10</UnitWeight>
        <WarehouseLocationNumber><![CDATA[]]></WarehouseLocationNumber>
        <Classification><![CDATA[]]></Classification>
        <ItemReserved1><![CDATA[]]></ItemReserved1>
        <ItemReserved2><![CDATA[]]></ItemReserved2>
        </Item>
    </Items>
    </Shipment>
    </ShipmentList>
</BuyerPurchase>
</PurchaseList>
</CheckoutReport> 


This report contains no invoices:

<?xml version="1.0" encoding="iso-8859-1"?>
<CheckoutReport>
<MerchantName>ChannelAdvisor Enterprise Demos 1</MerchantName>
<ReportId>36927</ReportId>
<ReportPeriodStart>6/15/2009 12:00:00 AM (ET)</ReportPeriodStart>
<ReportPeriodEnd>6/16/2009 11:00:00 AM (ET)</ReportPeriodEnd>
<Version>2.0</Version>
<PurchaseList>
</PurchaseList>
</CheckoutReport>

And here is an example of an error:

<Error>Report ID 36891 does not exist for account 10055350</Error>

 Return to top

0
Your rating: None Average: 5 (1 vote)
0
Your rating: None Average: 5 (1 vote)