PlentyONE Read-Only Integration Guide

Connect your PlentyONE system to Kintsugi

Updated 5 days ago

The PlentyONE read-only integration securely syncs your PlentyONE order data with Kintsugi for reporting, nexus tracking, and filing preparation.

PlentyONE (formerly plentymarkets) runs your catalog, orders, customers, and sales channels from one backend. Kintsugi reads from a single PlentyONE system and imports your own shop and manual orders. Marketplace orders from channels such as Amazon, eBay, and OTTO are skipped by default, and you can choose to import them when you connect.

This integration gives you visibility into your sales activity without changing how tax works in your store. It does not calculate tax at checkout and does not send tax rates back to PlentyONE.

No plugin required. You do not need to buy, install, or deploy anything from plentyMarketplace. The connection uses the PlentyONE REST API with a dedicated API user that you create.

What the Read-Only Integration Does

Once connected, Kintsugi will:

Sync your paid own shop and manual sales orders, including line items, discounts, and shipping
Sync credit notes and link them to the original sale
Sync the customers and companies on those orders, including VAT ID or tax ID where present
Sync the products that appear on those orders
Sync billing and shipping addresses
Monitor your sales activity against nexus thresholds
Generate reports and prepare filings based on the synced data

What It Does Not Do

This integration will not:

Calculate or apply tax at checkout in PlentyONE
Write tax or VAT rates back into your PlentyONE system
Override your PlentyONE tax settings
Import marketplace orders, unless you choose Import and mark as marketplace when you connect
Import goods returns
Import your full customer list or your full product catalog. Only the customers and products that appear on synced orders are brought across.

You will need to configure tax collection directly within PlentyONE.

Before You Start

Make sure you have the following ready:

Administrator access to your PlentyONE backend (Terra)
Your system ID. Take it from your Terra URL.
For example, if your URL is https://p75180.my.plentysystems.com, your system ID is p75180.
Country and postal code saved on your Kintsugi organization. If either is missing, Kintsugi asks you to complete your business address before the connection form opens.

Do not use your PlentyONE website login. Website and Terra user logins will not work with this integration. In Step 2 you will create a dedicated Only API user, and that is the account Kintsugi signs in with.

Using a German-language Terra? Orders appears as Aufträge and Items appears as Artikel.

Step 1: Create a Role with Read Rights in PlentyONE

REST API rights are switched off until a role grants them, so create the role first.

In Terra, go to Setup » Account management » Roles.
Click New and give the role a name, for example Kintsugi Read.
Switch to the Advanced view.
Tick Read on Orders, CRM, and Items. Leave Create, Update, and Delete unticked.
Under Access rights, set Clients to All, and make sure your visible order statuses include your paid statuses. If paid orders are hidden from this role, Kintsugi cannot see them.
Click Save.

Do not grant authorisation or user management rights. Kintsugi does not need them.

Step 2: Create the Only API User

Use New, not Invite new user. Invite creates a website account, which will not work here.

Go to Setup » Account management » Accounts.
Click New.
User name: at least 5 characters with no spaces. This is the value you will enter as Username in Kintsugi.
Name: any display name.
Email: used for PlentyONE notifications only. Do not enter this as your Kintsugi username.
Password and Repeat password: choose a password and store it somewhere safe. PlentyONE does not generate one for you, and Terra will not show it again after you save.
User accounts access: select Only API user.
Assigned roles: select the role you created in Step 1.
Click Save.

This user cannot sign in to Terra. That is expected. To change its password later, open the account as an Administrator, enter a new password under Login data, save, then update the password in Kintsugi.

Step 3: Connect PlentyONE in Kintsugi

Sign in to your Kintsugi account.
Go to Data Sources.
Find the PlentyONE card then click Connect.

In the Connect PlentyONE window, complete the fields below.

Field	What to enter
System ID or host	Your system ID, for example p75180. You can also paste p75180.my.plentysystems.com or the full REST URL. This field is locked after you connect.
Username	The User name of the Only API user from Step 2. Not your email address, and not your Terra login.
Password	The password you set on that Only API user.
Sync from(optional)	Only import orders created on or after this date. Leave blank to import all history.

Once your system ID, username, and password are filled in, click Connect.

Sync from is optional, and Marketplace orders is already set to Skip unless you change it.

You do not need an API token. Kintsugi signs in to PlentyONE with the username and password you enter. Do not paste a token into this form.

You will see a confirmation message once the connection is created, and syncing begins right away.

Step 4: Initial Sync

Kintsugi begins importing your order data as soon as you connect. The first import covers everything from your Sync from date, or your full history if you left that blank. How long this takes depends on your order volume. You can monitor progress from the Data Sources page, where the card shows your PlentyONE system.

Step 5: Complete Your Dashboard's Pending Tasks

Once the first sync finishes, verify your integration data:

Products. Kintsugi AI automatically assigns categories and subcategories to your products, but you must review and approve them, because not all products are taxed the same. See Updating Product Category and Subcategory. You can also set a default for newly synced products: How to Set a Default Product Classification.
Invalid and blank addresses. Tax is often assessed on the ship-to address, so address accuracy matters. See How to Update Invalid Addresses in the Kintsugi App and How to Update Blank Addresses in the Kintsugi App.
Transactions, customers, and products. Confirm these are visible in your Kintsugi dashboard.

