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 firstname.lastname@example.org.
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.
What do the prefixes in the Stripe IDs represent?
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 "whitelisting" 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
My integration just launched, and I'm seeing a "WARNING" notice in my deposits. Why?
If you were using Stripe without SuiteSync there is manual reconciliation work required the first couple months to handle transactions created before SuiteSync was integrating data into NetSuite.
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
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:
- Open up the CustomerRefund record
- Open up the associated CreditMemo in a new tab
- Edit the CreditMemo. Navigate to "Apply" and uncheck the CustomerRefund it is applied to. Press save.
- Edit the CreditMemo again. Navigate to "Actions > Delete".
- Celebrate your victory!
I'm getting a notification that "transactions are already deposited". How do I fix this?
This error occurs if transactions which are managed by the integration are manually deposited in NetSuite. This prevents transactions from being included in the bank deposit automatically created by the integration.
To fix this, you'll need to remove the transactions from the deposit they were incorrectly associated with.
- Go to the SuiteSync dashboard and search for the transaction that you received a notification about.
- In the SuiteSync dashboard, click on the CustomerRefund, CustomerPayment, CashSale, or CustomerRefund the transaction is associated with.
- 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.
- Remove the transactions reported by the integration as "already deposited" from this deposit record.
- 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 will be automatically retried within a couple hours.
If you don't see the "Deposit ID" field, use this guide to install it.
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 "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.
- 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.
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 processing or dispute 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.
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.
- Pull up the refund in NetSuite.
- Edit the Refund
- Change the account to "Undeposited Funds"
- 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:
- On the make deposits screen click the "Customize" button on the payments Deposits > Payments tab.
- Navigate to the "Additional Filters" tab and enable the "Payment Method" filter
- 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:
- Using the "Manually Link Record" SuiteSync dashboard feature. This works for all records.
- Using the Stripe Dashboard. Note that this will not work for refunds and disputes.
- Using the API. This works for all records.
For charges, we look for the following metadata keys:
For refunds, we look for the following metadata keys:
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 the 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 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:
- Apply the payment to the correct invoice in NetSuite
- Link the charge in Stripe to the correct NetSuite invoice. You do this by adding the
netsuite_invoice_idmetadata 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_integrationmetadata 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".