Order data overview - WEBSALE Dokumentation

This overview shows which parameters a standard order generates and passes to the connected ERP system. You can see the same data in the online service area in the “Orders” service under “Details”, and there under “Download order data”. The order data is organized into sections. Three of them are always present; the others are only created if the buyer used the corresponding function.

Section	Content	Always present
`ID`	header data of the order	yes
`CustomerAddress`	billing address	yes
`DeliveryAddress`	different delivery address	no
`CustomerComment`	customer’s comment	no
`OrderSpecialInput`	additional free text from the customer	no
`Order`	global data of the order	yes
`OrderList` with `Item`	the ordered products	yes

Which parameters are actually generated depends on the feature set of your shop. This page shows the standard case.You can find the complete technical documentation of the order data at doku.websale.de/schnittstellen.

Additional parameters with `_DName` and `_DValue`

For some parameters, WEBSALE V8s outputs two additional parameters with the same name and a suffix:

Suffix	Content
`_DName`	the name of the input field displayed in the shop, depending on the language of the subshop
`_DValue`	the value displayed in the shop

These two serve as additional information. The parameter without a suffix contains the technical value; the parameter with _DValue contains what the buyer saw. For Deliverer, for example, the main parameter contains the internal identifier of the delivery service, and Deliverer_DValue contains its display name.

To display an order, WEBSALE itself uses the _DValue version, for example for Deliverer, DeliveryCost, VAT, and Total. If you prepare order data for people to read, this is usually the better choice.

`ID` section

Header data of an order.

Parameter	Required	Remarks
`ShopID`	yes	unique identifier of your shop
`SubShopID`	yes	unique identifier of the subshop. Every shop has at least one
`Referer`		call reference indicating where WEBSALE was called from
`Subreferer`		sub-call reference
`OrderNumber`	yes	unique order number, suitable for referencing
`Date`	yes	date of the order in the format `TT.MM.JJ`, for example `29.01.10`
`Time`	yes	time in the format `HH:MM:SS`, for example `19:02:59`
`SessionID`	yes	the unique session identifier used in the shop
`ExpressCheckout`		the order was placed via Express Checkout
`ExpressCheckoutType`		via which service, for example PayPal or Klarna

`CustomerAddress` section

The billing address. The section is always present, but all parameters in it are optional.

Parameter	Remarks
`Number`	customer number
`Salutation`	language-dependent salutation, for example “Frau”
`CompleteSalutation`	complete country-dependent salutation, for example “Sehr geehrter Herr Dr. Meier”
`Company`	company name
`Department`	department
`Title`	language-dependent title, for example “Professor”
`FirstName`	first name
`LastName`	last name
`Street1`	street and house number
`Street2`	separate house number, if not included in `Street1`
`ZIP`	postal code
`City`	city
`State`	state
`Country`	three-letter country code according to ISO 3166, for example `DEU`
`Phone`	phone
`BusinessPhone`	business phone
`MobilePhone`	mobile phone
`Fax`	fax
`BusinessFax`	business fax
`E-Mail`	email address
`E-Mail2`	second email address, for example for sending invoices
`DateOfBirth`	date of birth in the format `TT.MM.JJJJ`
`IP-Address`	IP address from which the shop was accessed
`IP-AddressTimestamp`	time the IP was determined, in the format `JJJJ-MM-TT / HH:MM:SS`
`PostOfficeBox`	post office box
`SuperUserID`	set if the order was placed by a SuperUser on behalf of another customer
`TaxID`	VAT identification number
`UserDef-1` to `UserDef-3`	freely definable fields that are not stored in the customer database
`Suffix1` to `Suffix50`	freely definable fields that are stored in the customer database
`BonusPointsAccountBalance`	only with the bonus points system. The points balance
`PaymentAccountCredit`	only with the customer account payment method. The account balance
`ExpressCheckoutAddressUsed`	`yes` if the address comes from Express Checkout

The fields UserDefList-1 to UserDefList-3 may appear in the order data of older shops. Custom UserDefList selection lists are deprecated and no longer supported.

Guide: Selection lists for address data

`DeliveryAddress` section

The different delivery address. This section is only created if the buyer entered one. The parameters correspond to those of the billing address, with three differences: there is no Number, no E-Mail2, and none of the customer-account-related details such as TaxID or SuperUserID. In return, one parameter is added:

Parameter	Remarks
`OneTime`	only with multiple delivery addresses. If this is `yes`, the address was not stored in the customer database and the ERP system must not replicate it back into the shop

OneTime is the parameter where incorrect handling is most costly. If your ERP system replicates a one-time address back, it ends up permanently in the customer account, even though the buyer entered it only for this one order.

