Resolving Integration Errors

This page contains information on how to resolve common (and uncommon!) reconciliation errors. Reach out to support if you need additional assistance.

Here are some general thoughts to keep in mind when resolving errors:

• Many errors occur because of configuration changes in NetSuite. You may need to update your integration configuration and retry the translation to fix the issue.
• Some errors are most easily corrected manually. After manually correcting the problem, you'll can link the Stripe record to the NetSuite record using the internalId. Here's a guide to finding the internalId in NetSuite.
• You can set the internalId on a Stripe record programmatically using these metadata keys or manually using the Stripe dashboard.
• If no message is given, and manual resolution is not possible, reach out to support@suitesync.io.

Best Practices

The majority of the errors below can be avoided by following a simple set of best practices. Take a look, and feel free to reach out with any questions.

View Best Practices

General

What do the prefixes in the Stripe IDs represent?

• ch_ or py_ = a payment. Generally py_ represents a non-card payment.
• re_ = a refund
• dp_ = a dispute/chargeback
• po_ = a payout/batch payment
• in_ = a invoice
• cus_ = a customer

How can I re-run a transaction?

Use the "Manual Translation" area in the SuiteSync dashboard.

I'm getting an error that a transaction is "blocked". How do I fix this?

In most cases, this occurs when a sales order or invoice from your eCommerce integration (which is a separate system from SuiteSync) is "stuck" and doesn't come over to NetSuite. Generally working with your technical team to "unblock" the order in your integration tool (commonly Celigo, FarApp, or In8) is the easiest way to fix the issue.

Here's more technical information on other cases where this occur:

A "blocked" transaction occurs when the netsuite_block_integration metadata field is in place on a record, or any of its dependent records. It's also possible for a record to be blocked if "allowlisting" is enabled on your account (more info on that in the next section).

To fix this issue, simply remove the netsuite_block_integration field from the metadata on the Stripe record. You can do this using the Stripe dashboard, or by using the Stripe API.

If the issue still persists, a dependent record is blocked. For instance, if a subscription invoice is marked as blocked, you'll need to check both the customer and the charge for the netsuite_block_integration field. For each of the dependent records you'll need to add the netsuite_block_integration flag in order for all of the records to push through to NetSuite. For example, if a refund is blocked you'll need to ensure the charge and associated customer both have the netsuite_block_integration metadata field.

My integration just launched, my payouts are not matching my deposit amounts, and I'm seeing a "WARNING" notice in my deposits. Why?

If you used Stripe without SuiteSync, you could run into this problem if you refund (or receive a dispute) for an old transaction (i.e. a transaction handled before SuiteSync was in place). For example, if you issue a refund for a charge that was created before SuiteSync was in use, we didn't record the charge so we can't record the refund. In this case we "skip" the refund in the reconciliation, which causes the payout amount to be different from the deposit.

We can either send you a report of these "skipped" transactions so you can record them manually or include them automatically as a line item on the deposit.

Learn more about the manual work required.

This could also occur if SuiteSync support "forces" a payout through.

I'm seeing "Original Transaction Date" on my records. Why won't transactions post to the right period?

If there was a delay or error in pulling transactions over, it's possible that transactions will attempt to post to the previous transaction period. If you disallow transactions outside the current accounting period, this will cause an error.

To fix this, set the following setting to "Allow" (Setup > Accounting > Accounting Preferences)

A Stripe record is missing. How can I manually re-run a Stripe record?

In the SuiteSync dashboard, search for the Stripe transaction by it's ID and click the "Retry Translation" button.

Where can I find a Stripe refund ID for a charge

Under the charge in the dashboard, navigate to the "events" area and click on the event indicating that the charge is refunded. Then, search for a Stripe ID starting with re_.

NetSuite does not let me delete or unapply a CreditMemo once it has been applied. How do I fix this?

NetSuite does not make this easy, but it is possible. Here's how to unapply & delete a CreditMemo once it has been applied:

