How to import customers from another system

Import customer data from another system into Billforward

To import customers, you’ll need to prepare the data in a format that Billforward can recognise.

We can import customer information (name, contact details, and addresses) along with payment details.

Customer details

Prepare a CSV file according to the following template. Each row will become an account in Billforward.

custom_id,company_name,first_name,last_name,email,landline,mobile,tax_number,hubspot_id,xero_id,salesforce_id,quickbooks_id
1DF1BE0E-A481-4336,Acme Ltd.,John,Smith,john.smith@test.com,+1-555-555-1234,+1-555-555-5678,912-34-5678,2345,305ca5cf-497d-4fee-a161-cdb30e6be989,cu123,123

The CSV file should contain a header row and the following columns:

• custom_id: this can be any unique ID (up to 255 chars long) that makes sense to you. It will be attached to the Billforward account as searchable metadata.
• company_name, first_name, last_name, email, landline, mobile: optional fields for the customer’s contact details.
• tax_number: VAT or other Tax ID
• hubspot_id: if the already customer exists in a HubSpot system linked to your Billforward organization, you can provide the HubSpot contact ID and updates will be automatically synced between the two systems.
• xero_id: optional Xero contact ID.
• salesforce_id: optional Salesforce customer ID.
• quickbooks_id: optional QuickBooks customer ID.

Customer addresses (optional)

You can import up to two addresses for each customer: a billing address and a shipping address. As such, you’ll need to prepare these in a separate CSV file.

custom_id,line1,line2,line3,city,province,country,postcode,primary_billing,primary_shipping
1DF1BE0E-A481-4336,Apartment 1c,123 Derrick Street,,Boston,MA,US,02130,true,true

• custom_id: this file should match the ID of a customer record in the customer details CSV.
• line1, line2, line3, city, province, country, postcode: fields for customer address lines.
• primary_billing, primary_shipping: can be true or false to indicate whether this address should be treated as the primary billing or primary shipping addresses for the customer. There can be at most one primary billing address and one primary shipping address per customer, although it can be the same address for both.

Payment details (optional)

We can import payment details for three different payment gateways: Shuttle, Square, and Stripe.

Shuttle payment details

custom_id,card_type,expiry_month,expiry_year,last4,underlying_token,shuttle_id,shuttle_account_id,shuttle_gateway
1DF1BE0E-A481-4336,MASTERCARD,1,2021,7890,"{""customerId"":""cst_m4UHAueK7K"",""mandateId"":""mdt_B8TATs3Jsp""}",pm_21917_10403,acc_21917_10045,gw_21817_10002

• custom_id: ID matching a record in the customer details CSV.
• card_type: for example “VISA” or “MASTERCARD”.
• expiry_month: numeric value in the range 1–12 (inclusive).
• expiry_year: 4-digit year.
• last4: last 4 digits of the card number.
• underlying_token: Shuttle token as a plain string or a stringified JSON object.
• shuttle_id, shuttle_account_id, shuttle_gateway: details of the customer in Shuttle.

Square Payment Details

custom_id,card_type,expiry_month,expiry_year,last4,square_id,location_id
1DF1BE0E-A481-4336,MASTERCARD,1,2021,7890,ccof:WPqcLpIHXbsJOAL24GB,LEBEV9D7ZGLPH

• custom_id: ID matching a record in the customer details CSV.
• card_type: for example “VISA” or “MASTERCARD”.
• expiry_month: numeric value in the range 1–12 (inclusive).
• expiry_year: 4-digit year.
• last4: last 4 digits of the card number.
• square_id: ID of customer in Square.
• location_id: optional location ID of the location where this payment method should be used.

Stripe Payment Details

custom_id,card_type,expiry_month,expiry_year,last4,payment_method_id,customer_id,bank_account_id,setup_intent_id
1DF1BE0E-A481-4336,MASTERCARD,1,2021,7890,pm_1I8pRoHCKs0TOGq3DAQMqCPK,cus_IkK5xqHI2BpmEA,ba_14Fzsu4qC8RqTHkhN2k9tHvs,seti_1I8pZ5HCKr0HOGq6dpwdvYFS

• custom_id: ID matching a record in the customer details CSV.
• card_type: for example “VISA” or “MASTERCARD”.
• expiry_month: numeric value in the range 1–12 (inclusive).
• expiry_year: 4-digit year.
• last4: last 4 digits of the card number.
• payment_method_id: Stripe payment method ID (with prefix “pm_”) or card ID (prefix “card_”).
• customer_id: Stripe customer ID.
• bank_account_id: bank account ID — for ACH customers only.
• setup_intent_id: only for newer, verified customers.