Stripe NetSuite Integration Customization

If you have existing integrations you'd like to continue using, or if you want to provide existing records in NetSuite to the integration, you can use the guide below to help know how to integrate your existing systems or records with the integration.

Using existing records or integrations

You can override any part of the integration by providing the internal ID of an existing NetSuite record to the Stripe record using metadata.

Here's an example of how you would provide an existing customer ID to Stripe.

Controlling when records are created in NetSuite

It's possible to control when a record is translated to NetSuite. Here are two options:

• Add a netsuite_block_integration metadata field to "denylist" a Stripe record to prevent the record from being translated to NetSuite. When the Stripe record is ready to be translated to NetSuite, just remove the metadata field.
• Prevent all data from being translated to NetSuite by default. You can then "allowlist" records by adding the netsuite_allow_integration metadata field. With this feature enabled, only when a record is "allowlisted" in Stripe will the integration push it through to NetSuite.

For example, here's how to prevent a charge from being created in NetSuite:

Stripe::Charge.create(
  amount: 10_00,
  currency: 'usd',
  customer: 'cus_123',

  metadata: {
    netsuite_block_integration: true
  }
)

Later on, remove the metadata field to create the record in NetSuite:

stripe_charge.metadata['netsuite_block_integration'] = nil
stripe_charge.save

Alternatively, here's how to "allowlist" a record in order to instruct the integration to push the record through to NetSuite:

charge = Stripe::Charge.retrieve('ch_123')
charge.metadata['netsuite_allow_integration'] = true
charge.save

Both of these features are optional and are disabled by default. There is also an additional option to control data flow into NetSuite: blocking all payments that are not associated with an order, invoice, or cash sale. This is helpful if you don't want to use the allowlist or denylist flags, but want to ensure unapplied payments don't get pushed through to NetSuite.

An example of when this feature is useful is if you have an eCommerce application (Shopify, Magento, etc) and Stripe Billing/Subscriptions running out of the same Stripe account. In this case, you want the payments from your eCommerce application to be associated with your NetSuite orders, but you don't want to have to write code to allowlist the invoices & payments being automatically generated by your integration with Stripe Billing. In this scenario, blocking all payments without an associated NetSuite transaction works very well: subscription invoices & payments will come through automatically, and the eCommerce payments without a order will "wait" until the associated order or invoice is imported into your NetSuite account.

Note that invoices cannot be allowlisted, but they can be denylisted. This is because, under most circumstances, invoices are generated automatically by Stripe. This makes it challenging to ensure invoices are allowlisted.

Field customization

NetSuite records can be customized system-wide or dynamically (on a per-record basis)

For example:

• System-wide: you can specify a single subsidiary to use for all Stripe-created NetSuite customers.
• Dynamically: specify a customer's subsidiary through a Stripe metadata field like netsuite_subsidiary_id.

Field Types

There are multiple field types in NetSuite: date, number, free-form type, drop-downs, etc. For each of these field types, the corresponding Stripe metadata field value needs to be specified slightly differently:

• For reference or drop-down fields, the metadata value needs to be an integer representing the internal ID of the reference or drop-down option you'd like to use. For instance, if you'd like to specify the class for a payment or refund you'll want to use a metadata field like netsuite_class_id with a value of 123 referencing the internal ID of the class you'd like to use.
• For dates, the value must be an integer representing the GMT0 Unix timestamp of the date you'd like to use. For instance, if you want to set the "Due Date" on an invoice to "Feb 1st 2018" you could set a netsuite_due_date metadata field to 1517443200 which is the timestamp representing Feb 1st 2018.

Note that in the examples provided the netsuite_ prefix is used. Using this prefix is not a hard requirement; any metadata field can be used for mapping to NetSuite. It is highly recommended to use netsuite_ to differentiate which metadata fields are used for the integration.

A Note on Naming NetSuite Fields

When choosing the name of your NetSuite custom fields that you are planning on using with your integration, it's important that you don't end the internalID of those field names with either _date or _id. These are 'special' suffixes that point to specific field types (list fields and date fields, respectively). We recommend removing the underscore from these suffixes when naming your fields. For example, instead of custbody_activation_date use custbody_activationdate.

System-wide customization

You can specify system-wide NetSuite field values for all Stripe-created NetSuite records. In most cases, system-wide values for sublist item fields can be configured.

Here are some examples:

• Specify "Web Sales" as the NetSuite customer category for all Stripe-created records
• Use a specific department, class, or location on the line items of Stripe-created invoices

Dynamic (per-record) customization

Here's how to setup dynamic customization:

1. Set the value on the Stripe metadata using a consistent key.
2. Contact support to configure the mapping between the Stripe metadata field and the target NetSuite field.

For example:

Stripe::Customer.create(
  description: "First Last",
  metadata:  {
    netsuite_home_phone:  '123-456-7890',
    netsuite_sales_rep_id: 123
  }
)

Metadata from Related Objects

In example above, the netsuite_home_phone could be mapped to the NetSuite customer's phone field. However, you aren't limited to pulling metadata from a single object. You can pull metadata from any object that has a one-to-one relationship with the object you are mapping.

For example, let's say you create a charge connected to the customer created in the previous example:

Stripe::Charge.create(
  description: "A great charge",
  customer: customer.id,
  metadata: {
    netsuite_user_id: 123
  }
)

A customer payment in NetSuite is created from this charge. When that customer payment is created, we can pull both the netsuite_user_id on the charge and netsuite_sales_rep_id metadata on the customer into the NetSuite customer payment.

Overriding system-wide customization

Dynamic customization overwrites system-wide customization. This behavior enables system-wide "defaults" to be overwritten if additional data is provided using Stripe metadata.