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.

Stripe Record Stripe Metadata Key NetSuite Record
Customer netsuite_customer_id Customer
Invoice netsuite_invoice_id Invoice
Plan netsuite_service_sale_item_id Service Sale Item.
Plan netsuite_service_resale_item_id Service Resale Item. This item type can be used in place of a Service Sale Item.
Plan netsuite_non_inventory_sale_item_id Non Inventory Sale Item. This item type can be used in place of a Service Sale Item.
Plan netsuite_non_inventory_resale_item_id Non Inventory Resale Item. This item type can be used in place of a Service Sale Item.
Plan netsuite_discount_item_id Discount Item. Only applicable
Invoice Line Item netsuite_service_sale_item_id Service Sale Item. Only applicable if the line item is a non-plan item, otherwise the plan's NetSuite item is used. Any alternative item types available on Plan can be used here as well.
Invoice Line Item netsuite_discount_item_id Discount Item. Only applicable if the line item amount is negative.
Coupon netsuite_discount_item_id Discount Item
Charge netsuite_customer_payment_id Customer Payment
Charge netsuite_cash_sale_id Cash Sale
Charge netsuite_customer_deposit_id Customer Deposit
Refund netsuite_customer_refund_id Customer Refund
Refund netsuite_credit_memo_id Credit Memo. Only applicable if the refund's charge is linked to a Stripe-created invoice.
Refund netsuite_cash_refund_id Cash Refund
Dispute (Chargeback) netsuite_customer_refund_id Customer Refund
Dispute (Chargeback) netsuite_cash_refund_id Cash Refund
Transfer netsuite_deposit_id Deposit

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 a Stripe record to prevent the record from being translated to NetSuite. When the Stripe record is read to be translated to NetSuite, just removed the metadata field.
  • Prevent all data from being translated to NetSuite by default. You can then whitelist records to be pushed to NetSuite by adding the netsuite_allow_integration metadata field.

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

Remove the metadata field to create the record in NetSuite:

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

Both of these features are optional and are disabled by default.

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.

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

There are multiple field types in NetSuite. 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 dates, the value must be an integer representing the GMT0 Unix timestamp of the date you'd like to use.

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 NetSutie. It is highly recommended to use netsuite_ to differentiate which metadata fields are used for the integration.

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.