Customers


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

Here's how this integration works:

  • 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.
  • By default, customers are always created as company customers. This can be customized on a global or per-record basis.
  • Phone, email, and address is also translated over if specified on the Stripe customer.
  • If provided, the billing address is pulled into NetSuite
  • Any additional standard or custom fields can be specified using metadata

Using Existing Customers

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
  }
)

Alternatively, SuiteSync also supports automatically linking Stripe customers to existing NetSuite customers by email address.

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.

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.

The "Stripe Unallocated Charges" Customer

If a Stripe charge is not associated with a customer, it will be associated with a single 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.