Customers


In most workflows, creating a Stripe customer creates a corresponding NetSuite customer.

Here's how it works:

  • By default, customers are always created as company customers. This can be customized on a global or per-record basis.
  • The Stripe-generated customer ID (cus_123) is used as the entity ID.
  • description if specified, is used as the NetSuite company name. Otherwise, the Stripe ID is used as the company name.
  • Phone, email, and address is also translated over if specified on the Stripe customer.
  • If provided, the billing & shipping addresses is pulled into NetSuite
  • Any additional standard or custom fields can be specified using metadata
  • There's a duplicate detection system that can help link Stripe customers to pre-existing NetSuite customers.

Using Existing Customers

If there's a common identifier shared between Stripe customers and NetSuite customers, such as an email or account ID, we can use that data to link a Stripe customer to a NetSuite customer in order to eliminate duplicates.

You can link existing NetSuite customer records with Stripe customers by specifying the NetSuite customer's internalId in the Stripe customer metadata.

Here's an example:

Stripe::Customer.create(
  email: "existing-netsuite@example.com",
  metadata: {
    netsuite_customer_id: 123
  }
)

Customer Information Pulled from Stripe

Here's a list of the fields that are pulled by default from Stripe to NetSuite. Additional fields can be mapped using Stripe metadata, or default values for NetSuite fields can be specified.

Stripe Field NetSuite Field
Stripe ID Entity ID & external ID
Email Email
Description Company Name (or first and last name)
Phone Phone
Shipping Address Default Shipping Address
Billing Address Default Billing Address

Note that NetSuite requires that the name of a customer is set. If no name is provided through the Stripe customer description field or using custom metadata fields, the integration uses the email address on the customer. If no email address is specified in Stripe, the Stripe customer ID is used.

Customizing NetSuite Customer Data

It's possible to customize fields on Stripe-created NetSuite customers. Checkout this example for more information

Multiple Currencies

If you accept payments in multiple currencies, all active NetSuite currencies will be added to any Stripe-created customers. Here's more details on how multi-currency transactions work with NetSuite.

Updating NetSuite Customer Data

By default, NetSuite customers are not updated after they are created. There is an option feature available to update NetSuite customer data on customer.updated or whenever a charge, invoice, order, or refund is created and associated with a given customer.

The main reason you wouldn't want to turn customer updates on is if the customer record is updated in NetSuite by other systems. Any updates made by other systems will be overwritten when the integration updates the Stripe record.

Note that if the external ID of a NetSuite customer does not match the Stripe Customer ID updates will not be pushed to the NetSuite customer.

The "Stripe Unallocated Charges" Customer

If a Stripe charge is not associated with a customer, the charge is associated with a single "catch all" Stripe-created NetSuite customer named "Stripe Unallocated Charges".

Many pre-built Stripe integrations only create a standalone charge in Stripe instead of creating a Stripe customer and then creating a charge from that customer.

Customer Balance

A customer's balance is not represented in NetSuite directly. If a invoice is partially or fully paid by a customers negative balance (i.e. think of it as a customer credit), a CreditMemo is created against the Invoice for the amount paid by the customer balance.

For example, switching to a lower cost plan results in a increase in the customer's balance, which is used to pay future subscription invoices. The Stripe customer balance can also be set at-will using the dashboard or the API.

For example, the NetSuite invoice below represents the following situation:

  • $10 customer balance from switching to a lower cost plan
  • $20 invoice was created, $10 of which was paid with the customer balance, the remaining $10 paid by their credit card.

NetSuite Invoice Partially Paid with Customer Balance

Here's the credit memo representing the customer balance:

NetSuite Credit Memo Representing the Stripe Customer

Note that if the customer balance is not used up on the first invoice created after downgrading a plan, the CreditMemo representing the customer balance will be represented by a "Stripe Customer Balance" item in NetSuite.

After the initial invoice is creating in Stripe, there is no way to determine what the customer balance represents (i.e. proration, arbitrary discount for the customer, etc). Because of this, we use this unique item to track usage of the customer balance in NetSuite.

There's an option available to use a unique item for all customer balance credits. This allows you to ensure all discounts given via customer balance post to a specific GL account and allows you to run reports by item and see a breakout of the usage of customer balance.

Billing & Shipping Address

If the shipping address is specified using the Stripe customer API it is added to the customer and set as the default shipping address. Here's an example of how to create a Stripe customer with a shipping address.

Here are fields that are pulled from the shipping field of the Stripe customer:

  • Phone
  • Address1
  • Address2
  • City
  • State
  • Zip
  • Country

You can also specify a billing address for the customer. This can be done by collecting billing address information along with the credit card data for a customer. Stripe Checkout can do this for you, or you can build your own billing address form. If any of these fields are set on a customer's payment source then a default billing address is created:

  • Address 1
  • City or Zip
  • State

Note that the country field is optional. If specified, it is pulled over to NetSuite. If it is not specified, then the default country of your NetSuite account is used.

Country fields on both the shipping field and the billing verification fields should either be specified as two character codes (ISO2) or full names conforming to the ISO-3166 standard.

Creating a Individual Customer

NetSuite has two types of customers: company and individual. If you are creating a individual customer, NetSuite requires both the first and last name. There are two ways to pass the name to NetSuite:

  1. Using the Stripe customer description field
  2. Passing the first and last name separately using metadata

Here's an example of passing the first and last name over using metadata:

Stripe::Customer.create(
  description: "Sample Customer",
  email: "customer@example.com",
  metadata: {
    netsuite_first_name: 'First',
    netsuite_last_name: 'Last'
  }
)

If you pass the full name in the description field, the full name is broken up into a first and last name. The first space in the description is used to "split" the full name into a first and last name.

For instance, "Elon Reeve Musk" turns into first name "Elon" and last name "Reeve Musk". The danger with this approach is "Sir. Richard Branson" turns into first name "Sir." and last name "Richard Branson". If you collect name prefixes, you should use the metadata approach detailed above.

Putting a NetSuite Customer on Credit Hold when a Stripe Charge Fails

If the customer credit hold feature is enabled in NetSuite, customers in NetSuite can automatically put on credit hold when a charging a customer's card in Stripe fails. Here are the two cases where a credit hold can be put on a customer:

  1. When a card associated with a subscription fails to charge the final time. The number of times that a card is attempted to be charged is dependent on your Stripe Subscription settings
  2. When a authorized charge fails to capture, and a new charge cannot be created, in the context of the auth-fulfill-capture flow.

Enabling the credit hold for one or both of these cases is optional. Here's how to test this feature.