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

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".

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.

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

If the following fields are available 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 will be pulled over to NetSuite. If it is not specified, then the default country of your NetSuite account will be 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: using the Stripe customer description field, or passing the first and last name separately through the 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 will broken up into a first and last name.

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.