Use this reference to process customer orders created in YBM Connect. Each export contains the customer and delivery details followed by the ordered products, so your system can validate and process the order. YBM Connect creates the file and places it on your SFTP server after an order is submitted.

Processing workflow

1. Receive the exported file from the configured SFTP destination.
2. Wait until the file is completely available before reading it.
3. Parse the order header and its single data row.
4. Use the separator row to identify the start of the product section.
5. Process one product row for each ordered product.
6. Use Vessel count together with the bundle fields when quantities are delivered in bundles.

Use a standards-compliant CSV parser. Do not split the file by newline alone: quoted values, including the delivery message, may contain commas and line breaks.

Sections

Our CSV order file format consists of two sections:

1. Customer order information
2. Ordered products

Both sections have the same number of columns, so that the file can always be opened manually for human inspection. The two sections are separated by a line consisting only by column separators.

The default export contains 14 columns in each section. This is export version 0. YourBarMate can also configure export version 1. The exact version is agreed during the SFTP setup. Always process the header that is included in the file rather than relying only on a fixed column count.

Make sure to split the file and process the order information separate from the product information.

YourBarMate generates this file after a customer submits an order and uploads it to the SFTP destination configured for your account. The file is an outbound order notification; do not upload it back to YourBarMate as a catalog or price file.

File format

• Encoding: utf-8 or latin1 (ISO 8859-1)
• Newline: \n
• Delimiter: , (comma)
• Quoting: Cells with special characters like , and \n are quoted with "
• Escapes: The " sign is escaped as a double "" and the cell is quoted

Example: abc " def will become "abc "" def"

The user supplied message on the delivery in the first section is likely to contain newlines, while the message on the ordered products is a single line string.

If the file encoding is utf-8 (the default setting), the file contains a byte order mark.

The downloadable example shows the complete two-section structure, including the headers, separator and sample ordered products.

Row types

Each of the two sections has a header row. The first section has exactly one data row and the second section has one data row per ordered product.

1. Order header row
2. Order data row
3. separator
4. Products header row
5. Product data row 1
6. Product data row 2
7. Product data row 3

Order header and data row columns

1. Delivery ID: The order identifier
2. Type: One of "DELIVERY" or "RETURN". A return uses the same file structure as a delivery.
3. Customer ID: The customer ID
4. Company: The requesting company name
5. Cost Center: The cost center
6. Address: The delivery address
7. Zip: The ZIP code
8. City: The city name
9. Country: The ISO country code
10. User name: The name of the user who sent the order
11. User email: The email address of the user who sent the order
12. Scheduled date: The desired schedule date in the format YYYY-MM-DD
13. Scheduled time: The optional desired schedule time in the format HH:mm
14. Message: An optional message for the delivery provided by the user

In export version 1, the order section has the following 14 columns:

1. Delivery ID
2. Type
3. Customer ID
4. Company
5. Address
6. Zip
7. City
8. Country
9. User name
10. User email
11. Scheduled date: The desired schedule date in the format YYYY-MM-DD
12. Delivery from: The start of the configured delivery window
13. Delivery until: The end of the configured delivery window
14. Message: An optional message for the delivery provided by the user

Compared with export version 0, Cost Center is removed. The product section remains unchanged.

Product header and data row columns

YBM Connect generates these order-file headers. Keep their exact names when processing the export, including Item ID, Item name and Item count.

1. Delivery ID: The order identifier – this is the same as the Delivery ID in the header and is repeated on each product row
2. Item ID: The product identifier
3. Item name: The product name
4. Vessel size: The size of the product vessel in the specified unit
5. Vessel unit: One of "l", "dl", "cl", "ml", "kg", "g" or "quantity"
6. Order by: One of "vessel" or "kg"
7. Item count: The count of bundles, vessels or kilos ordered. It is a whole number for vessel-based products. For products ordered by weight, it may be a fractional kilogram value.
8. Bundle ID: The bundle identifier, if available
9. Bundle type: See vessel and bundle types
10. Bundle size: The number of vessels in the bundle
11. Vessel count: The total count of vessels (Item count * Bundle size)
12. Price: The expected unit price, e.g. 1234.56
13. Price per: One of "vessel", "l", "kg" or "100g"
14. Message: An optional message for the product provided by the user

For example, an order for two cartons containing six bottles each has Item count = 2, Bundle size = 6 and Vessel count = 12. If no bundle is used, Item count is the number of individual vessels and Vessel count is the same quantity.

For a return, use the Type value from the file to identify the transaction. Do not infer a return from a negative quantity: quantities are exported using the normal count fields.

File names

The SFTP setup defines the destination path and file name pattern. The pattern may contain these placeholders:

• ${type}: delivery or return
• ${id}: the order ID
• ${date}: the creation date in YYYY-MM-DD format
• ${time}: the creation time in HHmmss format

Use the generated file name and Delivery ID to identify an order. The file is an export from YBM Connect and does not require a response file.