Export Orders

The export orders API allows an external system to query bindCommerce to obtain orders that have been imported from the sales platforms (eCommerce, marketplace, etc ...).

The choice of which orders to expose to the API is made through the bindCommerce interface. It is possible to create multiple connectors (which correspond to different URLs to be called by the external system), each of which responding to a different configuration (filter which orders to return to the API).

Orders can act jointly on the API

an order filter: based on the characteristics of the order (e.g. shipment status, destination of the goods, etc ...)
a product filter: based on the characteristics of the products contained therein (for example, it is possible to export only orders that contain order lines that refer to products from a specific supplier)

It is also possible to apply transformations to exported orders (such as changing the billing address or prices).

Export order configuration

bindCommerce allows you to export all orders to API management thanks to a simple configuration.

To create the configuration from the bindCommerce control panel go to the menu:

API >> Export orders

Click on Add and fill in the required fields as shown below:

Configuration Name: Choose the desired name
Technology: API
Order processing: Premium function. For the configuration, please refer to the appropriate Order Transformation technical guide
Web Server for file storage: if this field is set, the connector can be inserted in a bindCommerce procedure and the file stored in the FTP area indicated. To ensure that the file stored in the FTP area has the date and time as a suffix in the name, you need to create a custom parameter with the name ERP_FILENAME_BY_DATETIME and value 1.

Click on SAVE AND CLOSE.

Export order connector

To create the connector that will allow you to export orders from bindCommerce to the API management system, you need to go to the menu:

Processes >> Connectors

Click on Add and fill in the fields as follows:

Connector Name: Choose the name you think is most appropriate
Node Type (Technology): API
Node: the node created earlier
Connector type: API [export orders]

By clicking on SAVE AND CONTINUE you will have access to the additional fields to be filled in.

The calling system must use the following string: copy the URL in this field
Connector Configuration: Select the configuration created earlier
Filter on sales documents: to create a filter on orders, please follow the instructions given in the specific Order Filters tutorial
Product filter: to create a product filter, please follow the instructions given in the Product Filters tutorial

Click on SAVE AND CLOSE.

Call and authentication

The call is made to the URL generated by bindCommerce for the specific connector.
Authentication takes place through a token assigned by bindCommerce. The parameter is passed into the request header.

Example PHP script to make the call

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
          CURLOPT_URL => "https://hABCDE.bindcommerce.cloud/integrator-tool/api/export_orders.php?connector=2",
          CURLOPT_SSL_VERIFYHOST => true,
          CURLOPT_RETURNTRANSFER => true,
          CURLOPT_HTTPHEADER => array(
                "cache-control: no-cache",
                "token: 84b670ea63539f5bc0572a260f1f4dfb"
          ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}

Orders file

An XML file containing the orders is provided in response to the request.

Example file

<?xml version="1.0" encoding="UTF-8"?>
<Documents><Document>
<General> ---- dalla versione 4
         <DocumentType>C</DocumentType>
         <bindCommerceNumber>15918</bindCommerceNumber>
         <Number>89568</Number>
         <Node>eBay superseller</Node>
         <NodeID>55</NodeID>
         <Technology>Marketplace eBay</Technology>
         <Market></Market>
         <Date>2018-03-22 17:34:07</Date>
         <StatebindID>1</StatebindID>
         <StateCode>C</StateCode>
         <StateName>Completed</StateName>
</General> ---- dalla versione 4
<Customer>
         <Code>14833</Code>
         <Name>Daniele</Name>
         <Surname>Beccarelli </Surname>
         <Company></Company>
         <Address>Via delle Rosine 70 </Address>
         <Postcode>00121</Postcode>
         <City>Lido di Ostia</City>
         <Province>RM</Province>
         <CountryCode>IT</CountryCode>
         <VatCode></VatCode>
         <FiscalCode></FiscalCode>
         <Phone>32871800000</Phone>
         <MobPhone></MobPhone>
         <Email>This email address is being protected from spambots. You need JavaScript enabled to view it.;;/Email>
</Customer>
<Delivery>
         <Name>Daniele</Name>
         <Surname>Beccarelli </Surname>
         <Company></Company>
         <Address>Via delle Rosine 70 </Address>
         <Postcode>00121</Postcode>
         <City>Lido di Ostia</City>
         <Province>RM</Province>
         <CountryCode>IT</CountryCode>
         <Phone>32871800000</Phone>
         <MobPhone></MobPhone>
         <Email>This email address is being protected from spambots. You need JavaScript enabled to view it.;;/Email>
</Delivery>
<Payments>
         <PaymentName>PayPal</PaymentName>
         <PaymentCode>PP</PaymentCode>
         <PaymentTotal>0.00</PaymentTotal>
         <PaymentStatus>Complete</PaymentStatus>
         <PaidTime>2018-03-22 17:34:31</PaidTime>
