Order Import File Definition

Transcription

1 Order Import File Definition Order Import File Definition February 2013 Page 1

2 CONTENTS I. INTRODUCTION TO THE ORDERS IMPORT PROCESS 3 II. SUPPORTED FILE FORMATS 3 1. CSV format 3 a. Supported decimal separators 3 b. Supported date formats 3 c. Supported text qualifiers 4 d. Supported field separators 4 2. XLS(X) format 4 3. XML format 4 a. Supported decimal separators 4 b. Supported date formats 4 III. OBLIGATORY FIELDS 5 1. Import of new transactions 5 a. Sale transactions 5 b. Lead transactions 5 2. Update of existing transactions 5 a. Identification through TransactionId 6 b. Identification through OrderId, RateMode and RateNumber 6 IV. FIELD DEFINITIONS 6 1. TransactionId 6 2. RateMode 6 3. RateNumber 7 4. OrderId 7 5. ProgramId 7 6. PublisherId 7 7. Status 8 8. NetPrice 8 9. CancellationReason RegistrationDate ClickDate SubId 9 Order Import File Definition February 2013 Page 2

3 I. Introduction to the orders import process affilinet offers advertisers various ways to handle their sales and leads. With the file-wise import, advertisers can insert new orders into our platform or update already existing orders. What advertisers call order normally refers to a set of actions, which a customer has performed on the advertiser s system. E.g. if a publisher brokers a new customer to an online shopping platform, and that customer performs his first purchase, subscribes to the newsletter and purchases articles, which shall be remunerated with 2 different sale rates (e.g. one for clothing, one for electronics), 4 different entities could be added to our platform, all assigned to the brokering publisher. These 4 entities are called Transactions within the affilinet platform. So strictly speaking, we are not offering an order import, but rather a transaction import process. II. Supported file formats Order import files can be submitted to us in CSV, XML and XLS format. We recognize the format of the submitted file automatically through the file extension (.csv,.xml,.xls,.xlsx case insensitive). 1. CSV format We accept CSV files up to a size of 2048 kb each. If you need to insert more orders, please submit separate files. The column headers of the obligatory fields must be named as defined in this document, case insensitive. Columns with unknown headers are accepted, but ignored. Each data row must have as many columns as the header row. Column headers must not appear more than once in the header row. The order of the column headers may vary. For the import, please select in the user interface the decimal separator and the date format you are using in your file. Text qualifiers and field separators are recognized automatically. a. Supported decimal separators, (comma). (dot) b. Supported date formats YYYY-MM-DD YYYY.MM.DD YY.MM.DD YYYY/MM/DD YY/MM/DD YYYYMMDD YYMMDD MM-DD-YYYY MM-DD-YY MM/DD/YYYY Order Import File Definition February 2013 Page 3

4 MM/DD/YY DD-MM-YYYY DD-MM-YY DD.MM.YYYY DD.MM.YY DD/MM/YYYY DD/MM/YY c. Supported text qualifiers (double quotes) (single quotes) (none) d. Supported field separators ; (semicolon) (pipe) ^ (caret) \t (tab) 2. XLS(X) format We accept XLS or XLSX files up to a size of 4096 kb each. If you need to insert more orders, please submit separate files. The column headers of the obligatory fields must be named as defined in this document, case insensitive. Columns with unknown headers are accepted, but ignored. 3. XML format We accept XML files up to a size of 8192 kb each. If you need to insert more orders, please submit separate files. The column headers of the obligatory fields must be named as defined in this document, case insensitive. a. Supported decimal separators, (comma). (dot) b. Supported date formats YYYY-MM-DD YYYY.MM.DD YY.MM.DD YYYY/MM/DD YY/MM/DD YYYYMMDD YYMMDD MM-DD-YYYY MM-DD-YY Order Import File Definition February 2013 Page 4

5 MM/DD/YYYY MM/DD/YY DD-MM-YYYY DD-MM-YY DD.MM.YYYY DD.MM.YY DD/MM/YYYY DD/MM/YY III. Obligatory fields 1. Import of new transactions a. Sale transactions At least the following pieces of information must be given: ProgramId OrderId RateMode RateNumber NetPrice PublisherId Status ( Open is obligatory when new) b. Lead transactions At least the following pieces of information must be given: ProgramId OrderId RateMode RateNumber PublisherId Status ( Open is obligatory when new) 2. Update of existing transactions Whenever you want to update a transaction, which is already present in our system, you can access this transaction in 2 different ways: either by specifying the TransactionId, or by specifying the OrderId, RateMode and RateNumber. If all 4 fields are specified, the TransactionId is used and OrderId, RateMode and RateNumber are ignored. The following business rules apply for transactions that are already present in the system: Status Change to open Change to confirm Is open No Yes Yes Is confirmed by AOM* No No No Is manually confirmed No No No Is cancelled by AOM* Yes Yes No Change to cancel Order Import File Definition February 2013 Page 5