With multiple delivery addresses, a parent DeliveryAddresses section groups the individual DeliveryAddress sections. This wrapper is not described in the previous documentation and has been added here.

`CustomerComment` section

An optional comment from the customer. The section contains no parameters, just the text as the buyer entered it, with any number of line breaks.

<CustomerComment>
   Text des Bestellers, wie
   von ihm eingegeben.
   Mit beliebigen Zeilenwechseln.
</CustomerComment>

`OrderSpecialInput` section

Another multi-line free text that the customer can optionally enter. Structured like CustomerComment.

<OrderSpecialInput>
   Beliebige Eingaben des Bestellers.
   Beliebige Eingaben des Bestellers.
   Beliebige Eingaben des Bestellers.
</OrderSpecialInput>

`Order` section

Global data of the order.

Shipping and general data

Parameter	Required	Remarks
`Deliverer`		name of the delivery service, freely assigned in the shop
`DeliveryDate`		preferred delivery date in the format `TT.MM.JJJJ`
`TotalWeight`		total weight of the order
`WeightUnit`		unit for the weight, for example `kg`
`TotalVolume`		total volume
`VolumeUnit`		unit for the volume
`PriceType`	yes	`Gross` for gross prices, `Net` for net prices
`Currency`	yes	three-letter currency code, for example `EUR`
`TaxFree`	yes	`yes` if the customer is exempt from VAT, otherwise `no`

Payment

Parameter	Remarks
`PaymentType`	technical name of the payment method, for example `CreditCard`, `CashOnDelivery`, `DebitNote`, `Bill`, `Prepayment`
`PaymentName`	language-dependent name, for example “Nachnahme”
`PaymentCode`	the payment method code
`CostCenterNumber`	cost center number, only with the cost center payment method
`CostCenterEmailAddress`	email address of the approver, only with the cost center payment method

Materials: Payment method codes

Vouchers and bonus points

Parameter	Remarks
`VoucherNumber`	number of the redeemed voucher
`VoucherRest`	remaining balance of the voucher
`VoucherChargeID`	batch ID of the voucher
`VoucherAmount`	amount actually redeemed. With a voucher worth 100 euros and an invoice amount of 25 euros, this contains `25.00`
`OrderBonusPoints`	number of bonus points credited
`CashedBonusPoints`	number of bonus points redeemed
`CashedBonusPointsAmount`	amount of the redeemed bonus points

Discounts

Parameter	Required	Remarks
`UserDiscountRate`	yes	customer discount in percent
`UserDiscount`	yes	value of the customer discount
`PaymentDiscountRate`	yes	payment method discount in percent
`PaymentDiscount`	yes	value of the payment method discount
`OrderDiscountRate`	yes	order value discount in percent
`OrderDiscount`	yes	value of the order value discount
`GroupDiscount`	yes	value of the product group discount
`ProductDiscount`	yes	value of the direct product discount
`PaymentCostDiscountRate`		payment cost discount in percent
`PaymentCostDiscount`		value of the payment cost discount
`DeliveryCostDiscountRate`		shipping cost discount in percent
`DeliveryCostDiscount`		value of the shipping cost discount
`TotalDiscount`	yes	value of all cumulative discounts

Costs and totals

Parameter	Required	Remarks
`DeliveryCost`	yes	delivery costs
`DeliveryVATRate`	yes	VAT rate of the delivery costs
`PaymentCost`	yes	payment costs
`Surcharge`		small-quantity surcharge
`ResellerSurcharge`		reseller surcharge
`GiftPackage`		total cost of all gift wrapping
`GiftPackageVATRate`		VAT rate of the gift wrapping
`CustomerSubvention`		customer subsidy granted
`CustomerSubventionRemainder`		remaining customer subsidy for the next order
`SubTotal`	yes	merchandise value
`VAT`	yes	total VAT amount
`Total`	yes	grand total including all discounts, vouchers, surcharges, and deductions

Further details

Parameter	Remarks
`OrderOption_Name-1` to `-5`	name of the order option
`OrderOption_Price-1` to `-5`	cost of the order option
`OrderOption_VAT-1` to `-5`	VAT rate of the order option
`TS_Name`	name of the Trusted Shops product
`TS_VAT`	VAT rate of the Trusted Shops product
`TS_COST`	cost of the Trusted Shops product
`UploadID`	unique upload identifier of the order, for file uploads
`DownloadID`	unique download identifier, for file downloads
`OfferID`	unique identifier when ordering a quote
`RefText` and `RefText2`	reference texts for the order

`OrderList` section with `Item`

