Etsy Connector for OpenCart

Overview

The term 'Etsy' is a trademark of Etsy, Inc. This application uses the Etsy API but is not endorsed or certified by Etsy, Inc.

Integrates OpenCart 4.1 with your Etsy shop through the Etsy Open API v3 and your own Etsy app. Your products become Etsy listings with SKU, price, quantity, images, tags and properties, stock and prices follow your store, paid Etsy orders arrive as real OpenCart orders (each exactly once) and the tracking number goes back to Etsy when you ship. OpenCart 4, events only, no OCMOD, no core file changed.

What it does

• Your own Etsy app, one sign-in. Keystring and shared secret stored encrypted; the shop is connected with OAuth 2.0 and PKCE and access is renewed for you. Etsy sends you back through a small page of the extension, so you stay signed in to your admin (OpenCart 4.1 keeps its session cookie strictly same-site).
• Draft listings. Mapped products are created as Etsy drafts with the SKU, price, quantity, images (up to 10), tags (from the product tags), the item weight and the properties you map. Drafts stay drafts until you publish them on Etsy, or switch on "Publish new listings" (Etsy charges its listing fee on publish). A create whose answer was lost is found again: one listing per product, never two.
• Categories and properties. Map your categories to Etsy's seller taxonomy with a markup each, and fill Etsy properties (colour, material ...) from product attributes, the manufacturer, the model, the SKU or a fixed value.
• Prices in your Etsy currency. Markup in percent and a fixed amount (account, category, product), price endings .99 / .90 / whole, your own exchange rate or the OpenCart currency table, and an optional VAT for EU / UK shops whose Etsy prices include VAT.
• Stock and price sync. Stock buffer, sold-out threshold and a maximum; unchanged values are never sent again, and orders are imported before stock is pushed, so a sale on Etsy is never overwritten.
• Orders. Paid receipts become OpenCart orders once, even when cron runs and webhooks overlap: buyer, address (letters such as Zoë or Ståhl kept), the chosen variation, the buyer note, Etsy discount and the tax Etsy collected as their own total lines, the amount converted to your default currency. Receipts still in "payment processing" wait; they are never cancelled.
• Failed imports are retried. A receipt that cannot be imported (SKU not mapped, product disabled) keeps the reason on the Orders page and is read again by its id when you click Retry or after an hour.
• Status follow. Cancelled or fully refunded on etsy.com: the OpenCart order moves to your cancelled / refunded status and the stock comes back. An order you moved yourself keeps your status otherwise.
• Tracking back to Etsy. Set the order to Shipped and write "Tracking: number Carrier: name" in the order history: Etsy gets the shipment once (each report e-mails the buyer). A refusal by Etsy is shown with a Send shipment again button.
• Optional webhooks (order.paid, order.canceled, order.shipped) with signature check, a job queue with retries that respects Etsy's rate limits, a log with CSV export, and data kept on update and uninstall.

Limits

• You need an Etsy shop and a free Etsy developer app for it (keystring + shared secret). Etsy accepts only https callback URLs.
• Etsy has no API to cancel a receipt or to handle returns: those stay on etsy.com and the OpenCart order follows.
• One OpenCart product = one Etsy listing (no variation grouping in 1.0).
• Orders arrive with the scheduled sync (every 15 minutes by default) or at once with webhooks.
• Imported orders do not send e-mails or run the checkout events of other extensions.
• Tested against a stand-in of the Etsy Open API v3 built from Etsy's documentation, not against a live Etsy shop.

Pages

Installation and setup

Requirements

• OpenCart 4.1.0.0 - 4.1.x (tested on 4.1.0.4), PHP 8.1 or later, administrator access.
• An Etsy shop. The person who connects it signs in to Etsy as the shop owner.
• A free Etsy developer app for your shop (below). It gives a keystring and a shared secret.
• Your shop on https: Etsy sends you back to an https callback URL only.
• The OpenCart cron (System > Maintenance > Cron Jobs runs it when your host calls cron.php), or the web address shown on the Jobs page.

Create your Etsy app