1. Open up the CustomerRefund record
2. Open up the associated CreditMemo in a new tab
3. Edit the CreditMemo. Navigate to "Apply" and uncheck the CustomerRefund it is applied to. Press save.
4. Edit the CreditMemo again. Navigate to "Actions > Delete".
5. Celebrate your victory!

I'm getting a notification that "transactions are already deposited". How do I fix this?

This error occurs if a transaction was accidentally deposited or the account on the transaction is not set to "Undeposited Funds". This prevents transactions from being included in the bank deposit (i.e. payout or batch payment) automatically created by the integration.

To fix this, you'll need to remove the transactions from the deposit they were incorrectly associated with.

Here's how to remove a transaction from a manual deposit:

1. Go to the SuiteSync dashboard and search for the transaction that you received a notification about.
2. In the SuiteSync dashboard, click on the customer refund, customer payment, cash sale, or customer deposit the transaction is associated with.
3. On the NetSuite record, search for the "Deposit ID" field. Then plug that ID into the global search and select the deposit by that name. If you don't see the "Deposit ID" field use this guide to install it.. In case you are confused, take a look at this video for a full walkthrough.
4. Remove the transactions reported by the integration as "already deposited" from this deposit record. You'll do this by editing the deposit, unchecking the transaction in the "Payments" list, and saving the deposit.
5. If the deposit (aka payout) is more than a month old, find the deposit in the SuiteSync dashboard and press the retry button. Transfers less than a month old are automatically retried within a couple hours.