You are all set. Kintsugi will begin monitoring your synced sales against the registration and reporting thresholds that apply to you, and flagging where you have exposure.

What to Expect After Connecting

PlentyONE handles sales, returns, and credit notes as separate document types, so it helps to know what comes across and what does not.

What you see in PlentyONE	What happens in Kintsugi
A paid order from your own shop, or a manual order	Imported as a transaction with its line items.
An order from a marketplace channel such as Amazon, eBay, or OTTO	Not imported, because Marketplace orders is set to Skip by default. Choose Import and mark as marketplace when you connect, or later under Edit, to bring them in flagged as marketplace.
An order that is not yet paid	Not imported. Once it is paid in PlentyONE, a later sync picks it up if the order was created inside the sync window. If Sync from is empty, that window is the last 90 days. If Sync from is set, it is from that date through today.
A goods return	Not imported. Returns move stock, not money, so they are not a tax document. This is expected behaviour, not a sync failure.
A credit note	Imported as a credit memo and linked to the original sale. If the original sale is still unpaid, the credit note waits until that sale is paid. If the original sale is paid in PlentyONE but not yet in Kintsugi, Kintsugi fetches the sale first and then imports the credit note. If PlentyONE has no original sale recorded, the credit note imports on its own, unlinked.
A cancelled order that already has a credit note	Not marked as cancelled in Kintsugi. The credit note already reverses the money, so cancelling as well would double count the reversal.
The VAT stored on your PlentyONE order	Kept for reference. Kintsugi calculates its own tax from the imported amounts rather than copying the stored VAT.

How later syncs pick up orders. After the first import, each sync looks at orders created in the last 90 days. An order created outside that window is not revisited, even if it changes in PlentyONE. If you need older orders brought in, contact Kintsugi support.

Managing the Integration

On the Data Sources page, click the three dots on your PlentyONE card to open the menu.

Option	What it does
Edit	Update your username, password, Sync from date, or Marketplace orders setting. Your system ID cannot be changed after connecting.
Sync	Start a sync now. It looks at the same orders as the automatic sync. If Sync from is empty, later syncs only include orders created in the last 90 days. The first sync still brought in older paid orders. If you set Sync from, every sync brings in order created on or after that date, up to today.
Deactivate	Stop future syncs. Historical data already synced to Kintsugi is not deleted.

Once deactivated, the menu offers Re-authorize, Activate, and Archive instead.

Connecting more than one PlentyONE system? Kintsugi uses one connection per PlentyONE system. To add another system, connect it separately with its own system ID. Click Connect Another to proceed.

Troubleshooting

What you see	What it usually means	What to do
PlentyONE did not accept this login	The login is wrong. This is often a website login, a Terra login, an email used as the username, a wrong password, or a locked user.	Use an Only API user. Enter its User name, not its email. If you are not sure of the password, reset it as an Administrator. So not keep retrying. That can lock the user. If it is locked, wait, or create a new Only API user.
PlentyONE is busy, try again in a moment	Too many tools are signed in with this API user at the same time.	Wait. Sign other tools out of this user. Then try again.
Failed to connect, please try again	The connection failed for a network or other unexpected reason.	Try once more. If it still fails, contact Kintsugi support. Send your system ID and the time it failed.
Could not find PlentyONE system ID (p{PID}) in the hose	The value is not a PlentyONE system address.	Use the address from your Terra URL, for example p75180. Do not use your shop website or an email domain.
You are asked for a business address instead of the connection form	Your Kintsugi organization is missing a country or postal code	Complete the address prompt, then connect.
The connection works but few or no orders appear	Marketplace orders are being skipped, unpaid orders are skipped, or the role cannot see your clients or paid statuses	If the missing orders came from Amazon, eBay, or OTTO, check your Marketplace orders setting under Edit. Otherwise check whether the orders are marked as paid in PlentyONE, then check that the role has Clients set to All and that your paid statuses are visible to it.
Paid orders are still missing	The orders are from a marketplace, Sync from is after the date the order was created, the order is older than 90 days and Sync from is empty, or the role cannot see them	Open Edit. Check Marketplace orders and Sync from. Then check the role from Step 1. If Sync from is empty, an order older than 90 days is imported only if it was already paid on the first sync. If it was paid later, contact Kintsugi support.
A credit note has not appeared	Its original sale is still unpaid in PlentyONE	Expected. The credit note imports once the original sale is paid. If the sale is already paid but the credit note is still missing, contact Kintsugi support.
A return has not appeared	Goods returns are not imported	Expected. See What to Expect After Connecting above.
Your API user cannot sign in to Terra	Only API users have no Terra access	Expected. Use your Administrator account to edit that user.

If your connection works, your Marketplace orders setting and Sync from date do not exclude the orders you expect, your role can see paid orders in PlentyONE, and those orders still never appear, contact Kintsugi support.

How Tax Works with this Integration

This connection only reads orders into Kintsugi. It does not calculate tax in PlentyONE, and it does not send tax back to the shop. Set tax in PlentyONE. Kintsugi uses the imported orders for nexus, reports, and filing.

Need Help?

For further concerns, we are always here to help. If you cannot find the answer you are looking for, please reach out to us using the chat bubble in the bottom right corner.

Was this article helpful?