</Payments>
<Rows>
         <Row>
         <bindID>17027</bindID>
         <Code>3961824</Code>
         <Barcode>8000072058222</Barcode>
         <Description>EURO 3 PLAST Sottovaso medea cm24 verde Giardino Arredo da esterno</Description>
         <Qty>4</Qty>
         <ProductDimensions>
         <Weight>0.05</Weight>
         <WeightUom>Kg</WeightUom>
         <WeightVolume>0</WeightVolume>
         <LwhUom></LwhUom>
         <Length>24</Length>
         <Width>24</Width>
         <Height>4</Height>
         </ProductDimensions>
         <ProductCategories>
         <Category></Category>
         </ProductCategories>
         <Picture>https://webserver.superseller.com/bindcommerce/product/big/17/a5f5_cb73a_130572.jpeg</Picture>
         <Supplier>Rossi S.p.A.</Supplier>
          <SupplierByRepricing>Rossi S.p.A api name</SupplierByRepricing>
         <SupplierByRepricingCost>1.23000</SupplierByRepricingCost>
         <SupplierPrice>0.58</SupplierPrice>
         <MPN>3961824</MPN>
         <PriceVatExcluded>1.12</PriceVatExcluded>
         <Price>1.37000</Price>
         <Discounts>0.00000</Discounts>
         <VatRate>22</VatRate>
         <TotalVatExcluded>4.49</TotalVatExcluded>
         <Total>5.48000</Total>
         <TotalDiscounted>5.48000</TotalDiscounted>
         <Currency>EUR</Currency>
         <Params>
                  <Param>
                  <Name>Param name</Name>
                  <Value>Param value example</Value>
                  </Param>
         </Params>

         </Row>
</Rows>
<Amounts>
         <TotalWithoutTax>4.49</TotalWithoutTax>
         <VatAmount>0.99</VatAmount>
         <Total>11.97</Total>
         <Currency>EUR</Currency>
         <ShippingCost>6.49</ShippingCost>
         <ShippingCostWithoutTax>6.49</ShippingCostWithoutTax>
         <ShippingTax>0.22</ShippingTax>
         <InternalComment></InternalComment>
         <SellerNote></SellerNote>
         <CouponDiscount>0.00</CouponDiscount>
         <CouponCode></CouponCode>
         <DiscountToCart></DiscountToCart>
</Amounts>
<Commission>
         <PayPalCommission>0.61</PayPalCommission>
         <PayPalTransactionID></PayPalTransactionID>
         <eBayCommission>0.48</eBayCommission>
         <eBayAccount>suo_account</eBayAccount>
         <eBayAdjustmentAmount>0.00</eBayAdjustmentAmount>
         <eBayAmountSaved>13.47</eBayAmountSaved>
</Commission>
<Shipping>
         <Carrier>Altro corriere 3-5 giorni</Carrier>
         <TrackingNumber></TrackingNumber>
         <TransportedWeight>0.2</TransportedWeight>
         <ShippedTime>0000-00-00 00:00:00</ShippedTime>
</Shipping>
</Document></Documents>

File fields

DOCUMENT HEAD FIELDS

Field	Description
DocumentType	Type of document. In standard implementations is used C = Sales order.
bindCommerceNumber	Internal bindCommerce ID for the order. In normal conditions it is a numerical counter. If you are asked to split orders by supplier, the format becomes [order_id] - [supplier_id]. To request the split, the API_ORDERS_OUT_SPLIT_SUPPLIER parameter must be set to 1 in the customized parameters table.
Number	Order number assigned by the sales channel
Node	Name of the bindCommerce node from which the order originates (chosen by the context administrator). It may contain the name of the marketplace and the account (e.g. eBay superseller) or the name of the website (e.g. www.superseller.com)
Technology	Technology to which the node belongs. Some possible values are for example: eBay Marketplace, Amazon Marketplace, ePrice Marketplace, ManoMano Marketplace, Wish Marketplace, Magento eCommerce, Prestashop eCommerce, etc ...
Market	Order market (data compiled only for some sales channels)
Date	Date and time of execution of the order
LastUpdate	Date and time of the last update of the document
StatebindID	BindCommerce order status id
StateCode	Order status code. Order states are inherited directly from the platforms from which the order originates.
StateName	Name of the order status
Customer	Node that sends tags relating to customer information (billing data)
Delivery	Node that sends tags relating to the information on the recipient of the shipment
Payments	Node that refers to tags related to Payment information
Rows	Node that refers to tags relating to order lines
Amounts	Node that refers to tags relating to information on amounts
Commission	Node that refers to tags relating to information on Commissions
Shipping	Node that refers to tags related to shipping information

