Order API v2 - Customer values & marketplace tax

In order to support the up-coming legislation changes, we have made some API changes which allow your orders to identify which have had Sales Tax/VAT collected and remitted by Fruugo as the marketplace and provides the relevant tax IDs, but also for you to obtain the order totals paid by the customer in the customers local currency.

The purpose of this new information is to allow you to have the correct local values, taxes, and tax information for their customs declarations. If you have pre-built integrations to logistics companies within your platform, these new values are those which should be used to auto-generate labelling, customs declarations and packing slips. The inclusion where relevant of the Fruugo tax IDs, as well the customs total should ensures you are able to correctly complete customs declarations, and ensure a smooth journey for all shipments as they cross borders.

New Elements

The new values are in two distinct collections. These are:

i) Customer Order Totals

Within the orderLine (item) level, there is a new collection of elements under 'customer' which provide the item order totals as paid by the customer and their currency code. To be used for customs declarations and shipment labelling. These include the item price, item tax, total price, total tax, and the customers local currency. Example:

                <o:customer>
                   <o:customerItemPriceExcVat>3.59</o:customerItemPriceExcVat>
                   <o:customerItemVat>0.36</o:customerItemVat>
                   <o:totalCustomerPriceExcVat>3.59</o:totalCustomerPriceExcVat>
                   <o:totalCustomerVat>0.36</o:totalCustomerVat>
                   <o:customerCurrency>AUD</o:customerCurrency>
                </o:customer>

ii) Fruugo Tax Identifier

At order level, there are three new elements. The first is 'fruugoTax' which is a constant boolean to identify whether Fruugo has collected and paid the tax on the order on your behalf (true/false). In the instances where the value is true and Fruugo is responsible for the payment of sales tax/VAT, the order will contain two additional elements - fruugoTaxID and fruugoEORI - which provides our tax information for the customs declaration of that order, and should be used by the retailer. Example:

        <o:fruugoTax>true</o:fruugoTax>
        <o:fruugoTaxID>300015541142</o:fruugoTaxID>
        <o:fruugoEORI>GB929353206000</o:fruugoEORI>

Availability

The new order download XML is available in parallel to the existing order API download XML to allow you to make a smooth transition across when you have completed your development to support these new fields.

Current order API download endpoint: https://www.fruugo.com/orders/download
New order API download endpoint: https://www.fruugo.com/orders/download/v2

Documentation

Requests/calls: see 'Download orders - v2': https://fruugo.atlassian.net/wiki/spaces/RR/pages/66158675
v2 Download XML Specification: https://fruugo.atlassian.net/wiki/spaces/RR/pages/2133524481
v2 Example Download XML Output: https://fruugo.atlassian.net/wiki/spaces/RR/pages/2133458976
The XML schema and an example order XML download are attached to the XML Specification documentation.

Packing List/Invoice

We would recommend all retailers also include a copy of the customers packing list/invoice within their shipment, and attached to the package to ensure a smoother customs journey. As a result, if you are yet to include the download of our packing list from the order API it would be prudent to include this within the functionality.

The PDF packing list can be downloaded from the endpoint: https://www.fruugo.com/orders/packinglist. Even Though the packing list does require the shipmentId parameter from our system to download the packing list, you can also obtain it prior to shipment by providing 0 as the shipmentId parameter.