General

This documentation describes the format and content of voucher data that can be sent to the shop.

Transfer of import files

The import files described below can be transferred in 3 ways:

Transfer via SFTP-REST

Step 1: Transferring the import files via SFTP
Step 2: Starting the import of the data via REST trigger

Since the trigger procedure is used in a similar way for different interfaces, it is described in the separate documentation "SFTP-REST-to-Shop (EN)":

SFTP-REST-to-Shop (EN)

Use voucherupdate.csv or voucherdelete.csv file names for this procedure.

Transfer via SFTP-SOAP

Step 1: Transferring the import files using SFTP
Step 2: Starting the import of the data using SOAP triggers

Since the trigger procedure is used in a similar way for different interfaces, it is described in the separate documentation "SFTP-SOAP-to-Shop (EN)":

SFTP-SOAP-to-Shop (EN)

Use the file names voucherupdate.csv or voucherdelete.csv for this procedure.

Alternative transfer via WSPManager (previous version)

Import data can also be transferred and imported to the shop server using the Windows tool "WSPManager" provided by WEBSALE. This method should be used if, for example, no SFTP transfer or no REST/SOAP trigger can be implemented on the merchant's system.

The transfer via WSPManager is described in the separate documentation "WSPManager-to-Shop (EN)":

WSPManager-to-Shop (previous version) (EN)

Use the file names voucherupdate.dat or voucherdelete.dat for this procedure, these files must be placed in the "data-exchange" directory.

Names and format of the import files

Structure of the file voucherupdate.dat/voucherupdate.csv

The file is used to create new vouchers or modify existing vouchers. It contains the following fields:

Name	Meaning	Required field