BILLING INFORMATION (CUSTOMER)

Field	Description
Code	Numeric code that identifies the customer
Name	Name
Surname	Surname
Company	Company
Address	Street Address
Postcode	Postcode
City	City of residence
Province	District
CountryCode	ISO 3166-1 Alpha-2 country code (e.g. IT)
VatCode	VAT Number
FiscalCode	Personal number (e.g. NINo for UK)
Phone	Phone number
MobPhone	Mobile number
Email	E-mail. In some cases it contains a non-real email address (for example Amazon assigns a temporary relay address)
EInvoiceDestCode	Recipient code for electronic invoicing (SDI)
Pec	Certified mail

SHIPPING INFORMATION (DELIVERY)

Field	Description
Code	Numeric code that identifies the customer
Name	Name
Surname	Surname
Company	Company
Address	Street Address
Postcode	Postcode
City	City of residence
Province	District
CountryCode	ISO 3166-1 Alpha-2 country code (e.g. IT)
Phone	Phone number
MobPhone	Mobile number
Email	E-mail. In some cases it contains a non-real email address (for example Amazon assigns a temporary relay address)

PAYMENT INFORMATION

Field	Description
PaymentName	Mayment method name
PaymentCode	Payment method code
PaymentTotal	Collection cost including VAT (for example for cash on delivery there is an additional cost charged to the customer)
PaymentStatus	Payment status
PaidTime	Date and time of payment
PaymentCOD	It can be: YES or NO. Indicates if the payment method is cash on delivery.

ORDER LINES (ROWS)

Each order line is contained in an tag

Field	Description
bindID	Internal bindCommerce identifier for the order line
Code	SKU code of the product
Barcode	Bar code extracted from the product master data connected to the SKU sold
Description of the order line as it appears on the sales channel. For example, for eBay orders the title of the advertisement is returned.	Bar code extracted from the product master data connected to the SKU sold
Qty	Quantity purchased (number)
ProductDimensions	Tag that groups the tags Weight (Weight), WeightUom (weight measurement unit), WeightVolume (volumetric weight), LwhUom (linear measurement unit), Length (length), Width (base), Height (height). This information, if any, is extracted from the products database.
ProductCategories	Category - KeyCat of the category (s) combined with the product purchased
Picture	URL immagine prodotto (eventualmente estratta dall’anagrafica articoli)
Supplier	Name or code of the supplier (possibly extracted from the article master)
SupplierPrice	Cost price to be paid to the supplier (to indicate the price list to be used, enter the "SupplierPrice" key in the "Price list export file key" field)
PriceVatExcluded	Unit price excluding VAT (ref. product_item_price)
Price	Unit price including VAT (ref. product_final_price)
SupplierByRepricing	Name of the supplier in the event that the sale price has been imposed through the repricing algorithm
SupplierByRepricingCost	The cost of the product related to the supplier (SupplierByRepricing) obtained through the repricing algorithm
Discount	Discount percentage (ref. product_discount_percent)
VatRate	VAT rate (e.g. 0.22 to indicate 22%). See note (***)
TotalVatExcluded	Total price excluding VAT (ref. product_item_price_total)
Total	Total price including VAT (ref. product_final_price_total)
TotalDiscounted	Total price including VAT (ref. product_final_price_total)
Currency	ISO 4217 currency (e.g. EUR, CHF, GBP, USD). bindCommerce is able to manage a currency conversion so that all amounts are expressed in Euros.

ORDER LINES: CASH FLOW (CASHFLOWROWS)

Field	Description
SettlementId	Settlement Id
Currency	Currency
TransactionType	TransactionType
OrderId	OrderId
MerchantOrderId	Merchant Order Id
AdjustmentId	Adjustment Id
ShipmentId	Shipment Id
MarketplaceName	Marketplace Name

ORDER LINES: COMMISSIONS

Field	Description
Commission	eBayCommission (eBay commission on order line)

AMOUNTS

Field	Description
TotalWithoutTax	Cost of goods excluding VAT excluding VAT (ref. order_subtotal)
VatAmount	VAT amount (ref. order_tax)
Total	Total order (ref. order_total)
Currency	ISO 4217 currency (e.g. EUR, CHF, GBP, USD).
ShippingCost	Shipping cost including VAT (ref. order_shipping_total)
InternalComment	Notes entered by the customer during the purchase phase (ref. customer_note)
SellerNote	Notes entered by the seller (ref. seller_note)
CouponDiscount	Coupon discount (ref. coupon_discount)
CouponCode	Coupon Code
ShippingCostWithoutTax	Amount of shipping costs excluding taxes
ShippingTax	VAT rate applied to the shipment
DiscountToCart	Cart discount (ref. discount_to_cart)

