WooCommerce shop owners
Stipendia for WooCommerce: setup guide
For shop owners setting up on their own, and for Stipendia staff running an onboarding. Version 1.2, 12 November 2026. Plugin version 1.6.0.
1. Overview
Stipendia adds import duties and taxes to a WooCommerce checkout when a customer orders from another country. The customer sees one line, "Import duties & taxes", pays it with the order, and has nothing to pay when the parcel arrives.
What the shop gets:
- Duties and taxes calculated live at checkout, for the customer's country.
- A Customs box on each product for country of origin and customs (HS) code, with a Suggest button that fills the code in.
- Paid orders sent to Stipendia as shipments, so customs records are ready when the carrier asks.
- Coming soon: card payments straight into the shop's own Stripe account, with Stipendia's fee taken automatically (Stipendia Payments).
Two ways to take payment. The shop chooses:
| Keep your current payment method | Stipendia Payments (coming soon) | |
|---|---|---|
| How customers pay | Your existing gateway (WooPayments, Stripe, PayPal, …) | Card on a secure Stripe page that belongs to your own Stripe account |
| Stipendia's fee | Invoiced to you | Taken from each payment automatically; no invoice |
| Extra setup | None | Connect a payout account (about 10 minutes) |
In both cases the money goes to the shop. Stipendia never holds the shop's or the customer's money.
Time needed: about 15 minutes for the basic setup, plus time to add customs data to products.
2. Requirements
Tick every item before starting.
The shop
- WordPress 6.0 or later, WooCommerce 7.0 or later, PHP 8.0 or later (ask the host if unsure).
- Admin access to WordPress (an Administrator or Shop Manager login).
- The site uses HTTPS (the address starts
https://). Required: Stipendia can't connect to a shop without it. Most hosts switch it on free; ask yours if the address startshttp://. - Store currency is US dollar, euro or pound sterling (WooCommerce → Settings → General → Currency). Other currencies are not supported yet.
- The store address is filled in (WooCommerce → Settings → General). It is used as the default origin if nothing else is set.
- Products have a price and, ideally, a weight.
Information to have ready
- Where each product is made (country of origin). Not where it ships from.
- The customs (HS) code for each product, if known. If not, the Suggest button will propose one.
- Which countries you ship to (US, UK, EU, Canada, …).
Accounts
- A Stipendia account: sign up at ddp.stipendia.ai. (Staff: use ddptest.stipendia.ai for test setups.)
- For Stipendia Payments only (when available): business details for Stripe's checks (legal name, address, date of birth of the owner or director, company number if a company) and the bank account (or WorldFirst account) payouts should go to.
3. Setup, step by step
Step 1: Create your Stipendia API key
- Sign in at ddp.stipendia.ai.
- In the left menu, open API Keys, then click Create API key.
- Name it after the shop (for example
woocommerce-myshop). Leave the permission boxes as they are: the plugin works with any key from this page. - Click Create key and copy the key straight away. It is shown only once. Keep it private, like a password.
Step 2: Install the plugin
- In WordPress, go to Plugins → Add New → Upload Plugin.
- Choose the file stipendia-woocommerce.zip (sent by Stipendia), click Install Now, then Activate.
- A "Finish setting up Stipendia" checklist appears at the top of the admin. It ticks itself off as you go.
Step 3: Connect your shop
- Go to WooCommerce → Settings → Stipendia.
- Environment: choose Live for real orders (choose Test only if Stipendia staff asked you to).
- API Key: paste the key from Step 1.
- Default country of origin: choose the country most of your products are made in (see Step 4).
- Import charges: leave on DDP: add to the order total (recommended; see Step 5).
- Scroll to the bottom and click Save changes. You should see "Your settings have been saved".
- Click Connect to Stipendia. WooCommerce shows an approval screen for "Stipendia". Click Approve. You return to the settings page, which now says ✓ Connected.
No Connect button? The site is not on HTTPS. Switch HTTPS on with your host first; Stipendia can't connect without it.
Step 4: Tell Stipendia where your goods are made
Duty depends on where a product was made, not where it ships from.
- Most shops: the Default country of origin from Step 3 is enough.
- Products made somewhere else: open the product, go to Product data → Shipping, find Customs (Stipendia) and set Country of origin.
- Customs code: in the same box, click Suggest. Stipendia proposes a code from the product name and shows what it means. Check it looks right, then click Update to save the product.
The checklist shows how many products still have no customs code.
Step 5: Choose how import charges work
| Setting | What the customer sees | Recommended for |
|---|---|---|
| DDP: add to the order total | "Import duties & taxes" in the total. Nothing to pay on delivery. | Most shops: fewer refused parcels, no surprise bills. |
| DDU: show as due on delivery | An estimate, marked as due on delivery. Not charged. | Shops whose carrier collects duty on delivery. |
Step 6: Place a test order
- Add a product to the basket.
- At checkout, enter a delivery address in the United States or United Kingdom.
- Check that "Import duties & taxes" appears in the order total. Click "What are import duties & taxes?" to see the breakdown. A green note under the total should read "Duties paid at checkout. Nothing more to pay on delivery."
- Cancel or refund the test order afterwards.
Tip: a "VAT $0.00" or "Tax $0.00" line. If your checkout shows a zero tax line next to "Import duties & taxes" on orders going abroad, that line is WooCommerce's own sales tax, not Stipendia's. It confuses customers, so check WooCommerce → Settings → Tax: make sure your tax rates only apply to the countries you charge tax in. If you don't charge tax at checkout at all, untick Enable tax rates and calculations under WooCommerce → Settings → General.
Cart page: the cart shows "Import duties & taxes are added at checkout once you enter your delivery address" until the customer gives an address abroad. That's expected.
The basic setup is done. Paid orders now go to Stipendia automatically.
Worked examples
Everything made in one country (for example, an Irish honey producer). Set Default country of origin to that country in Step 3. No product needs its own origin. Click Suggest on the main products to fill in their customs codes, and type the code in yourself if Suggest has no answer.
Products made in several countries (for example, a golf equipment shop). Set the default to the most common origin, then set Country of origin on each product made elsewhere (Step 4). This matters: the same trolley can pay a different duty depending on where it was made. For example, a trolley that qualifies as EU-made under the UK–EU agreement may pay no UK duty, while a Chinese-made one does.
4. Coming soon: Stipendia Payments
Not yet available for live shops. The steps below show how it will work. Stipendia will tell you when you can switch it on; until then, keep your current payment method.
Customers pay by card into your own Stripe account. Stipendia's fee is taken from each payment, so there is nothing to invoice.
Step 7: Connect your payout account (about 10 minutes)
- In the Stipendia dashboard, open Payouts & Settlements.
- Under Get paid directly, choose the country your business is registered in, then click Set up. Stripe's form opens inside the page. (The country cannot be changed later.)
- Fill in:
- Business type (for example sole trader or company), and your details.
- Website: your shop's address. Products: a short description of what you sell.
- Statement descriptor: how you appear on customers' card statements (for example
MYSHOP). - Bank account (or WorldFirst account) for payouts.
- Fraud protection: Stripe asks you to choose a level. Pick "Use baseline protection with Lite (included)" unless you want more. Higher levels may cost extra and are charged to you by Stripe.
- Already have a Stripe account? If your email is already used with Stripe, Stripe asks for the code from your authenticator app so it can reuse your details. Enter it, or use a different email to start fresh.
- When it finishes, the badge shows Connected. Your Payouts page now lists payments to your account, with Stipendia's fee on each, and a View payouts in Stripe button.
Step 8: Turn on Stipendia Payments
- In WordPress, go to WooCommerce → Settings → Payments.
- Turn on Stipendia Payments. You can change the Title customers see (default: Card) and the description.
- Place a test order and choose Card. You are taken to a secure Stripe page that lists the products, shipping and import duties & taxes, with the order number above the Pay button. After paying, the customer returns to your order confirmation page and the order is marked Processing.
Refunds: issue them from your own Stripe Dashboard. Stipendia's fee is not refunded.
5. Test and go-live checklist
Going live:
- Create a live API key at ddp.stipendia.ai and paste it, with Environment set to Live. Click Connect to Stipendia again.
- Default country of origin is set; products made elsewhere have their own origin.
- Main products have customs codes (checklist shows none missing, or the shop accepts the gaps).
- Import charges mode agreed (DDP recommended).
- If using Stipendia Payments (once available): payout account Connected on the live dashboard, payment method turned on, one small real order placed and refunded.
- The shop knows who pays customs on its shipments (its carrier or customs broker; see Section 6).
6. Fees and how the money moves
Stipendia's fee per international order is a fixed amount plus a percentage of the duties and taxes. Nothing is charged on the value of the goods. The fee appears to the customer as "Clearance service" inside "Import duties & taxes".
| Plan | Monthly | Per order (store in $ / € / £) | Plus, of duties & taxes |
|---|---|---|---|
| Free | $0 | $1.75 / €1.75 / £1.50 | 7.5% |
| Growth | $99 | $1.50 / €1.50 / £1.30 | 5% |
| Scale | $399 | $1.00 / €1.00 / £0.85 | 3% |
Every shop starts on Free. Upgrade any time in the Stipendia dashboard under Billing. Subscriptions and invoices are in US dollars.
Who pays customs: the shop, through its carrier or customs broker, as today. The customer pays the duties to the shop at checkout, so the shop is covered. Stipendia does not pay customs on the shop's behalf.
How the money moves:
- Your current payment method: the customer pays the full total to you. Stipendia invoices you for its fees.
- Stipendia Payments: the customer pays into your own Stripe account. At the same moment Stripe moves Stipendia's fee to Stipendia. Stripe's own processing fee is charged to your Stripe account as usual. Payouts follow your Stripe payout schedule.
7. Troubleshooting and FAQ
No "Import duties & taxes" line at checkout. Check the delivery country is different from the store's country. Check the store currency is USD, EUR or GBP. Check the API key is pasted and the plugin says Connected. Check Import charges is set to DDP.
"The shop was not connected" after Approve. The API key and the Environment must match: a key from ddp.stipendia.ai needs Live, a key from ddptest.stipendia.ai needs Test. Fix it, save, and click Connect again.
The Connect button is missing. The site is not on HTTPS. Ask your host to switch it on, then reload the settings page.
Suggest says "No suggestion". Check the product has a name and the API key is saved. Then try a clearer name (for example "Raw honey, 450 g jar" rather than "Spring Gold").
Stipendia Payments does not appear at checkout. It only shows when it is turned on, the store currency is USD, EUR or GBP, and an API key is set.
A customer paid but the order is still Pending. Orders are confirmed when the customer returns to the shop, and by an hourly check if they do not. Wait an hour, or contact Stipendia support with the order number.
The Stripe payment page shows my own name, not my shop's. Stripe shows the business name from your Stripe account. Change it in your Stripe Dashboard under Settings → Business → Public details.
My checkout shows "VAT $0.00" (or "Tax $0.00"). That is WooCommerce's own tax line, not Stipendia's. See the tip under Step 6.
Can I change the payout bank account? Yes. Payouts & Settlements → Manage payout account.
Does the plugin send customer data to Stipendia? For the duty calculation, only the destination country and the products (name, value, origin, customs code). When you connect, WooCommerce also sends Stipendia each new or changed order, including the customer's name, addresses, email and phone, so Stipendia can keep customs records and record its fee.
Support: support@stipendia.ai, or the chat button in the Stipendia dashboard.