Name	Meaning	Required field
Number	The (unique) voucher number. The length of the number must not exceed 200 characters. In principle, the "number" may contain any characters. However, umlauts and similar "special characters" (i.e. characters that are not part of the ASCII code) should be avoided, as they will prevent the associated vouchers from being redeemed in the shop if the character set encoding in the shop differs from the encoding of the voucher data.	Yes
ChargeId	The batch ID of the vouchers. This value is required to edit or display the voucher data in the service area.	Yes
ChargeDescr	Description of the batch as it is displayed in the OSB	No
ChargeLabel	"Label" of the voucher, which is transferred in the order data and can be used for evaluations by downstream systems. Multiple "labels" can be specified as a comma-separated list.	No
Currency	The currency of the voucher	Yes
Type	The type of vouchers. The following types are supported: 0: Remaining amount can be reused 1: Remaining amount expires 2: Universal voucher 3: Universal voucher (customer-specific, i.e. each customer can only use the voucher once) 4: Universal voucher (only for new customers) 5: Remaining amount can be reused (only for new customers) 6: Remaining amount expires (only for new customers) 7: Individual multiple voucher (universal voucher with automatic customer binding, i.e. as soon as a customer uses the voucher, the voucher is automatically reused). i.e. as soon as a customer has redeemed the voucher, only this customer can redeem it, but as often as desired)	Yes
Type2	Promotional voucher/purchase voucher 1: Advertising voucher 2: Purchase voucher	Yes
Amount	Amount or percentage of the voucher	Yes
AmountType	0: Amount contains an absolute amount (default) 1: Amount contains a percentage 2: Amount contains a percentage and capped value. This type can be used only for set sub-items. The product numbers or indexes of these set sub-items must be supplied in the CatProdFilter field. Total amount of the item will be capped (regardless of the quantity) to the amount specified in the Amount/AmountMultiCurrency field. Vouchers with this type cannot have a "normal" maximum amount specified.	No
AmountMultiCurrency	This field is used instead of Amount for MultiCurrency vouchers. For a MultiCurrency voucher, the amount of the voucher is specified in multiple currencies. Format: `<g><c>ISO code of the currency</c><a>amount</a></g>`... Example: `<g><c>EUR</c><a>10.00</a></g>` `<g><c>GBP</c><a>8.00</a></g>`	Yes (only for vouchers with multiple currencies)
UsedAmount	The amount of the voucher already redeemed	No
UsedAmountMultiCurrency	This field is used instead of UsedAmount for MultiCurrency vouchers. Format: `<g><c>ISO code of the currency</c><a>amount</a></g>...`	No
State	The state of the voucher, the following two values are possible: 1: Active 0: Not active This field is optional, default: a voucher is active.	No
MinOrderValue	Minimum order value, from which the voucher can be redeemed	No
MinOrderValueMultiCurrency	This field is used instead of MinOrderValue for MultiCurrency vouchers. Format: `<g><c>ISO code of the currency</c><a>amount</a></g>`...	No
ValidFrom	Date from which the voucher is valid, in the format "YYYYMMDD".	No
ValidUntil	Date until which the voucher is valid, in the format "YYYYMMDD".	No
MaxUseCount	Maximum number of times the voucher can be redeemed (only for universal vouchers) If this field is missing or empty, the voucher can be redeemed any number of times.	No
MaxDiscountValue	Only for percentage discount: The maximum value of the voucher that can be redeemed	No
MaxDiscountValueMultiCurrency	This field is used instead of MaxDiscountValue for MultiCurrency vouchers. Format: `<g><c>ISO code of the currency</c><a>amount</a></g>`...	No
Subshop	Subshops for which the coupon should apply. If this field is left blank, the voucher can be redeemed in all subshops. Multiple subshops can be specified in a comma separated list.	No
VATIndex	The VAT code of the voucher. This must be either one of the values configured in the shop.config under "<VATRates>" or one of the special values "-1" or "0". "-1" means "Default", in this case the identifier configured under DeliveryVATRate will be used for the voucher. "0" stands for "No VAT". This field is optional, by default it will be set to "-1"/Standard".	No
VoucherProds	The numbers of the products that should be automatically added to the cart when this voucher is redeemed (comma separated list).	No
Pool	"y": The voucher will be written to the "Voucher Pool" and will not be redeemable in the shop until it has been activated via the SOAP voucher interface. For any other value, or if the field is completely missing, a normal voucher is created that is immediately redeemable. It is not possible to re-import an already activated voucher into the pool.	No
CustomerFilter	Restricting the validity to certain customers. Customers can be identified either by user index (<i></i>) or by customer number (<n></n>). Similarly, the negative tags <!i></!i> and <!n></!n> can be used to specify customers to whom the coupon is not valid. Once this field is filled, a customer must be logged into the shop to use the coupon. Example 1: <i>123</i> (coupon is only valid for the customer with user index 123) Example 2: <n>abc</n><n>xyz</n> (voucher is only valid for the customers with the numbers abc and xyz) Example 3: <!i>456</!i> (coupon is not valid for the customer with user index 456)	No
CatProdFilter	This field can be used to restrict the validity of the voucher to certain products or categories. The restriction can be done by specifying category indexes (<ci></ci>), product indexes (<pi></pi>) or product numbers (<pn></pn>). Per voucher, the field can contain either <pi>- or <pn>- entries, but no combinations of these two tags. Example 1, restricting to categories with indexes "543" and "345": `<ci>543</ci><ci>345</ci>` Example 2, restriction to the products with numbers "abc" and "xyz". `<pn>abc</pn><pn>xyz</pn>`	No
CatProdFilterSetBehavior	0: Product number or index of the parent product determines if the coupon is used for a set item. 1: Product number or index of the child products determines if the voucher is used for a set item.	No
SpecialFeatures	A tag-separated field that contains details for customer-specific special features. Example: `<g><t>AdditionalProductFieldsFilter</t><setbehavior>asUnit\|single</setbehavior><filter><fieldname>tech. Fieldname</fieldname><valueInList>a,b,c,d,e</valueInList></filter></g>`	No

Note:
If the same voucher number occurs more than once in the same import file, the records occurring later in the import file will normally overwrite those occurring earlier.

Optionally (i.e. if this has been enabled for your shop), however, the import can also combine the subshop fields of the voucher records.

In this case, the import will check whether the data of the multiple imported vouchers (with the exception of the "Subshop" field) is the same in all lines.
If this is the case, the subshop entries of all vouchers with the same numbers will be combined.
If there are discrepancies, only the data of the first voucher with that number will be imported and all other occurrences will be ignored.

Example file: Part of this documentation is the example file "voucherupdate.dat", which you can download on the subordinate page.

Structure of the file voucherdelete.dat/voucherdelete.csv

The file is used to delete vouchers. It contains the following fields:

Name	Meaning	Required field

Name	Meaning	Required field
Number	The (unique) voucher number	Yes
Pool	y": The voucher will be deleted from the "voucher pool" (see voucherupdate.dat)	No

Example file: Part of this documentation is the example file "voucherdelete.dat", which you can find on the subordinate page for download.

Dokumentation

Format and content - WS-SFTP-Gutscheindaten (to-Shop) (EN)