COMMISSIONS

Field	Description
PayPalCommission	PayPal fee amount (available only for eBay orders)
PayPalTransactionID	PayPal transaction ID
eBayCommission	eBay fee amount
eBayAccount	Account eBay
eBayAdjustmentAmount	eBay order cost adjustment
eBayAmountSaved	eBay order cost adjustment

SHIPPING INFORMATION

Field	Description
Carrier	Carrier
TrackingNumber	Tracking Number
TransportedWeight	Weight
ShippedTime	Shipping date and time
ShippingMethod	Shipping Method

Notes relating to the VAT rate

bindCommerce imports orders from various sources: eCommerce platforms and marketplaces (such as eBay, Amazon, ePrice, Spartoo, Wish), and each of the sources transmits a different detail regarding the application of VAT. Usually, marketplaces do not adapt the price based on the type of buyer (private individual / company) and its origin (Italy / Europe / rest of the world). If a buyer buys a certain asset for € 100.00, the determination of how much value is attributable to taxable and how much VAT is an activity that can be performed only after the purchase (and a possible VAT exemption will actually translate in a sale at a higher price). Also on both eBay and Amazon, the request for an invoice is made with manual methods (messages) concurrently or immediately after the purchase (on Amazon always after), therefore it is not possible to make price adjustments before payment.
Furthermore, observing the data relating to the rates transmitted by the main marketplaces, we note that: eBay (all markets) always transmits the rate that was set when the advertisement was created (even when it should not be applied), while Amazon (all markets, if business options are not activated) does not transmit any VAT rate (unlike eBay which transmits it potentially wrong).
With these premises, 2 alternative approaches are possible:

transmit the definitely correct data (who the buyer is, what he purchased and what he paid) and the rate coming from the marketplace (which may not be correct) and then let ERP to recalculate the correct rates to be applied and any exemption codes.
use a Premium bindCommerce function that is able to recalculate the rates to be applied to sales, for shipping costs and for the goods, according to a "VAT rate group" parameter (product attribute to be imported previously) and the destination of the goods

Order status

The values that bindCommerce transmits in the StateName field represent the order status used by the platform from which the order originates. The StateCode field is used only on some platforms and the StateName field can be considered unique within a certain technology. A presentation of the possible order status for the most common platforms follows.

ORDER STATUS FOR EBAY MARKETPLACE

StateName	Note
Active	Purchase not yet completed/confirmed
Cancelled	Cancelled
CancelPending	Being canceled
Completed	Purchase completed
Refunded	Totally refunded
Shipped	Shipped

ORDER STATUS FOR WISH MARKETPLACE

StateName	Note
APPROVED	Purchase confirmed (paid to Wish)
REFUNDED	Refunded
SHIPPED	Shipped

ORDER STATUS FOR AMAZON MARKETPLACE

StateName	Note
Pending	Purchase not yet completed/confirmed
Cancelled	Cancelled
Unshipped	Confirmed (paid to Amazon) but not yet shipped
Shipped	Shipped

ORDER STATUS FOR EPRICE MARKETPLACE

StateName	Note
RECEIVED	Received by ePrice
SHIPPED	Shipped
SHIPPING	In shipping
WAITING_ACCEPTANCE	Awaiting acceptance by the seller

ORDER STATUS FOR ALLEGRO MARKETLACE

StateName	Note
BOUGHT	purchase without checkout form filled in
FILLED_IN	checkout form filled in but payment is not completed yet so data could still change.
READY_FOR_PROCESSING	payment completed. Purchase is ready for processing.
CANCELLED	purchase cancelled by buyer.

ORDER STATUS FOR CDISCOUNT MARKETLACE

StateName	Note
CancelledByCustomer
WaitingForSellerAcceptation
AcceptedBySeller
PaymentInProgress
WaitingForShipmentAcceptation
Shipped
RefusedBySeller
AutomaticCancellation	ex: no answer from the seller
PaymentRefused

StateName	Note
ShipmentRefusedBySeller
Waiting for Fianet validation “A valider Fianet” (None)
Validated Fianet
RefusedNoShipment
AvailableOnStore
NonPickedUpByCustomer
PickedUp
Filled

ORDER STATUS FOR MAGENTO ECOMMERCE PLATFORM

note that these states can be changed by the site operator

StateName	Note
canceled
closed
complete
completed
failed
holded
on-hold
paid
paypal_canceled_reversal
paypal_reversed
pending
processing
refunded

ORDER STATUS FOR PRESTASHOP ECOMMERCE PLATFORM