--- title: Historical Data slug: historical-data docTags: createdAt: 2026-06-01T13:20:12.573Z --- ## Why Forter asks for your historical data To ensure the highest level of accuracy for our decisioning model, Forter customizes our model to fit the specific risk profile of each of our customers. We achieve this by training the model with your past order and account data, including actual fraud outcomes, in order to provide you with better accuracy from Day 1. To provide the best results, we require comprehensive historical data including many of the data points that are required for a live integration. The timeframe for the requested data will depend on your traffic volume and the solutions you are leveraging. This helps us to understand both new and established buyer patterns. If for any reason you're unable to provide us with data covering the specified timeframe, you should notify your dedicated Implementation Manager who will provide guidance on a suitable path forward. ## Download a template Below, you will find details on what historical data is relevant to share with Forter, including a CSV example that may serve as a template. Each header column in the template maps to a parameter in our API, so you can use the [API Reference](https://docs.forter.com/reference) for formatting requirements and enum options for each field. A few fields that are specific to historical data are defined below. ## Upload file securely Forter processes your historical order data offline using batch files in a CSV format. To ensure secure transmission of this data, please format your extracted data in the CSV format provided and upload to a dedicated AWS S3 folder that we have created for your account. You can find instructions on how to set up your credentials and access the folder [here](https://portal.forter.com/app/integration/docs/secure-file-transfer). :::::ExpandableHeading ## Order history Forter requires 12 months of order data to account for spikes in traffic, promotional and seasonality effects. Order history should include traffic from payment methods even if they are excluded from decisioning, as well as any order attempts that resulted in payment authorization failure, were declined for fraud, or otherwise canceled. The required data points include buyer information, cart items, payment methods, promotions used, as well as billing and shipping details, using the same fields as the *Order API*. The model also needs to know the fulfillment status of each order, as well as any declined transactions and related chargebacks or fraud notifications. While fulfillment status would normally be provided in a subsequent call to the Order Status API in your live integration, please include it along with your order history under historicalData.status. Enum options are: COMPLETED, CANCELED\_BY\_MERCHANT, CANCELED\_BY\_CUSTOMER. In the case of transactions that were declined for suspicion of fraud, mark the order as historicalData.status = CANCELED\_BY\_MERCHANT and historicalData.fraud = DECLINED\_FOR\_FRAUD. In the case of transactions that were processed but a chargeback or fraud notification was later received, mark the order as historicalData.status = COMPLETED and use one of the following enums for historicalData.fraud:  - FRAUD\_CHARGEBACK - dispute submitted by the customer with a reason code of fraud, or a retrieval request otherwise known as a “soft chargeback” - SERVICE\_CHARGEBACK - dispute submitted by the customer for item not received or for not meeting the quality standard expected - PRE\_CHARGEBACK\_ALERT - notification of an incoming dispute from a third party - FRAUD\_REFUND - complaint of fraud by the customer without a formal dispute If your fraud data is not available in the same system as your order history, you may upload this information separately. Please refer to the instructions below for Dispute history. ### Build your template For Order history, the specific columns to send to Forter vary based on your particular integration. To create a customized template, you can use the CSV base template below and add the relevant columns for your relevant vertical and any payment methods. :::CodeblockTabs Base example order data (CSV) ```none accountOwner.accountId,accountOwner.created,accountOwner.email,accountOwner.firstName,accountOwner.lastName,cartItems[0].basicItemData.name,cartItems[0].basicItemData.quantity,cartItems[0].basicItemData.category,cartItems[0].basicItemData.price.amountLocalCurrency,cartItems[0].basicItemData.price.amountUSD,cartItems[0].basicItemData.price.currency,checkoutTime,connectionInformation.customerIP,historicalData.fraud,historicalData.orderStatus,orderId,orderType,payment[0].billingDetails.address.address1,payment[0].billingDetails.address.address2,payment[0].billingDetails.address.city,payment[0].billingDetails.address.country,payment[0].billingDetails.address.region,payment[0].billingDetails.address.zip,payment[0].billingDetails.personalDetails.email,payment[0].billingDetails.phone[0].phone,payment[0].billingDetails.personalDetails.fullName,payment[0].billingDetails.personalDetails.firstName,payment[0].billingDetails.personalDetails.lastName,payment[0].creditCard.bin,payment[0].creditCard.expirationMonth,payment[0].creditCard.expirationYear,payment[0].creditCard.lastFourDigits,payment[0].creditCard.nameOnCard,payment[0].creditCard.verificationResults.eciValue,payment[0].creditCard.verificationResults.processorResponseCode,payment[0].creditCard.verificationResults.processorResponseText,primaryDeliveryDetails.deliveryMethod,primaryDeliveryDetails.deliveryType,primaryRecipient.personalDetails.email,primaryRecipient.phone[0].phone,totalAmount.amountLocalCurrency,totalAmount.amountUSD,totalAmount.currency e520-ba9a-367-60b,1415273168,john_s@test.com,John,Smith,White GenericBrand handbag,1,Apparel and accessories,105.55,99.95,CAD,1699916780,10.0.0.127,SERVICE_CHARGEBACK,COMPLETED,4306795,WEB,235 Montgomery st.,Ste. 1110,San Francisco,US,CA,2157-08-23,john_s@test.com,15557654321,John Smith,John,Smith,42424242,3,2018,4242,John R. H. Smith,5,D23,Stolen card,USPS - Ground Mail,PHYSICAL,john_s@test.com,15557654321,105.55,99.95,CAD ``` ::: Add relevant columns for cart item details, based on the type of goods you sell. :::CodeblockTabs Retail ```none primaryRecipient.address.address1,primaryRecipient.address.address2,primaryRecipient.address.city,primaryRecipient.address.zip,primaryRecipient.address.country,primaryRecipient.address.region 235 Montgomery st.,Ste. 1110,San Francisco,94104,US,CA ``` Gift Cards ```none cartItems[0].beneficiaries[0].personalDetails.email,cartItems[0].beneficiaries[0].personalDetails.firstName,cartItems[0].beneficiaries[0].personalDetails.lastName,cartItems[0].beneficiaries[0].phone[0].phone john_s@test.com,John,Smith,15557654321 ``` Tickets ```none cartItems[0].itemSpecificData.ticketsAndEvents.eventTime,cartItems[0].itemSpecificData.ticketsAndEvents.eventName,cartItems[0].itemSpecificData.ticketsAndEvents.eventVenueName,cartItems[0].itemSpecificData.ticketsAndEvents.eventLocation.address1,cartItems[0].itemSpecificData.ticketsAndEvents.eventLocation.zip,cartItems[0].itemSpecificData.ticketsAndEvents.eventLocation.city,cartItems[0].itemSpecificData.ticketsAndEvents.eventLocation.region,cartItems[0].itemSpecificData.ticketsAndEvents.eventLocation.country,cartItems[0].itemSpecificData.ticketsAndEvents.eventType,cartItems[0].seller.sellerDetails.sellerAccountCreationDate,cartItems[0].seller.sellerDetails.sellerLastLoginIP.ip,cartItems[0].seller.sellerDetails.sellerPersonalDetails.accountId,cartItems[0].seller.sellerDetails.sellerPersonalDetails.email 1420070400,FIFA World Cup Final,Maracana Stadium,235 Montgomery st.,94104,San Francisco,CA,US,sports,1415273168,10.0.0.128,,john_s@test.com ``` Accomodation ```none cartItems[0].itemSpecificData.accommodation.accommodationName,cartItems[0].itemSpecificData.accommodation.numberOfGuests,cartItems[0].itemSpecificData.accommodation.type,cartItems[0].itemSpecificData.accommodation.accommodationAddress.address1,cartItems[0].itemSpecificData.accommodation.accommodationAddress.address2,cartItems[0].itemSpecificData.accommodation.accommodationAddress.city,cartItems[0].itemSpecificData.accommodation.accommodationAddress.country,cartItems[0].itemSpecificData.accommodation.accommodationAddress.region,cartItems[0].itemSpecificData.accommodation.accommodationAddress.zip,cartItems[0].itemSpecificData.accommodation.duration.endDate,cartItems[0].itemSpecificData.accommodation.duration.startDate,cartItems[0].itemSpecificData.accommodation.location.city,cartItems[0].itemSpecificData.accommodation.location.country,cartItems[0].itemSpecificData.accommodation.location.region Forter Boutique Hotel,2,HOTEL,235 Montgomery st.,Ste. 1110,San Francisco,US,CA,94104,2014-11-15,2014-10-28,San Francisco,US,CA ``` Transportation ```none cartItems[0].itemSpecificData.transport[0].carrier,cartItems[0].itemSpecificData.transport[0].duration.endTime,cartItems[0].itemSpecificData.transport[0].duration.startTime,cartItems[0].itemSpecificData.transport[0].endPoint.roughLocation.airportCode,cartItems[0].itemSpecificData.transport[0].endPoint.roughLocation.city,cartItems[0].itemSpecificData.transport[0].endPoint.roughLocation.country,cartItems[0].itemSpecificData.transport[0].endPoint.roughLocation.region,cartItems[0].itemSpecificData.transport[0].endPoint.roughLocation.seaportCode,cartItems[0].itemSpecificData.transport[0].leg,cartItems[0].itemSpecificData.transport[0].startPoint.roughLocation.airportCode,cartItems[0].itemSpecificData.transport[0].startPoint.roughLocation.city,cartItems[0].itemSpecificData.transport[0].startPoint.roughLocation.country,cartItems[0].itemSpecificData.transport[0].startPoint.roughLocation.region,cartItems[0].itemSpecificData.transport[0].startPoint.roughLocation.seaportCode,cartItems[0].itemSpecificData.transport[0].type Forter airlines,1420294711,1412345911,JFK,Anytown,DK,New York,USNYC,2,JFK,Anytown,DK,New York,USNYC,AIR_TRAVEL ``` Marketplace ```none cartItems[0].seller.sellerDetails.sellerAccountCreationDate,cartItems[0].seller.sellerDetails.sellerLastLoginIP.ip,cartItems[0].seller.sellerDetails.sellerPersonalDetails.accountId,cartItems[0].seller.sellerDetails.sellerPersonalDetails.email 1415273168,10.0.0.128,,john_s@test.com ``` Food ```none cartItems[0].itemSpecificData.food.restaurantAddress.address1,cartItems[0].itemSpecificData.food.restaurantAddress.address2,cartItems[0].itemSpecificData.food.restaurantAddress.city,cartItems[0].itemSpecificData.food.restaurantAddress.country,cartItems[0].itemSpecificData.food.restaurantAddress.region,cartItems[0].itemSpecificData.food.restaurantAddress.zip,cartItems[0].itemSpecificData.food.restaurantId,cartItems[0].itemSpecificData.food.restaurantName,primaryRecipient.address.address1,primaryRecipient.address.address2,primaryRecipient.address.city,primaryRecipient.address.zip,primaryRecipient.address.country,primaryRecipient.address.region 235 Montgomery st.,Ste. 1110,San Francisco,US,CA,94104,eh674df9,Ron's Steak House,235 Montgomery st.,Ste. 1110,San Francisco,94104,US,CA ``` ::: Include relevant payment methods for your integration. Credit card is already included in the base CSV. :::CodeblockTabs Apple Pay ```none payment[0].applePay.bin,payment[0].applePay.expirationMonth,payment[0].applePay.expirationYear,payment[0].applePay.lastFourDigits,payment[0].applePay.nameOnCard ,3,2018,4242,John R. H. Smith ``` Google Pay ```none payment[0].androidPay.bin,payment[0].androidPay.expirationMonth,payment[0].androidPay.expirationYear,payment[0].androidPay.lastFourDigits,payment[0].androidPay.nameOnCard ,3,2018,4242,John R. H. Smith ``` PayPal ```none payment[0].paypal.payerEmail,payment[0].paypal.payerId,payment[0].paypal.paymentStatus john_s@test.com,FD000A45P,COMPLETED ``` Tokenized card ```none payment[0].tokenizedCard.bin,payment[0].tokenizedCard.expirationMonth,payment[0].tokenizedCard.expirationYear,payment[0].tokenizedCard.lastFourDigits,payment[0].tokenizedCard.verificationResults.processorResponseCode,payment[0].tokenizedCard.verificationResults.processorResponseText,payment[0].tokenizedCard.verificationResults.eciValue,payment[0].tokenizedCard.token ,3,2018,4242,D23,Stolen card,5,tkn-77620C360132856A103477D2959967AB ``` ::: Alternatively, you can download the comprehensive template file and remove the irrelevant columns. ::::VerticalSplit{layout="middle"} :::VerticalSplitItem ::: :::VerticalSplitItem ::File{src="https://api.archbee.com/api/presign/-MJXmQSFT34OMN6RlO4NM-XjOuvUCvBxtx9a9J2l1rm-20250805-161203.csv" label="historical-order-template.csv"} ::: :::: ### Orders with multiple cart items For orders that have multiple cart items or multiple payment methods, which are represented in arrays, please follow one of the patterns below. :::CodeblockTabs Example with items in columns (CSV) ```none orderId,cartItems[0].basicItemData.name,cartItems[0].basicItemData.quantity,cartItems[0].basicItemData.category,cartItems[0].basicItemData.price.amountUSD,cartItems[1].basicItemData.name,cartItems[1].basicItemData.quantity,cartItems[1].basicItemData.category,cartItems[1].basicItemData.price.amountUSD,cartItems[2].basicItemData.name,cartItems[2].basicItemData.quantity,cartItems[2].basicItemData.category,cartItems[2].basicItemData.price.amountUSD,totalAmount.amountUSD 4306795,White GenericBrand handbag,1,Apparel and accessories,99.95,Brown GenericBrand wallet,1,Apparel and accessories,39.95,Green GenericBrand duffel,1,Apparel and accessories,69.95,209.85 ``` Example with items in rows (CSV) ```none orderId,cartItems[].basicItemData.name,cartItems[].basicItemData.quantity,cartItems[].basicItemData.category,cartItems[].basicItemData.price.amountUSD,totalAmount.amountUSD 4306795,White GenericBrand handbag,1,Apparel and accessories,99.95,209.85 4306795,Brown GenericBrand wallet,1,Apparel and accessories,39.95,209.85 4306795,Green GenericBrand duffel,1,Apparel and accessories,69.95,209.85 ``` ::: ::::: :::::ExpandableHeading ## Dispute history Forter requires 12 months of historical dispute data covering all of the order data provided. Most claims are issued within 90 days from the time of transaction. As a result, dispute history is not expected to match the order history time frame perfectly. If you were able to include dispute data in the `historicalData.fraud` field in your Order history, you may skip this step. If not, please share this data in an additional CSV that includes the `orderID` from your Order history file along with the `reason` string that was provided by the processor or claim source.  :::CodeblockTabs Example dispute data (CSV) ```none orderId,reason 4306795,Fraudulent Transaction: Card Not Present Environment ``` ::: ::::VerticalSplit{layout="middle"} :::VerticalSplitItem ::: :::VerticalSplitItem ::File{src="https://api.archbee.com/api/presign/-MJXmQSFT34OMN6RlO4NM-rsgV5sddenlieNx0bnO5B-20250805-160452.csv" label="historical-dispute-template.csv"} ::: :::: ::::: :::::ExpandableHeading ## Signup history Forter requires 6 to 12 months of historical account signup data.  Signup history should contain the information provided by the customer as part of the registration process as well as data captured in the background such as account ID, timestamp, and connection information. The required data points use mostly the same fields as the [Signup API](https://docs.forter.com/reference/signup).  Given that the accounts could have been closed or suspended in that timeframe, Forter also requests that you provide us with the current status of the account, though in your live integration this will be shared via [Account Status API](https://docs.forter.com/reference/account-status). The enum options for `accountData.status` are: ACTIVE, SUSPENDED, CLOSED, GUEST, PENDING. :::CodeblockTabs Example signup data (CSV) ```none accountId,eventTime,signupStatus,connectionInformation.customerIP,connectionInformation.userAgent,connectionInformation.merchantDeviceIdentifier,accountData.personalDetails.firstName,accountData.personalDetails.lastName,accountData.personalDetails.email,accountData.type,accountData.status e520-ba9a-367-60b,1415287568000,SUCCESS,10.0.0.127,"Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36",HGJ7512345H3,John,Smith,john_s@test.com,BUSINESS,ACTIVE ``` ::: ::::VerticalSplit{layout="middle"} :::VerticalSplitItem ::: :::VerticalSplitItem ::File{src="https://api.archbee.com/api/presign/-MJXmQSFT34OMN6RlO4NM-gSPWZKlV3AR4Zc2GMFYww-20250805-160553.csv" label="historical-signup-template.csv"} ::: :::: ::::: :::::ExpandableHeading ## Login history Forter requires 6 months of historical account login data.  Login history should contain all the information collected during login, such as the inputs entered by the customer, as well as data captured in the background such as timestamp, connection information, and the existing account details. The required data points use mostly the same fields as the [Login API](https://docs.forter.com/reference/login). Your dataset should include login attempts that resulted in failure, so that our models can learn from these as well. The enum options for `loginStatus` are: SUCCESS, FAILED, BLOCKED\_BY\_MERCHANT, ACCOUNT\_DOES\_NOT\_EXIST. Given that the accounts could have been closed or suspended since the login event, Forter also requests that you provide us with the current status of the account, though in your live integration this will be shared via [Account Status API](https://docs.forter.com/reference/account-status). The enum options for `accountData.status` are: ACTIVE, SUSPENDED, CLOSED, GUEST, PENDING. :::CodeblockTabs Example login data (CSV) ```none accountId,eventTime,connectionInformation.customerIP,connectionInformation.userAgent,connectionInformation.merchantDeviceIdentifier,loginMethodType,loginStatus,userInput.inputType,userInput.email,userInput.phone,accountData.personalDetails.firstName,accountData.personalDetails.lastName,accountData.personalDetails.email,accountData.created,accountData.type,accountData.status e520-ba9a-367-60b,1471171293,10.0.0.127,"Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36",HGJ7512345H3,PASSWORD,SUCCESS,EMAIL,john_s@test.com,15557654321,John,Smith,john_s@test.com,1415287568000,BUSINESS,CLOSED ``` ::: ::::VerticalSplit{layout="middle"} :::VerticalSplitItem ::: :::VerticalSplitItem ::File{src="https://api.archbee.com/api/presign/-MJXmQSFT34OMN6RlO4NM-Zcro8sBz3RtRzBovS4GR4-20250805-160635.csv" label="historical-login-template.csv"} ::: :::: ::::: :::::ExpandableHeading ## Compensation history Forter requires 6 months of historical compensation request data. Compensation request history should contain the status and total compensation amount granted for the order, as well as details on each item included in the request. Note that the fields match the data structure in the [Order Status API](https://docs.forter.com/reference/order-status), though you may be utilizing the [Compensation Request API](https://docs.forter.com/reference/compensation-request) in your live integration. For orders that have multiple cart items, please follow one of the patterns below.  :::CodeblockTabs Example compensation with items in columns (CSV) ```none orderId,eventTime,updatedStatus,compensationStatus.totalGrantedAmount.amountUSD,compensationStatus.totalGrantedAmount.amountLocalCurrency,compensationStatus.totalGrantedAmount.currency,compensationStatus.itemStatus[0].basicItemData.quantity,compensationStatus.itemStatus[0].basicItemData.price.amountUSD,compensationStatus.itemStatus[0].basicItemData.price.amountLocalCurrency,compensationStatus.itemStatus[0].basicItemData.price.currency,compensationStatus.itemStatus[0].basicItemData.productId,compensationStatus.itemStatus[0].basicItemData.name,compensationStatus.itemStatus[0].basicItemData.type,compensationStatus.itemStatus[0].statusData.updatedStatus,compensationStatus.itemStatus[0].statusData.compensationTypeGranted,compensationStatus.itemStatus[0].statusData.reasonCategory,compensationStatus.itemStatus[1].basicItemData.quantity,compensationStatus.itemStatus[1].basicItemData.price.amountUSD,compensationStatus.itemStatus[1].basicItemData.price.amountLocalCurrency,compensationStatus.itemStatus[1].basicItemData.price.currency,compensationStatus.itemStatus[1].basicItemData.productId,compensationStatus.itemStatus[1].basicItemData.name,compensationStatus.itemStatus[1].basicItemData.type,compensationStatus.itemStatus[1].statusData.updatedStatus,compensationStatus.itemStatus[1].statusData.compensationTypeGranted,compensationStatus.itemStatus[1].statusData.reasonCategory 2356fdse0rr489,1415287568000,SENT,120.45,134.15,CAD,1,99.95,105.55,CAD,Ag54352R7768kkO,White GenericBrand handbag,TANGIBLE,ACCEPTED_BY_MERCHANT,REFUND,WRONG_ITEM,1,99.95,105.55,CAD,Ab54352R7768kkO,Black Socks,TANGIBLE,ACCEPTED_BY_MERCHANT,REFUND,WRONG_ITEM ``` Example compensation with items in rows (CSV) ```none orderId,eventTime,updatedStatus,compensationStatus.totalGrantedAmount.amountUSD,compensationStatus.totalGrantedAmount.amountLocalCurrency,compensationStatus.totalGrantedAmount.currency,compensationStatus.itemStatus[0].basicItemData.quantity,compensationStatus.itemStatus[0].basicItemData.price.amountUSD,compensationStatus.itemStatus[0].basicItemData.price.amountLocalCurrency,compensationStatus.itemStatus[0].basicItemData.price.currency,compensationStatus.itemStatus[0].basicItemData.productId,compensationStatus.itemStatus[0].basicItemData.name,compensationStatus.itemStatus[0].basicItemData.type,compensationStatus.itemStatus[0].statusData.updatedStatus,compensationStatus.itemStatus[0].statusData.compensationTypeGranted,compensationStatus.itemStatus[0].statusData.reasonCategory 2356fdse0rr489,1415287568000,SENT,120.45,134.15,CAD,1,99.95,105.55,CAD,Ag54352R7768kkO,White GenericBrand handbag,TANGIBLE,ACCEPTED_BY_MERCHANT,REFUND,WRONG_ITEM 2356fdse0rr489,1415287568000,SENT,120.45,134.15,CAD,1,20.5,28.6,CAD,Ab54352R7768kkO,Black Socks,TANGIBLE,ACCEPTED_BY_MERCHANT,REFUND,WRONG_ITEM ``` ::: ::::VerticalSplit{layout="middle"} :::VerticalSplitItem ::: :::VerticalSplitItem ::File{src="https://api.archbee.com/api/presign/-MJXmQSFT34OMN6RlO4NM-05BWfd4niv6b-825LTC3M-20250805-161515.csv" label="historical-compensation-template.csv"} ::: :::: :::::