The list of ordered products. One Item section is created per product.

<OrderList>
   <Item>
      Daten des 1. Produktes
   </Item>
   <Item>
      Daten des 2. Produktes
   </Item>
   ...
</OrderList>

Identification

Parameter	Required	Remarks
`ID`		unique product number, depending on the selected variants
`PositionNumber`		sequential line item number
`ProdIndex`	yes	internal index of the product, independent of variants
`DepVarIndex`		index of the dependent variant
`Insert`		promotional code
`SetParentID`		identifier of a set parent product
`SetChildID`		identifier of a set child product
`MerchantID`		merchant identifier
`MerchantName`		merchant name
`EmployeeID`		employee identifier
`ExternalProductID`		identifier of an external product unknown to the shop
`Name`	yes	product name

Quantity, weight, and dimensions

Parameter	Required	Remarks
`Quantity`	yes	order quantity
`UnitFactor`		packaging unit factor
`Weight`		weight per piece
`TotalWeight`		total weight, that is `Quantity` times `Weight`
`Volume`		volume
`TotalVolume`		total volume
`AreaProductLength`		length or height of an area product
`AreaProductWidth`		width or thickness of an area product
`AreaProductCalculatedArea`		calculated area in the unit configured in the shop

For an area product with a length of 50 centimeters and a width of 150 centimeters, AreaProductCalculatedArea contains 0.75, for example, if the area is measured in square meters. You set the number of decimal places for length and width in the shop.

Prices and discounts per line item

Parameter	Required	Remarks
`Price`	yes	base price without discounts, variants, and tiered prices. For information only
`StaticAddPrice`		quantity-independent one-time price, for example for a print template
`GiftPackage`		price of the gift wrapping
`TotalGiftPackage`		total price of the gift wrapping
`VAT`	yes	absolute VAT amount
`Sum`	yes	subtotal. For information only
`DiscountFactor`		discount factor
`ProductDiscount`	yes	absolute direct product discount
`UserDiscount`		calculated customer discount for this product
`ParticularOrderDiscount`		share of this line item in the globally shown order value discount
`ParticularUserDiscount`		share of this line item in the globally shown customer discount
`ParticularPaymentDiscount`		share of this line item in the globally shown payment method discount
`TotalDiscount`	yes	total discount of the line item
`Total`	yes	final total price including all discounts, tiered prices, additional costs, and the order quantity

Price and Sum are explicitly marked as information. For posting, Total is the relevant value, because only it includes all discounts, surcharges, and the quantity.

Subsections per line item

Section	Content
`<Variation>`	a selected variant. Can occur multiple times per line item
`<TextInputFields>`	the text input fields of the line item, maximum ten
`<OrderInfo>`	internal information about the product, which is returned unchanged
`<InstantVoucherProduct>`	details of a gift voucher

Within <Variation>:

Parameter	Remarks
`ID`	partial product number for normal variants
`Name`	name of the variant, for example “Farbe”
`Option`	selected option, for example “rot”
`Price`	surcharge for normal variants
`Index`	internal index of the sort position

Within <TextInputFields>:

Parameter	Remarks
`Name-1` to `Name-10`	name of the text input field
`Field-1` to `Field-10`	value of the text input field

Within <InstantVoucherProduct>:

Parameter	Remarks
`ChargeID`	batch ID of the gift voucher
`Number`	voucher number
`Amount`	amount
`PDFLinkPart`	link for downloading the gift voucher as a PDF

Special product types

Parameter	Remarks
`BonusProduct`	`yes` identifies a reward product
`BonusProductPrice`	number of bonus points redeemed for it
`BonusProductPriceTotal`	total number of bonus points redeemed
`InstantVoucherProduct`	`yes` identifies a gift voucher
`UploadID`	upload identifier of this line item

​Additional parameters with _DName and _DValue

​ID section

​CustomerAddress section

​DeliveryAddress section

​CustomerComment section

​OrderSpecialInput section

​Order section

​Shipping and general data

​Payment

​Vouchers and bonus points

​Discounts

​Costs and totals

​Further details

​OrderList section with Item

​Identification

​Quantity, weight, and dimensions

​Prices and discounts per line item

​Subsections per line item

​Special product types

Additional parameters with `_DName` and `_DValue`

`ID` section

`CustomerAddress` section

`DeliveryAddress` section

`CustomerComment` section

`OrderSpecialInput` section

`Order` section

Shipping and general data

Payment

Vouchers and bonus points

Discounts

Costs and totals

Further details

`OrderList` section with `Item`

Identification

Quantity, weight, and dimensions

Prices and discounts per line item

Subsections per line item

Special product types