6 Is manually cancelled Yes Yes No AOM* = Auto Order Management. Automatic confirmation or cancellation of an order after a predefined time. a. Identification through TransactionId At least the following pieces of information must be given: ProgramId TransactionId Status NetPrice (sales transactions only) b. Identification through OrderId, RateMode and RateNumber At least the following pieces of information must be given: ProgramId OrderId RateMode RateNumber Status NetPrice (sales transactions only) IV. Field definitions 1. TransactionId This is the identifier each transaction gets within our platform. You receive the TransactionId through the order export. If this field is filled, the fields RateMode, RateNumber and OrderId are ignored. If this field is not filled, RateMode, RateNumber and OrderId must be filled. We need either of these in order to unambiguously identify the transaction to which you are referring. Can contain positive integer values between 1 and Thousand separators are not permitted. Must not refer to a transaction which is assigned to a different program. If in XML you submit a data set, where you would like to leave TransactionId unspecified (because you identify the transaction through OrderId, RateMode and RateNumber), then please don t submit a line like this: <TransactionId></TransactionId> because this is interpreted as a TransactionId with the length 0, which is incorrectly formatted. Please instead submit this line as <TransactionId xsi:nil= true /> 2. RateMode The mode of the rate, which is used for the transaction you refer to. Can be either Sale or Lead, case sensitive. Order Import File Definition February 2013 Page 6

7 If in XML you submit a data set, where you would like to leave RateMode unspecified (because you identify the transaction through the TransactionId), then please don t submit a line like this: <RateMode></RateMode> because this is interpreted as a RateMode with the length 0, which is incorrectly formatted. Please instead submit this line as <RateMode xsi:nil= true /> 3. RateNumber The identifier of the rate, which is used for the transaction you refer to. A combination of this RateMode and RateNumber must be defined for your ProgramId. Can contain positive integer values between 1 and Thousand separators are not permitted. If in XML you submit a data set, where you would like to leave RateNumber unspecified (because you identify the transaction through TransactionId), then please don t submit a line like this: <RateNumber></RateNumber> because this is interpreted as a RateNumber with the length 0, which is incorrectly formatted. Please instead submit this line as <RateNumber xsi:nil= true /> 4. OrderId The identifier of the order, which you have defined for this transaction. E.g. the argument of the parameter &order= in a registersale.asp call. Can contain an alphanumerical string with a length of 0 to 40 characters. In order to upload orders with empty OrderIds (length 0) into our system, your key accounter or support must have adapted your program settings. Otherwise, the length must be between 1 and 40 characters. If in XML you submit a data set, where you would like to leave OrderId unspecified (because you identify the transaction through the TransactionId), then please don t submit a line like this: <OrderId></OrderId> because this is interpreted as a OrderId with the length 0, which is incorrectly formatted. Please instead submit this line as <OrderId xsi:nil= true /> 5. ProgramId The identifier of the program, for which you would like to insert or update the transactions. Must be equal to the ID of the program, for which you are logged in while you perform the import. Can contain positive integer values between 1 and Thousand separators are not permitted. 6. PublisherId Order Import File Definition February 2013 Page 7

8 The identifier of the publisher, which shall be assigned to this transaction. At the time of the import, you need to have an accepted partnership with this publisher and the publisher must be active. Can contain positive integer values between 1 and Thousand separators are not permitted. If in XML you submit a data set, where you would like to leave PublisherId unspecified, then please don t submit a line like this: <PublisherId></PublisherId> because this is interpreted as a PublisherId with the length 0, which is incorrectly formatted. Please instead submit this line as <PublisherId xsi:nil= true /> 7. Status The status, which the transaction shall receive through this import. Can be any of these strings (case sensitive): Open Confirmed Cancelled Please note that in the import of new transactions, the status must be set to Open. 8. NetPrice In transactions with the RateMode Sale, this is the monetary value, which shall be used to calculate the publisher commission, applying the submitted rate. Typically, this is the shopping cart value of a customer in an online shopping session. Can optionally be defined for lead transactions. Can contain positive decimal numbers with two decimal places. Thousand separators are not permitted. Must always be greater than 0. If you would like to reduce the commission to 0, please set the Status of the transaction to Cancelled, define a CancellationReason and leave the NetPrice at its previous value. 9. CancellationReason If a transaction is cancelled or the NetPrice is changed, the publisher shall be informed why this has been done. E.g. because it was booked twice, or a customer sent goods back, Can contain an alphanumerical string with a length of 5 to 100 characters. If in XML you submit a data set, where you would like to leave CancellationReason unchanged, then please don t submit a line like this: <CancellationReason></CancellationReason> because this is interpreted as a CancellationReason with the length 0, which is incorrectly formatted. Please instead submit this line as <CancellationReason xsi:nil= true /> Order Import File Definition February 2013 Page 8

9 10. RegistrationDate This is the date when the order has been generated within your system. This field is only considered when a new transaction is submitted into our system with this import. Cannot be changed afterwards. Can contain any date in the past, but max. 60 days before the current date. Cannot be before the ClickDate. Must be formatted in any of our supported date formats. Please note: if you open a CSV file in Excel the date is sometimes displayed in a different format than it is saved in the CSV file. If you get a date format error when importing this file, please check the date format in a text editing software such as Windows Notepad. 11. ClickDate This is the date of the click, which led to the generation of the transaction. This field is only considered when a new transaction is submitted into our system with this import. Cannot be changed afterwards. Can contain any date in the past, between today and the start of your program on the affilinet platform. Cannot be after the RegistrationDate. Must be formatted in any of our supported date formats. Please note: if you open a CSV file in Excel the date is sometimes displayed in a different format than it is saved in the CSV file. If you get a date format error when importing this file, please check the date format in a text editing software such as Windows Notepad. 12. SubId The column SubId can be included in the CSV import file. But it will not be displayed in the CSV export file. The column is optional it contains the SubId for publishers. The entry in this column can have a maximum length of 80 characters. Order Import File Definition February 2013 Page 9