TradeMate (B2B) Returns | ReturnMate Help Centre

TradeMate is MateHQ's B2B trade platform. The TradeMate integration lets you run returns for B2B trade orders through the same RMA workflow you use for Shopify orders — with resolutions (account credits, credit notes and free replacement orders) pushed back to TradeMate as the financial system of record.

TradeMate account required

This integration requires an active TradeMate tenant. Trade returns are separate from Shopify returns — no Shopify order or refund is involved at any point.

Overview

With the integration enabled:

Staff can create trade returns from the admin by looking up a TradeMate order.
Trade customers can be redirected from a TradeMate portal straight into your ReturnMate returns portal with their order pre-filled.
TradeMate (or any system integrated with it) can create trade returns via the External API.
Trade RMAs are flagged with a TradeMate badge on the RMA list and detail page, and follow the standard returns workflow starting at Submitted.
Resolutions are pushed back to TradeMate: account credits, credit notes, or a free ($0) replacement order.

Before you begin

You have a TradeMate account, and know your tenant's API base URL (e.g. https://acme.admin.matehq.com.au/api)
You can access Settings → Integrations in ReturnMate
Your ReturnMate subscription is active — trade returns count towards your monthly RMA limit like any other RMA (see Plans, Billing & Usage Limits)

Connecting TradeMate

Open the TradeMate card

Go to Settings → Integrations and scroll to the TradeMate card. Tick Enable TradeMate integration.

Enter your API URL

Fill in API URL — the base URL for your TradeMate tenant's ReturnMate endpoints (e.g. https://acme.admin.matehq.com.au/api). This field is required while the integration is enabled.

Connect your TradeMate account (OAuth)

Click Connect to TradeMate. A popup opens where you authorise ReturnMate to call TradeMate on your behalf. Once connected, the card shows a Connected badge, the account name, and when the token renews.

If your TradeMate environment doesn't support OAuth yet, click Use API key instead of OAuth and paste a TradeMate API key instead. OAuth is preferred; the API key is a fallback for machine-to-machine setups.

Optional settings

Store ID — sent with every TradeMate request if provided.
TradeMate admin base URL — when set, the trade order number on RMA detail pages links back to the order in TradeMate's admin.
Portal redirect signing secret — required only if trade customers will be redirected from a TradeMate portal into your returns portal (see below). Click Generate a new secret, then paste the same value into TradeMate's portal-redirect signing secret field. The identical secret must exist on both sides.

Save

Click Save TradeMate settings.

📷

TradeMate card in Settings → Integrations showing the Enable checkbox, API URL field and Connect to TradeMate button

(Screenshot placeholder)

The TradeMate integration card in Settings → Integrations.

Creating trade returns

There are three ways a trade return can be created.

1. From the admin (staff-created)

Open Create Trade Return

From the RMA list, click Create RMA, then on the Create Return page use the Create trade return action. (This action only appears while the TradeMate integration is enabled.)

Look up the trade order

Enter the Trade order number (e.g. TO000001) and click Lookup on TradeMate. The company, customer contact details, delivery address and line items are pre-filled from TradeMate.

Choose items and a reason

Tick the line items being returned and adjust quantities (you can't exceed the ordered quantity). Pick a Reason — damaged in transit, wrong item, warranty repair, warranty replacement, over-supplied, ordered in error, or goodwill — and optionally add a fault description and internal notes.

Confirm the pickup / ship-from address

Choose one of the company's saved addresses from the Ship-from address dropdown, keep the order's delivery address, or pick Custom address (enter manually) and type the address (with autocomplete suggestions).

Create

Click Create trade return. You're taken straight to the new RMA's detail page.

📷

Create Trade Return page with trade order lookup, item selection and ship-from address

(Screenshot placeholder)

The Create Trade Return page — look up the TradeMate order, pick items, then create.

2. From a TradeMate portal redirect

Trade customers can start a return from within a TradeMate portal. TradeMate redirects them to your ReturnMate returns portal with a signed, single-use token; ReturnMate validates the token, fetches the trade order, pre-fills the return form, and creates the RMA when the customer submits. Tokens expire and can only be used once.

This flow requires the Portal redirect signing secret to be configured on both sides (Step 4 above).

3. Via the External API

Systems can create and query trade returns through the External API (POST /trade-returns, plus get/list endpoints, relative to the External API base URL). See the API Reference for authentication and payloads.

How trade RMAs behave

Trade returns follow the standard RMA workflow starting at Submitted — approval, labels, receiving and inspection work as usual.
The RMA list and the Order panel on the detail page show a TradeMate badge, along with the trade company name. If you configured the TradeMate admin base URL, the trade order number links out to the order in TradeMate's admin.
Dangerous-goods detection runs on trade line items too — SKUs in your DG product register flag the RMA as dangerous goods.
When approving a trade return, an extra return method is available: No return required (skip return). The RMA is approved and marked received immediately (no label or pickup) — useful for warranty write-offs or low-value goods.

Resolving trade returns

Because there is no Shopify order behind a trade RMA, the resolve step offers TradeMate-specific options via the Resolution selector:

Credit Note — resolve with an account credit or credit note. ReturnMate marks the RMA resolved and notifies TradeMate, which creates the actual financial record. The credit amount cannot exceed the RMA's line-item total.
Send Replacement — a free ($0) replacement order for the returned item(s) is created on TradeMate. You can choose which saved company address to ship it to (or it ships to the order's address). The new TradeMate order number is recorded against the RMA. Replacement creation is idempotent, so a retry after a network failure won't create a duplicate order.

Webhooks

RMA events for trade returns are delivered to your External API webhook endpoint as trade_return.* events: trade_return.created, trade_return.status_changed, trade_return.credit_requested and trade_return.resolved. See Webhooks for signing, retries and payload format.

Permissions and plan requirements

The TradeMate integration is available on all plans. Trade returns count towards your plan's RMAs per month limit, and creation is blocked while your subscription is in read-only mode — see Plans, Billing & Usage Limits.
Configuring the integration requires access to Settings → Integrations.

Limitations

Trade returns never touch Shopify — no Shopify order link, no Shopify refunds. Credits and replacements are handled by TradeMate.
The integration talks to your TradeMate tenant's ReturnMate endpoints; these must be available on the TradeMate side for order lookup, saved addresses and replacements to work.
Credit resolutions are capped at the RMA's item total.

Troubleshooting

Symptom	Likely cause / fix
"TradeMate integration is not enabled for this shop."	Enable the integration and save in Settings → Integrations.
"TradeMate integration is not authenticated. Connect via OAuth or set an API key."	Click Connect to TradeMate, or add an API key via Use API key instead of OAuth.
"Trade order not found on TradeMate."	The order number doesn't exist on TradeMate, or your TradeMate tenant doesn't have the ReturnMate integration endpoints deployed. Check the order number first, then check with TradeMate support.
"Popup blocked. Allow popups for this page and try again."	Your browser blocked the OAuth popup — allow popups and retry.
"Could not reach TradeMate. Try again shortly."	TradeMate is unreachable — transient network or outage; retry.
Portal redirect fails with a token error	The signing secret doesn't match on both sides, or the link was expired/already used. Regenerate the secret in ReturnMate and paste the same value into TradeMate.