If the transaction is a customer refund or cash sale, the account on the transaction needs to be set to "Undeposited Funds" (https://cl.ly/4c3daa02cc88). You can do this by editing the record and setting the account to undeposited funds. If the transaction is a payment, there is a "Undep Funds" checkbox that needs to be selected (https://cl.ly/7c6d8ea23e03).

SuiteSync never uses an account other than Undeposited Funds on any transactions it creates. Any time the account is set to something other than Undeposited Funds an action was taken by a person or system on your end. You'll want to dig into the system notes and figure out what process caused the account to change so you can prevent it from happening in the future.

I'm seeing a "Invalid record referenced in metadata key netsuite_credit_memo_id (123)" error

This can occur if a Stripe refund was linked to a CreditMemo that has since been deleted. The easiest way to fix this is to update the refund metadata key netsuite_credit_memo_id to point to the correct credit memo.

I'm seeing a "Customer is on credit hold." error. How do I fix this?

You may have NetSuite configured to disallow additional invoices on a customer if their open balance exceeds a certain amount. This will prevent SuiteSync from creating invoices against that customer for subscription invoices. To fix this issue you'll want to edit the customer and ensure they aren't put on a credit hold.

Alternatively, you can disable the credit hold feature in NetSuite:

Setup > Accounting > Preferences > Accounting Preferences > Accounts Receivable (subheader) > Customer Credit Limit Handling > Warn Only

If "Enforce Holds" is enabled this prevents transactions from being created on customers.

I'm seeing a "Invalid salesorder reference key 33928315 for customer 499557."

This error occurs when a CustomerDeposit cannot be created for a SalesOrder. There are many reasons why a customer deposit may not be able to be created for a SalesOrder:

• The SalesOrder is closed, cancelled, partially/completely fulfilled, or billed.
• The SalesOrder is pending approval. Depending on your account configuration, you may need to approve the sales order to create a deposit on the order. If the "Create Deposit" button does not exist on a unapproved sales order, then your NetSuite account does not allow deposits to be created unless they are approved.
• In some cases, if the SalesOrder was put on a payment hold and then released from the hold it's not possible to create a deposit against the SalesOrder. This is very rare.
• This could also occur if the custom form on the sales order creates invoices. Here's more information.

I'm seeing a "amount is not equal to the Stripe amount" error coming from SuiteSync. What is causing this?

This is caused if the amount of a payment, refund, or dispute in NetSuite does not match the amount of the corresponding record in NetSuite. This check is performed to ensure the accounting impact of transactions in Stripe matches the corresponding entry in NetSuite down to the penny.

Here's a couple reasons why this could occur:

1. Someone in NetSuite edited a payment or refund after it was created by SuiteSync
2. In rare cases, if a refund is issued and associated with a credit memo which does not have an unapplied balance then the customer refund amount will be incorrect.

Solution: edit the payment and correct the amount to match the amount in Stripe. If a refund is causing the issue, you'll need to create a new refund for the correct amount. In most cases, NetSuite doesn't let you edit the amount of a refund.

I'm getting a TRANS_UNBALNCD "Transaction was not in balance." error

https://help.avalara.com/Frequently_Asked_Questions/NetSuite_-Knowledge_Base/Why_am_I_getting%22Transaction_was_not_in_balance.%22_in_NetSuite%3F

I'm seeing a "Invalid paymentmethod reference key 7" error. How do I fix it?

This can occur if you've deleted or inactivated the "Stripe" payment method. To fix the issue, reactivate the "Stripe" payment method in your account.

I'm seeing a "Invalid account reference key 123 for subsidiary 2" error when creating a bank deposit?

This can often occur if an account's subsidiary does not match the subsidiary of the bank account chosen for deposits. To fix this problem, either change the subsidiary on the account or chose a different account.

For instance, in this example the account 123 is "inaccessible" to the subsidiary associated with the account. In other words, the subsidiary associated with the account is not associated with the subsidiary associated with the bank. This is a NetSuite requirement. For example, in the screenshot below the subsidiaries do not match, which would cause this error.

It's also possible that the account is either disabled or a non-posting summary account. Both of these cases are much more rare, but if the subsidiary looks correct, you'll want to check this as well. This error is very similar to this error.

I'm seeing a "Invalid item reference key 123 for subsidiary 7" error when creating an invoice or order.

This error occurs if item 123 is inaccessible to the subsidiary associated with the customer of the invoice or order. NetSuite considers an item "inaccessible" if it the item is not associated with the subsidiary directly, or if the customer subsidiary is not a child of a parent subsidiary which the item is associated with.

This could also occur if there is not a income account set on the item record.

Solution: change the subsidiary associated with the item. The easiest solution is to pick the parent subsidiary and ensure "Include Children" is checked.

Here's an example:

I'm seeing a "Invalid item reference key 123" error when creating an invoice or order

This indicates that the income account for the item is not set:

This could also indicate that the item has been marked as inactive.

I'm seeing a "Invalid currency reference key 4 for customer 123."

This occurs if the currency of the Stripe payment is not available on the "Currencies" list of the customer. NetSuite doesn't allow you to create a payment in a currency that hasn't been "assigned" to a user.

Solution: add the missing currency to the customer with the internal ID indicated in the error message. Note that in some cases, SuiteSync can add currencies to the customer for you. Contact support to enable this feature on your account.

Add the currency to the user and press retry to fix the issue.

If you are using the subscription integration, this should never occur; contact support to resolve the issue. If you are using another integration (Celigo, Jitterbit, etc) in conjunction with SuiteSync that integration needs to ensure the correct currencies are added to the customer.

I accidentally included Stripe transactions in a manual bank deposit and now my deposits won't reconcile. How can I fix this?

Just remove the Stripe transactions from the manual deposit that you created. The integration automatically retries bank deposits: within a couple hours of removing the Stripe transactions from the manual deposit the integration creates a bank deposit automatically.

You can determine which deposit a payment or refund is associated with by looking at the "Deposit ID" field. If this field does not exist, reach out to support so we can add this to your account.

I'm getting a "Unable to find a matching line for sublist apply with key: [doc,line] and value: [4629556,null]"

In the case of a payment, this can occur if the Invoice that the CustomerPayment is applied does not have an "Amount Remaining" which is greater than or equal to the amount of the CustomerPayment. In this case, the internal ID of the Invoice that the payment is attempting to be applied to is 4629556. Solution: modify the invoice to have an "Amount Remaining" that is greater than or equal to the payment amount.

In the case of a refund, this can occur if the unapplied amount of the CreditMemo is less than the amount of the refund. Solution: modify the CreditMemo to have an unapplied amount equal or greater than the Stripe refund.

In the case of a refund for an unapplied payment, this can occur if there is no credit memo associated with the refund and the payment that is being refunded is partially applied. If the unapplied amount of the payment is less than the amount of the refund this error occurs. Solution: reduce the amount of the payment that is applied to be less than the refund amount.

I'm getting a "Unable to find a matching line for sublist deposit with key: [doc,line] and value: [123,null]." error

In the case of a refund, this can occur if the CreditMemo that the CustomerRefund is applied to is:

• Not "Open". If the CreditMemo is already applied to another Invoice or CustomerRefund this error is triggered. Solution: unapply the credit memo.
• Not associated with the same customer as the original payment. Solution: change the customer on the CreditMemo to match the customer of the original transaction.

Transfers (Deposits)

I see a "Deposit does not match Stripe transfer amount" in my deposit memo. Why?

This will only happen if support pulls over transfers and skips the validation process. If you have been using Stripe for some time, this will occur because some transactions will reference Stripe invoices, charges, etc which were created before go-live.

What does the error "Required field missing in a related list. You must set lineId." indicate?

This error occurs when you've run into a NetSuite bug in the deposit creation process. If you are attempting to deposit transactions that can't be "seen" in the "Make Deposit" GUI (for instance, if you have more than 10,000 items in the undeposited transaction list).

To fix the issue:

• Make sure all filters are disabled/cleared from the "Make Deposits" screen on the user's account being used for the integration (shown below).
• Clear out non-Stripe transactions from the payment list. The easiest way to do this is to create a deposit record containing these transactions. On the "Make Deposit" page you can click the checkbox underneath the "Customize" button and then save the deposit. This "clears out" all of the transactions currently waiting to be deposited. Make sure you don't deposit any transactions automatically created by SuiteSync; you can ensure these are excluded by using a "Payment Method" filter on the "Make Deposits" screen.

Note that this may not fix the issue. Contact support if this does not resolve the error. Also, contact support if you'd like to report this NetSuite bug to your NetSuite support contact.

How do I fix "Invalid customer reference key 3323."?

This error is occurring because the Stripe customer is associated with a NetSuite customer that has been deleted, merged, or marked as inactive.

Solution: If the customer has been deleted to merged, manually link the Stripe customer with the correct NetSuite customer using the Stripe metadata.

If the customer has been marked as inactive, simply re-activate the customer.

How do I fix refunds whose account is not set to "Undeposited Funds"?

In order for a customer refund to be reconcilied to a payout, the account of the customer refund must be set to “Undeposited Funds”. In some NetSuite accounts, this account is named “Deposits in Transit”.

Here’s an example:

When SuiteSync creates a customer refund we automatically set the refund to post to this account. However, it’s possible for another NetSuite user to accidentally modify the refund and set the account to a different value.

To fix:

1. Pull up the refund in NetSuite.
2. Edit the Refund
3. Change the account to "Undeposited Funds"
4. Click Save

If this is a common occurrence, contact support. There are scripts that can be installed in your NetSuite account to prevent this from occurring.

How can I determine which records were deleted in NetSuite?

It's important that records created by the integration are not deleted. If they are deleted, you'll run into reconciliation issues: the integration notices a record is missing and asks you to correct the error before the automatic cash reconciliation process is completed.

NetSuite maintains a audit trail of all transactions that were deleted. This deleted records log is hidden under the "View Audit Trail" page.

Here's how to use it:

• You'll want to select the "Delete" option under the "Action" area
• Pick the transaction type(s) you'd like to inspect

NetSuite returns a list of deleted records indicated which user deleted the record and when.

Stripe charges and refunds in the payment list is making it hard to reconcile other undeposited payments. What should I do?

All payments and refunds in NetSuite are associated with a special payment method called "Stripe". You can select payments from other payment methods to filter out Stripe transactions.

Here's how to add this filter:

1. On the make deposits screen click the "Customize" button on the payments Deposits > Payments tab.
2. Navigate to the "Additional Filters" tab and enable the "Payment Method" filter
3. Press Save

The "Make Deposit" page should look like this:

Deposit Reconciliation-only Flow

It's possible to use SuiteSync just for automatic deposit reconciliation. This is useful if you have a custom integration in place, but still want to eliminate manual reconciliation work.

Charge, refund, or dispute failed to translate

In the reconciliation-only flow, this error indicates that Stripe records are not linked to a corresponding NetSuite record. To fix this problem, add a link to the corresponding record using Stripe metadata.

You can add a link to the corresponding NetSuite records by:

1. Using the "Manually Link Record" SuiteSync dashboard feature. This works for all records.
2. Using the Stripe Dashboard. Note that this will not work for refunds and disputes.
3. Using the API. This works for all records.

For charges, we look for the following metadata keys:

• netsuite_customer_payment_id
• netsuite_customer_deposit_id
• netsuite_cash_sale_id

For refunds, we look for the following metadata keys:

• netsuite_customer_refund_id
• netsuite_cash_refund_id

Here's an example of how to link a charge using the API:

require 'stripe'

ns_customer_payment_id = 123

stripe_charge = Stripe::Charge.retrieve('ch_123')
stripe_charge.metadata['netsuite_customer_payment_id'] = ns_customer_payment_id
stripe_charge.save

Transactions are linked to multiple NetSuite records

For charges, refunds, and disputes we check to ensure multiple NetSuite records are not linked through Stripe metadata.

To fix this problem, just remove the duplicate NetSuite reference in the Stripe metadata and this problem will be fixed.

A transaction is not linked to the correct subsidiary, or is linked to a subsidiary that is different from your deposit account.

NetSuite requires that customer's subsidiary is the same subsidiary as the bank deposit account. This is the account that batch deposits from Stripe are sent to. For example, if you have a US and UK subsidiary, NetSuite does not allow you to deposit a transaction on the UK subsidiary into a bank account under the US subsidiary.

To determine which subsidiary is associated with an account, navigate to your chart of accounts (global search for page: accounts) and click "Edit" on the account in question. Then, on the account page, you'll be able to see the subsidiary chosen for the account.

In most cases, you'll need create a new one and ensure that the subsidiary matches the customer subsidiary. Once a bank account has a subsidiary selected and has been used in at least one locked accounting period, the subsidiary associated with the account cannot be changed.

If the bank account subsidiary is correct, then check if customer must be associated with the incorrect subsidiary. You can check the customer's subsidiary by taking a look at the customer record in NetSuite. If the customer's subsidiary is incorrect, there is not a way to correct it in NetSuite. You'll need to recreate a new customer in NetSuite associated with the correct subsidiary.

If the bank account subsidiary and the customer subsidiary match, check if the currency of the NetSuite bank account matches the currency of the payout in Stripe. The currency of the bank account in NetSuite must match the currency of the payout Stripe in order to create a deposit in NetSuite.

Alternatively, SuiteSync support can "exclude" the transactions that were created under the wrong subsidiary from the payout reconciliation. However, this will not fix the issue going forward: it's important that you work with SuiteSync support to ensure that payments are created under the correct subsidiary.

If that doesn't work, contact support.

eCommerce and Auth-Fulfill-Capture

A charge was accidentally captured using the dashboard

If you are using the auth-fulfill-capture workflow, charges should only be captured by SuiteSync when the SalesOrder is billed (i.e. an Invoice is created).

If a charge was accidentally captured using the Stripe dashboard, the charge will be a unapplied payment in NetSuite. In order to fix this issue, you'll need to do two things:

1. Apply the payment to the correct invoice in NetSuite
2. Link the charge in Stripe to the correct NetSuite invoice. You do this by adding the netsuite_invoice_id metadata field to the Stripe Charge. The value of this field is the internal ID of the invoice (here's how to find the internal ID)

If these steps are not taken, and if the refund is requested by a CreditMemo in NetSuite, it's possible that the refund will not be created.

I can't change the customer associated with an invoice

After a payment is deposited the customer on the payment cannot be edited. This is a NetSuite limitation: after a payment is deposited the payment is "locked". You'll see a lock icon on the record when this is the case.

The only way to change the customer on a transaction that has been deposited is to undeposit the transaction, edit the transaction, and then re-deposit the transaction.

A customer has an invoice in NetSuite but the payment did not get applied to the NetSuite Invoice. How could this happen?

• If you are using the auth-fulfill-capture flow, if another person or system captured the charge it will come over immediately as an unapplied payment. You can figure out if this is the case by looking at the "Events" area in the Stripe Dashboard for a charge, clicking on the captured event, and then clicking on the "Source". You'll then be brought to a request viewer and will be able to see what system triggered the capture.
• If you are using custom eCommerce flow, it's possible that the netsuite_block_integration metadata field was incorrectly removed by a system or by someone using the Stripe Dashboard.

In order to fix this issue, use the same process as identified in "A charge was accidentally captured using the dashboard".

I'm seeing "Deposit could not be applied to the order XYZ" on my customer deposit records. How can I stop this from happening?

This occurs if NetSuite does not allow a customer deposit to be created for a sales order. You can determine if this is the case, by looking at the sales order in NetSuite: if you don't see a "Create Deposit" button on the sales order, then NetSuite will not allow a customer deposit to be created.

For instance, if a sales order is closed, cancelled, or already billed NetSuite does not allow a customer deposit to be attached to the sales order. Some custom transaction forms also prevent a deposit from being created. If SuiteSync detects that a sales order is in this state, it creates the customer deposit and adds the memo Deposit could not be applied to the order to the deposit.

You can view all of these deposits by using the "Stripe Duplicate Invoice Payments" saved search.

Here's how to force your sales orders to create invoices instead of cash sales.

If this occurs on your account, you may need to resolve these manually. To do this, you'll need to manually apply each customer deposit to the correct invoice.

I'm getting an error CUST_LEAD_NOT_GROUP_MEMBR indicating that "this customer or lead does not belong to your group."

The role that the integration is using to connect to your NetSuite account does not have access to the subsidiary that the integration is attempting to create a customer under. To solve the issue, add more subsidiaries to the role you are creating.

I'm getting an error "More than one avalara line item encountered!"

This error happens due to a bug or configuration error with your tax integration (most likely Avalara). NetSuite does not allow for multiple lines of tax invoices, so this invoice and charge will fail to sync until this is resolved. There a few different ways to resolve this error depending on the scope of the issue.

1. If there are only a handful of invoices:

The quickest way to resolve this is to manually creating the invoice(s) in NetSuite. Then use the "Manual Resolution" tool in the the Stripe Connector for    NetSuite (SCN or SuiteSync) dashboard to link the Stripe invoice and newly created NetSuite invoice. The NetSuite invoice will need to be the same amount as the Stripe invoice. Once the invoices are linked, the SCN (SuiteSync) integration will be able to sync the payment record.

2. If there is a large number of invoices where the tax amount is $0.00

You can use a script to update the metadata on the Stripe invoice line items and remove the "Is_AvaTax_Line" line item. If it's a zero-dollar line item, this won't cause an issue and allow the invoice and charges to be created. 

3. If there is a large number of invoices where the tax amount is more than $0.00

3a. You can use a script to update the metadata on the Stripe invoice line items and remove the "Is_AvaTax_Line" line item. 
3b. Since the line item has an amount you will also need to set a NetSuite item ID on the Stripe invoice line item so the amount gets directed to the right place in NetSuite. You could direct it to a special NetSuite item with a specific account if you plan to refund this additional tax line. 

Lastly,reach out to your tax integrator

Regardless of the size of the issue, you will want to reach out to your tex integrator to ensure this is not a more widespread configuration issue or ongoing bug. The Stripe Connector for NetSuite (SCN or SuiteSync) will never add additional tax lines to your invoice, and is controlled by your tax integration.