Skip to content
Developer

Vouchers

You take over existing vouchers with their initial value and remaining open amount from your previous system.

Format
CSV (comma or semicolon), UTF-8
Access rights
Administrator, write access to billing
Example file
Gutscheine_beispiel_technisch.csv (download)

In short: Each row is a voucher with its initial value and the remaining open amount. vynst updates existing vouchers and creates new ones. The codes that customers already have remain valid.

What you need this for

Vouchers from your previous system should continue to work in vynst without you having to issue them again. The open amount shows what can still be redeemed.

Before you start

  • Rights: Administrator with write access for billing.
  • Check settings: The settings Vouchers - number prefix (Gutscheine - Nummernpräfix) (default GS-) and Vouchers - VAT rate (Gutscheine - MwSt.-Satz) (default 0) apply to newly created vouchers. Change them beforehand if necessary.
  • Backup: Take an export before the import (Settings → Export (Einstellungen → Export)).

Prepare the file

  • File name: The name must contain .csv, for example Gutscheine_2024.csv.
  • Header row: The first three columns come at the start in this order: VOUCHER_IDENTIFIER, VOUCHER_AMOUNT, VOUCHER_AMOUNT_OPEN. Further columns after them are allowed.
  • Separator: Comma or semicolon. If the header row is enclosed in quotation marks, the separator must be a comma.
  • Amounts: 100.00 or 1.234,56. If the amount contains a comma, vynst reads it in German notation.
  • Date: 2024-02-14 or 14.02.2024.
  • Character set: UTF-8.

Columns

Column Required Content Example
VOUCHER_IDENTIFIER yes Identifier of the voucher. Ideally the voucher code the customer has. Also possible: voucher number, token or internal ID. ABCD2345
VOUCHER_AMOUNT yes Initial value of the voucher. 100,00
VOUCHER_AMOUNT_OPEN no Remaining open amount. Must be between 0 and the initial value. If the field is empty, the full amount counts as open. 40,00
VOUCHER_SHORT_ID no Voucher code, if it differs from the identifier. Only for new vouchers. ABCD2345
VOUCHER_NUMBER_STRING no Voucher number. If the field is empty, vynst assigns the next number with prefix and year. GS-2024-00012
VOUCHER_STATUS no open or offen, paid or bezahlt, canceled or storniert. New vouchers without a value count as paid. paid
VOUCHER_CURRENCY no Currency. Default is EUR. EUR
VOUCHER_PURCHASE_DATE no Purchase date. It determines the year in the voucher number. 14.02.2024
VOUCHER_FREE_TEXT no Free text that appears on the voucher. Geburtstagsgeschenk
VOUCHER_ARCHIVED no ja or nein. nein
CUSTOMER_NAME no Name of the buyer. Erika Mustermann
CUSTOMER_EMAIL no Email of the buyer. erika@example.org
CUSTOMER_ADDRESS_STREET, CUSTOMER_ADDRESS_ZIP, CUSTOMER_ADDRESS_CITY, CUSTOMER_ADDRESS_COUNTRY no Address of the buyer. Hauptstraße 1, 30159, Musterstadt
COMPANY_IDENTIFIER no Linked account via its account number in vynst. K-1001
PERSON_IDENTIFIER no Linked person via their identifier from the persons import. AFS_CSV_1003

Example

VOUCHER_IDENTIFIER;VOUCHER_AMOUNT;VOUCHER_AMOUNT_OPEN;CUSTOMER_NAME;VOUCHER_PURCHASE_DATE;VOUCHER_STATUS;VOUCHER_SHORT_ID;VOUCHER_NUMBER_STRING;VOUCHER_CURRENCY;VOUCHER_FREE_TEXT;VOUCHER_ARCHIVED;CUSTOMER_EMAIL;CUSTOMER_ADDRESS_STREET;CUSTOMER_ADDRESS_ZIP;CUSTOMER_ADDRESS_CITY;CUSTOMER_ADDRESS_COUNTRY;COMPANY_IDENTIFIER;PERSON_IDENTIFIER
ABCD2345;100,00;40,00;Anna Beispiel;14.02.2024;paid;;;EUR;Geburtstagsgeschenk;nein;anna.beispiel@example.org;Gartenweg 4;50668;Köln;Deutschland;;AFS_CSV_1003
EFGH6789;50,00;50,00;Max Mustermann;01.03.2024;open;;;EUR;;nein;max.mustermann@example.org;Feldweg 7;50669;Köln;Deutschland;;AFS_CSV_1004
GS-2024-00099;25,00;25,00;Erika Mustermann;01.12.2024;open;KAR7351;GS-2024-00099;EUR;Weihnachtsgeschenk;ja;erika@example.org;Hauptstraße 1;30159;Musterstadt;Deutschland;K-1003;

Example file: Gutscheine_beispiel_technisch.csv with all columns. The rows also show the voucher number and short code, the currency, the customer address and the link to account and person.

How to proceed

  1. Create the file following the pattern above.
  2. Settings → Import → Add (Einstellungen → Import → Hinzufügen), select the file.
  3. Check in the log how many vouchers were created and updated.
  4. For new vouchers, spot-check the numbers and codes.

Good to know

  • A repeated import updates vouchers that are found via their identifier. Using a voucher code therefore does not create duplicates.
  • The open amount from this file applies. Bookings, i.e. redemptions, can be added via the import “Voucher bookings” (Gutschein-Buchungen). By default, the open amount remains unchanged in the process.
  • If a customer column is in the file but the field is empty, the previous value is deleted. This also applies to existing vouchers.
  • If COMPANY_IDENTIFIER or PERSON_IDENTIFIER is set in the file but empty or unknown, the link is removed.
  • A pure number as identifier is risky. vynst also searches for it among the internal numbers. If it hits a different voucher, that voucher is changed. In addition, the next import cannot reliably find a voucher with a pure number. Therefore, use the voucher code.
  • For existing vouchers, VOUCHER_SHORT_ID is not taken over. The code remains unchanged.

When something does not work

Message in the log Meaning What to do
Error: skipped <Kennung> - VOUCHER_AMOUNT is missing or not a number The initial value is missing or is not a number. Correct the amount in the row.
Error: skipped <Kennung> - VOUCHER_AMOUNT_OPEN must be between 0 and VOUCHER_AMOUNT The open amount is negative or greater than the initial value. Check the amounts.
Error: skipped <Kennung> - voucher code <Code> is already used by another voucher The code already belongs to another voucher. An issued code is never silently replaced. Choose another code or check the existing voucher.
Error: skipped row without VOUCHER_IDENTIFIER A row has no identifier. The row appears below as LINE-DATA. Add the identifier.
Warning: <Kennung> - unknown VOUCHER_STATUS "<Wert>", using paid The status is unknown, the voucher was created as paid. Check the status.
Warning: <Kennung> - could not read VOUCHER_PURCHASE_DATE, keeping <Datum> The purchase date could not be read. Write the date in the format 14.02.2024.
Warning: <Kennung> - company <Nummer> not found The account is not known in vynst. The voucher is created without a link. Check the account number.
Warning: <Kennung> - person <Nummer> not found The person is not known in vynst. Check the person number.
Error: less then one line The file contains no data row. Check the file.

See also