Resolving Integration Errors
This documentation is a work in progress. Don't hesitate to reach out to support if something is missing or incomplete.
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.
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?
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.
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 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.
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 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
It looks like a customer was associated with a subsidiary which is not the child of the subsidiary associated with the bank account deposits post to.
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, if the refund is requested by a CreditMemo in NetSuite it's possible that the refund will not be created.
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".