Skip to main content

​
Overview

This page describes the different types of data that can be sent to Mention Me via SFTP. All data must be in structured CSV format.
For connection details and folder structure, see SFTP Connection.
Column names are case sensitive and use PascalCase. Columns whose names do not match the expected values exactly will be ignored on import. The type values are also fixed strings: they must match exactly or the row will be rejected.
Columns may be supplied in any order, so CustomerFirstname,CustomerSurname is equivalent to CustomerSurname,CustomerFirstname.

​
Data Types

Mention Me accepts several types of inbound data via SFTP. The type column on each row selects which feed the row belongs to.
Used to send order or transaction data for conversion tracking. Each row represents a single order. This is commonly used for orders that cannot be captured by the JavaScript tag, such as orders placed over the phone or in a customer support application.Required fields:
​
type
string
required
Must be order. Example: order
​
CustomerEmail
string
required
The customer’s email address. Example: customer@example.com
​
OrderId
string
required
Unique order identifier. Example: ORD-12345
​
OrderDate
string
required
Date and time of the order (ISO 8601). Example: 2024-01-15T10:30:00Z
​
OrderTotal
string
required
Order total excluding VAT/taxes and delivery. Example: 49.99
​
OrderCurrency
string
required
ISO 4217 currency code. Example: GBP
Recommended fields (improve referral performance):
​
MerchantCouponCode
string
The coupon code used by the customer (if any). Example: REF-ABC123
​
IsSubscription
string
Whether this order is for a subscription (recurring). Helps us qualify and categorise the revenue. Example: false
​
IsFirstOrderInSubscription
string
Whether this is the customer’s first order initiating a subscription. Example: false
​
IsGift
string
Whether this order is a gift (bought for someone else). Gifts can be signals of advocacy. Example: false
​
DiscountAmount
string
The discount amount, assumed already deducted from the order total. Lets us calculate cost per acquisition. Example: 18.45
​
OrderItemCount
string
The number of items in the order. Helps us understand the type of purchase. Example: 3
​
CustomerAddressLine1
string
First line of the customer’s address. Example: 1-45 Durham Street
​
CustomerAddressLine2
string
Second line of the customer’s address. Example: VG01
​
CustomerAddressCity
string
City of the customer’s address. Example: London
​
CustomerAddressCounty
string
County or state of the customer’s address. Example: London
​
CustomerAddressPostcode
string
Postcode or zip code of the customer’s address. Example: SE11 5JH
​
CustomerAddressCountry
string
Country of the customer’s address. Example: United Kingdom
Optional fields:
​
CustomerId
string
Your internal customer identifier. Example: CUST-789
​
CustomerFirstname
string
Customer’s first name. Example: Alice
​
CustomerSurname
string
Customer’s last name. Example: Liddell
​
Segment
string
The segment this customer is in. Example: VIPs
​
Locale
string
Locale code. Example: en_GB
​
MerchantCustomField
string
Extra custom data used to qualify or segment the order. Example: NewCustomer|AccountID#1234
For ongoing subscription order data where you prefer not to send any PII, CustomerEmail can be replaced with CustomerHashedEmail. This requires that you follow the hashing instructions in the Hashing historical customer emails guide. When CustomerHashedEmail is used, no referees or referrers will be rewarded.
Used to enrol customers into the referral programme, for example customers who have confirmed they wish to take part. The type value determines whether a confirmation email is sent: use register to send a welcome email, or register-silently to register the customer without contacting them.
For GDPR compliance, only use this feed if you are certain you have the right to share this data, for example where customers have been told their data is shared for the purpose of running a referral programme. register-silently is preferred over register unless you have specific consent to send the customer referral emails.
Required fields:
​
type
string
required
register or register-silently. Example: register
​
CustomerEmail
string
required
The customer’s email address. Example: customer@example.com
​
CustomerFirstname
string
required
Customer’s first name. Example: Jane
​
CustomerSurname
string
required
Customer’s last name. Example: Smith
Optional fields:
​
CustomerId
string
Your internal customer identifier. Example: CUST-789
​
Locale
string
The locale of the referral campaign the customer should be enrolled into. Example: fr_CA
​
Segment
string
The segment this customer is in. Example: VIPs
​
OrderId
string
Associated order. Example: ORD-12345
​
OrderDate
string
Order date. Example: 2024-01-15T10:30:00Z
​
OrderTotal
string
Order total. Example: 49.99
​
OrderCurrency
string
Currency. Example: GBP
​
MerchantCouponCode
string
Voucher used. Example: REF-ABC123
Used to notify Mention Me that a new customer has cancelled their order, so any pending referrer reward can be withheld.Required fields:
​
type
string
required
Must be referee-cancelled. Example: referee-cancelled
​
CustomerEmail
string
required
Email address of the customer who cancelled their order. Example: customer@example.com
Optional fields:
​
OrderId
string
The cancelled order ID. Example: ORD-12345
Example:
type,CustomerEmail
referee-cancelled,alice.bloggs@example.com
referee-cancelled,joe.bloggs@example.com
In many cases the eligibility of a customer to earn a reward depends on more than just making a purchase. For example, the customer may have to keep a subscription for more than 30 days or pass an external fraud check.The eligibility feed lets you tell Mention Me about each customer who may have met the criteria to be rewarded. It is important that all potentially eligible customers are provided, as only Mention Me knows whether they are due a reward.Required fields:
​
type
string
required
Must be referee-eligible. Example: referee-eligible
Plus one of the following identifiers for the customer:
​
CustomerEmail
string
Email address of the potentially eligible customer. Example: customer@example.com
​
CustomerId
string
Your internal ID of the potentially eligible customer. Example: 123456-example
​
OrderId
string
The order ID placed by the potentially eligible customer. Example: O123X4
Examples:By Customer Email:
type,CustomerEmail
referee-eligible,alice.bloggs@example.com
referee-eligible,joe.bloggs@example.com
By Customer ID:
type,CustomerId
referee-eligible,123alice
referee-eligible,345joe
By Order ID:
type,OrderId
referee-eligible,O123X4
referee-eligible,O123C5
Used to confirm referral purchases completed in store via a coupon. Referral can drive customers into your stores to make their first purchase: the referral happens before the purchase and the referee is given a single-use voucher to use in store. This feed sends back confirmation that the code was used and the details of the purchase. Because you may not have the customer’s email address, the feed only requires the coupon code plus the transaction details.If you have collected the customer’s email address you may include it, and we will record both the original referee email and the one used to confirm the purchase.Required fields:
​
type
string
required
Must be coupon-redemption. Example: coupon-redemption
​
MerchantCouponCode
string
required
The coupon code used by the customer in the transaction. Example: REF-ABC123
​
OrderId
string
required
Unique order or transaction identifier. Example: TXN-789
​
OrderDate
string
required
Date and time of the order (ISO 8601). Example: 2024-01-15T10:30:00Z
​
OrderTotal
string
required
Transaction value excluding VAT/taxes and delivery. Example: 75.00
​
OrderCurrency
string
required
ISO 4217 currency code. Example: GBP
Recommended fields (improve referral performance):
​
IsSubscription
string
Whether this order is for a subscription (recurring). Example: false
​
IsFirstOrderInSubscription
string
Whether this is the customer’s first order initiating a subscription. Example: false
​
IsGift
string
Whether this order is a gift. Example: false
​
DiscountAmount
string
The discount amount, assumed already deducted from the order total. Example: 18.45
​
OrderItemCount
string
The number of items in the order. Example: 3
Optional fields:
​
CustomerId
string
Your internal customer identifier. Example: CUST-789
​
CustomerEmail
string
The customer’s email address, if collected. Example: customer@example.com
​
Segment
string
The segment this customer is in. Example: VIPs
Example:
type,MerchantCouponCode,OrderId,OrderDate,OrderTotal,OrderCurrency
coupon-redemption,PM012422452,INV100032313,2024-01-15T10:30:00Z,17.99,GBP
coupon-redemption,INSTORE-ABJ124152,INV100032314,2024-01-16T11:00:00Z,44.05,GBP
Used to notify Mention Me of customer account changes, for example a name or email address update, so the customer’s referral history is preserved against their new details. This is most common in subscription businesses such as the energy sector.Required fields:
​
type
string
required
Must be customer-details-changed. Example: customer-details-changed
​
CustomerEmail
string
required
The current email address of the customer as Mention Me currently knows it. Example: old@example.com
Plus at least one of the following fields, holding the new value:
​
NewCustomerEmail
string
The new email address of the customer. Example: new@example.com
​
CustomerId
string
The internal ID Mention Me should use for this customer from now on. Example: AW79302
​
CustomerFirstname
string
The first name Mention Me should use from now on. Example: Alice
​
CustomerSurname
string
The surname Mention Me should use from now on. Example: Wonderland
Example:The first row below changes Alice’s surname and email address. The second changes only Joe’s first name.
type,CustomerEmail,NewCustomerEmail,CustomerFirstname,CustomerSurname
customer-details-changed,alice.liddell@example.com,alice.wonderland@example.com,Alice,Wonderland
customer-details-changed,joe.bloggs@example.com,,Joseph,
Relevant for subscription businesses only.
Used to inform Mention Me that a customer has stopped paying for a service or subscription. This supports models where a lapsed customer can be given a referral offer if they are referred and return as a paying customer after a period of time.Required fields:
​
type
string
required
Must be customer-lapsed. Example: customer-lapsed
​
CustomerEmail
string
required
Email address of the customer who has lapsed. Example: customer@example.com
Example:
type,CustomerEmail
customer-lapsed,alice.bloggs@example.com
customer-lapsed,joe.bloggs@example.com
Used to record when a customer has completed a non-order action that should trigger a reward or progress in your referral programme, for example signing up for a newsletter, leaving a review, or registering an account.Required fields:
​
type
string
required
Must be incentivised-action. Example: incentivised-action
​
CustomerEmail
string
required
Email address of the customer who completed the action. Example: customer@example.com
​
ActionId
string
required
The identifier, provided by Mention Me, that identifies the action performed. Example: i5d88c29eb14e7
Example:The following example shows alice.liddell@example.com completing action i5d88c29eb14e7, which corresponds to an action defined inside Mention Me (for example, completing a review).
type,CustomerEmail,ActionId
incentivised-action,alice.liddell@example.com,i5d88c29eb14e7
Used to permanently remove all records of a specific customer, including all Personally Identifiable Information. This can be used to satisfy a data-subject erasure request.
This action is irreversible.
Required fields:
​
type
string
required
Must be purge. Example: purge
​
CustomerEmail
string
required
Email address of the customer to purge. Example: customer@example.com
Example:
type,CustomerEmail
purge,alice.bloggs@example.com
purge,joe.bloggs@example.com

​
File Format Requirements

  • Format: CSV with headers
  • Encoding: UTF-8
  • Delimiter: Comma (,)
  • Line endings: Unix (\n) or Windows (\r\n)
  • Quoting: Fields containing commas, quotes, or newlines must be double-quoted
  • Column names: PascalCase, case sensitive. Mis-named columns are silently ignored on import
  • Column order: Columns may be supplied in any order
  • Mixed feeds: A single file may contain rows with different type values; each row is processed according to its type

​
File Naming

Any filename can be used, but each file must be unique. We recommend including a date in the filename, for example Orders-20240115.csv.

​
Errors and Malformed Data

Malformed or incorrect data is handled as follows. Missing columns or column headers
  • A file missing a column header will not be processed.
  • A file missing a mandatory column, or with the column incorrectly named, will be ignored.
  • A file missing an optional column, or with an optional column incorrectly named, will be processed as if the optional column was not present.
Missing or malformed rows Each row is treated as a separate entity, so errors in one row do not affect another. A malformed row (for example, an empty row, or a row with an email address that has no @ symbol) will be ignored, and the remainder of the file will be processed as normal.

​
Need Help?

Contact the Support Team using the Help form.
Last modified on June 18, 2026