1. Sign in to Etsy as the shop owner and open https://www.etsy.com/developers.
2. Create an app for your own shop. Developers who connect the shops of other sellers request Commercial Access instead (Etsy reviews it).
3. Fill in the app name and description. Follow Etsy's Trademark Policy: do not start the app name with "Etsy".
4. Add the callback URL shown on the extension's Connection page, exactly as shown: https://<your shop>/extension/kv_etsy/return.php.
5. Copy the keystring and the shared secret.

Install the extension

1. Extensions > Installer, upload kv_etsy.ocmod.zip, click the green install button next to it.
2. Extensions > Extensions, type Modules, install Etsy Connector, then edit it: status on, the status of imported orders, the sync interval and your licence key (Check now). Without a key it works for 14 days.

Connect Etsy

1. Open Sales > Etsy > Connection. Enter the keystring and the shared secret and click Save and test: "Etsy accepted the app keys" confirms them.
2. Click Connect Etsy shop. Etsy opens in a new tab and asks you to sign in and grant access to listings, shop data and orders. The page you come back to says "Etsy is connected" with your shop name; the Connection page notices it and reloads.
3. Click Load profiles from Etsy, then choose the shipping profile (required), return policy and processing profile, who made the items and when, and whether new listings are published. Save.
4. Map categories (Categories), optionally properties, and set price and stock rules (Rules).
5. Add products on the Listings page (one by one or a whole category) and click Sync now. Check the drafts on Etsy.
6. Optional: in Etsy's webhook portal add the Webhook URL shown on the Connection page for order.paid, order.canceled and order.shipped, and paste the signing secret (whsec_...) into the Connection page.

Updating and uninstalling

OpenCart 4.1 updates an extension by uninstall + install. The links between Etsy receipts and OpenCart orders, between products and Etsy listings, the connection, the rules and the settings are kept on uninstall, so an update never imports an order or creates a listing twice. Nothing is pushed to Etsy right after a reinstall until a product changes or the hourly check comes round.

Configuration

Settings page (Extensions > Modules > Etsy Connector)

Connection

Keystring, shared secret and the optional webhook signing secret (stored encrypted), the callback URL to register in your Etsy app, the shop authorization and the listing defaults: shipping profile (required), return policy, processing profile, who made it, when it was made, supply, "Publish new listings" and "Import orders from".

Rules

Categories and properties

Search Etsy's seller taxonomy, map it to a store category with a markup. On the Properties page fill each Etsy property from a product attribute, the manufacturer, the model, the SKU or a fixed value; required properties must have one.

Usage

Listings

Add a product by its ID (the SKU on Etsy is the product SKU, else the model) or all products of a category. With "Already on Etsy" the product is linked to the listing that has this SKU instead of creating a new one. At the next sync each product becomes an Etsy draft with its price, quantity, images, tags and properties; switch on "Publish new listings" or publish the drafts on etsy.com. The Listings page shows the listing ID (a link to Etsy), the last quantity and price pushed and Etsy's answer when something was refused (Retry).

Stock and price changes go out with the next sync. Etsy decides how a listing at quantity 0 is shown.

Orders

Paid Etsy receipts become OpenCart orders with the order date of the receipt. The order comment holds the receipt number, the payment method, the buyer note and the gift message; the order page has an Etsy panel with the receipt status and the tracking found.

• Failed import: the reason is shown (e.g. "No product mapping for SKU ..."). Fix it and click Retry: the receipt is read again by its id.
• Shipping: set the order to your shipped status (or straight to Complete) and add a history comment such as Tracking: 9400111899223197428490 Carrier: USPS. Etsy gets the shipment with the carrier matched to Etsy's carrier list ("other" when none matches). It is sent once.
• Refused shipment (e.g. Etsy's preferred-partner rule): the order shows "Refused by Etsy" and a Send shipment again button.
• Cancelled or refunded on Etsy: the OpenCart order moves to the mapped status and the stock comes back.

Log and jobs

The Log page lists every step with filters and a CSV export; the Jobs page shows the queue with Run the queue now, Retry and Remove, and the cron command and web address.

Etsy Connector: developer notes

The term 'Etsy' is a trademark of Etsy, Inc. This application uses the Etsy API but is not endorsed or certified by Etsy, Inc.

OpenCart 4.1 port of the CS-Cart add-on kv_etsy 1.0.1 (same API client, mapper, driver and hub logic, with every fix of its release audit research/quality/AUDIT-2026-11-07-etsy.md). Extension code kv_etsy (package kv_etsy.ocmod.zip, licence id kv_oc_etsy), PHP namespace KavioLabs\KvEtsy in extension/kv_etsy/system/library/ (autoloaded by bootstrap.php). Built on the Kavio Marketplace Hub (Hub\*, channel independent) with one channel driver: Client\Api (HTTP), Drivers\Etsy\Mapper (pure translation, unit tested), Drivers\Etsy\Driver (Hub\DriverInterface). OpenCart glue: Store (products, orders, statuses, tracking), compat.php (db_* helpers over the OpenCart DB object), Keep (data kept across uninstall + install), oc4/return.php (OAuth redirect, see below).

Sources (read 2026-11-07)

node scratchpad/etsy/show.mjs op <operationId> prints the parameters and body fields of an operation from the spec copy.

Hosts and headers

• Host https://api.etsy.com (requests guide: api.etsy.com and openapi.etsy.com "are equivalent"; the spec lists openapi.etsy.com).
• Every request: x-api-key: <keystring>:<shared secret> (authentication guide, "API Key"; spec securitySchemes.api_key).
• Scoped endpoints: Authorization: Bearer <user id>.<token> (requests guide). Bodies are UTF-8; form bodies are sent as application/x-www-form-urlencoded; charset=utf-8 (requests guide, "Encoding").
• Test override: the setting module_kv_etsy_base_url (e.g. http://127.0.0.1:11931) replaces the host for every call, including the token endpoint (the authorization page https://www.etsy.com/oauth/connect is opened by the seller's browser and is never called by the store). tests/e2e.js refuses to run unless it points at 127.0.0.1 / localhost.

OAuth 2.0 authorization code grant with PKCE

Redirect (OpenCart 4.1): the session cookie OCSESSID is shared by admin and catalog and sent with SameSite=Strict. A browser coming from etsy.com does not send it, so OpenCart would start a new session and replace the cookie: the admin would be signed out. The redirect URI is therefore oc4/return.php (generated by kv return-file oc_etsy --platform opencart --oauth): it boots nothing, sets no cookie and passes on only state (exact pattern), code ([A-Za-z0-9._~-]{1,512}), error ([a-z_]{1,64}) and language with a same-site navigation (meta refresh + location.replace) to the fixed route. The route itself also removes any queued Set-Cookie when a request arrives without the session cookie (webhooks, a direct hit). The redirect URI used in the link is stored (etsy:redirect:0) and repeated exactly in the code exchange. A registered URI without a query string also settles open point 3 below.

Implementation: Accounts::authState() = <account>.<time>.<nonce>.<HMAC> (1 hour, single use via Accounts::consumeState()); Accounts::verifier() = 43 base64url characters derived from the state with the store secret (RFC 7636: 43-128 of [A-Za-z0-9._~-]), so no verifier is stored. Api::challenge() is checked against RFC 7636 Appendix B and the pair in Etsy's guide (unit tests). The refresh runs under GET_LOCK (Idempotency::lock('token-...')) and re-reads the stored set after taking the lock, because every refresh rotates the refresh token. A refresh answered 400/401/403 (e.g. invalid_grant) PAUSES the account (auth.paused, connection check "Paused"): Accounts::active() is false, cron schedules nothing and Hub::driver() returns null until the seller connects again.

Scopes requested (Api::SCOPES), with the endpoints that need them (spec security of each operation):

listings_d, email_r, address_r are not requested (no delete; buyer e-mail access is a separate approval for commercial apps).

Endpoints

Receipt -> order (Mapper::order): receipt_id, status, is_paid, is_shipped, name (split at the last space, mb-safe), first_line, second_line, city, state, zip, country_iso, buyer_email (null unless Etsy approved access: a placeholder address is used), payment_method, message_from_buyer, is_gift, gift_message, grandtotal, total_shipping_cost, total_tax_cost, total_vat_cost, discount_amt, created_timestamp, updated_timestamp, shipments[], transactions[] (transaction_id, sku, title, quantity, price, listing_id, variations[].formatted_name/formatted_value). Money = amount / divisor (spec, Money schema).

Status (ShopReceipt.status enum paid, completed, open, payment processing, canceled, fully refunded, partially refunded): paid -> created (shipped when is_shipped), completed -> shipped, canceled -> cancelled, fully refunded -> returned, partially refunded -> created / shipped. open and payment processing are pending: never imported, never mapped to cancelled.

Rate limits

QPS and QPD per API key; 429 with retry-after (seconds); headers x-limit-per-second, x-remaining-this-second, x-limit-per-day, x-remaining-today (rate-limits guide). Api::call() waits once for a retry-after of 1-3 s; anything longer is thrown as retryable and the job queue backs off (5 min, 15 min, 1 h, 3 h, 12 h). A run that stops on a 429 keeps what it created (see "Never twice").

Webhooks

Events order.paid, order.canceled, order.shipped, order.delivered, listing.*, inventory.*; payload event_type, resource_url, shop_id (+ listing_id, product_id). Subscriptions are made in Etsy's webhook portal (no API). Signature (Webhook::verify): base64(HMAC-SHA256(base64_decode(secret without "whsec_"), webhook-id + "." + webhook-timestamp + "." + raw body)) compared with every entry of webhook-signature; |now - webhook-timestamp| <= 300. The event is stored as a queue job keyed by webhook-id; order events are read back with getShopReceipt only when resource_url matches https://(api|openapi).etsy.com/v3/application/shops/<our shop>/receipts/<id> (the URL itself is never fetched).

Never twice (checklist: idempotent create, locks)

• Listings: a pending marker (SKU, title, time) is cached BEFORE createDraftListing; the listing id is saved right after it (Hub\ProductSync::created). A retry looks the SKU up in the cache, then in the shop index (getListingsByShop includes=Inventory, every state), then, when a create was pending, in the drafts created since the marker with the same title, and links what it finds.
• Orders: ?:kv_etsy_order_map row claimed with INSERT IGNORE (unique company + receipt) before the order is placed, per-receipt GET_LOCK, placing_at marker; Store::createOrder() writes the marker [kv_etsy:<account>:<receipt>] into the order comment in the same INSERT that creates the order (and removes a half-written order before it rethrows), so an interrupted attempt adopts its order instead of placing a second one. A receipt cancelled at Etsy before it could be imported is parked (retry_at = 2147483647) and never re-read.
• Tracking: the receipt is read first; a shipment with the same tracking code is not sent again (each call e-mails the buyer). A refusal of the request (400/403/404/409/422) is final for that order ("Send shipment again" on the Orders page); authorization problems are retried.
• Import cursor: the Etsy updated_timestamp of the last receipt READ (option order_cursor), not the local time of the last success; failed receipts are re-read by id (getShopReceipt) once their wait is over or when "Retry" is clicked.
• Listing steps: SKU/quantity, images, properties and publish are recorded per listing; a run stopped by a rate limit or timeout finishes the remaining steps on the next sync (no second create, no step twice).
• Currency: outgoing prices use the account's own Etsy shop currency (fixed rate on the Rules page, else the OpenCart currency table; unknown currency = no price push, logged); incoming receipt amounts are converted back to the default currency the same way.

Field limits (mb-safe)

Cuts use mb_substr / mb_strlen with UTF-8 (Mapper::cut). Title: allowed character class and "%, :, & and + once each" from the spec; tags: allowed characters from the spec; styles 2 x 45 (spec, not used); alt_text 500 (spec).

Time zone

Etsy timestamps are Unix seconds. The order date is the receipt's created_timestamp; dates shown in notes use date() (the shop time zone OpenCart sets from System > Settings > Local). "Import orders from" is a calendar day in the shop time zone (Accounts::importFrom, DateTime with the PHP default zone). The Etsy Shop object has no time zone field (spec Shop schema), so the OpenCart shop zone is the one used.

Unverified / flagged

1. Title 140 characters, 13 tags of 20 characters: Etsy's seller-facing limits (Seller Handbook); the API spec names no length. Enforced as constants in Mapper (TITLE_MAX, TAGS_MAX, TAG_LEN). If Etsy rejects a longer value it answers 400 and the product keeps the error.
2. Array encoding in form bodies (tags, value_ids, values): the spec has no encoding object, so the OpenAPI 3 default (style form, explode true: tags=a&tags=b) is used; the tag description says "comma-separated list". Not verified against the live API.
3. Redirect URI with a query string: not needed on OpenCart (<shop>/extension/kv_etsy/return.php has none).
4. createReceiptShipment access: the spec says that in regions where Etsy's Preferred Partner Program applies only approved fulfilment apps, personal-use apps owned by the seller, or apps the seller authorized before the program launched may call it (others get 403). A 403 is shown on the order row and is not retried.
5. Address fields of receipts are "contingent in some regions to a preferred partnership status" (spec, getShopReceipts). An order without a street address is still imported; the order shows what Etsy returned.
6. App type for a sold extension: each merchant registers a Seller App for their own shop (developers.etsy.com: "for your own shop use only", approved within minutes). Whether a purchased third-party extension run by the seller with the seller's own app counts as "own shop use" is not stated; the alternative is a Personal App with Commercial Access (manual review). Owner item.
7. Webhook signature header format: the guide shows one signature and "if more than one" entries; the entry separator and the v1, prefix are taken from the Standard Webhooks convention and accepted both ways.
8. Offering quantity 0: the spec allows minimum=0 per offering; whether Etsy accepts 0 on the only enabled offering (sold out) or wants the offering disabled is not documented. The extension sends 0 and shows Etsy's answer.
9. No sandbox exists: tests run against tests/mock-server/server.js, which follows the documented contract above.
10. A used refresh token stops working: the guide says a refresh returns a new refresh token; that the old one is invalidated at once is assumed (the refresh runs under a lock and re-reads the stored set, so either behaviour is safe).
11. Daily request quota: the rate-limit guide documents the headers but no default numbers. Unchanged stock and prices are not sent again (the inventory is compared first), orders are imported before stock is pushed.
12. Address access: when Etsy withholds the address of a receipt (see 5), the order gets the store country (System > Settings > Local > Country), never a guessed one.

OpenCart port (differences to the CS-Cart add-on)

Troubleshooting

FAQ

Is this an official Etsy app?

No. The term 'Etsy' is a trademark of Etsy, Inc. This application uses the Etsy API but is not endorsed or certified by Etsy, Inc. It integrates with the Etsy Open API v3 through your own Etsy app.

Does it use OCMOD or change core files?

No. Events and cron only.

OpenCart 3?

No, OpenCart 4.1 only.

Do I need an Etsy developer account?

Yes, a free Etsy app for your own shop gives the keystring and shared secret.

Why does Etsy send me to extension/kv_etsy/return.php?

OpenCart 4.1 keeps its session cookie strictly same-site. A page that a browser reaches straight from etsy.com would start a new session and sign you out of the admin. This small page sets no cookie and takes you to the extension's own page from inside your shop, so your admin session is kept.

Are new listings published at once?

No, they stay drafts unless you switch on "Publish new listings". Etsy charges its listing fee when a listing is published.

Can an order be imported twice?

No. The receipt is recorded before the order is created, every receipt has its own lock, and an interrupted import adopts the order it already created.

Can I cancel an Etsy order from OpenCart?

No, Etsy's API has no cancel endpoint. Cancel it on etsy.com; the OpenCart order follows.

Returns?

Handled on etsy.com. A full refund there moves the OpenCart order to your refunded status.

Does it send the buyer e-mail?

Etsy gives the buyer e-mail only to apps it approved for it; otherwise orders get a placeholder address ending in @channel.invalid.

EU / UK shop: do my Etsy prices include VAT?

Enter your VAT rate under Rules > "VAT added to net prices"; products with a tax class get it before the markups.