How Seller API fits Shopify, WooCommerce, Magento, BigCommerce, and custom keyshops — plus the Steam/Epic boundary.
What this covers#
Where to put Avrix calls in common commerce stacks. Pair with Architecture patterns and Store integration profiles.
Hard rule#
Checkout UI talks to your backend. Your backend calls Avrix with the Seller API key. Never embed the key in themes, storefront JS, or app clients.
Maintained plugins#
Avrix maintains plugins for WooCommerce and Shopify, built on the official SDKs. Both follow the same rules:
- The API key never leaves your server. It is stored server-side, sent only on server-to-server calls to Avrix, and never rendered into a page, a theme, checkout scripts or the buyer's browser.
- One Avrix order per line, with the store order id as
orderReference. An order with several Avrix lines uses<order id>-<line id>per line and declares the order id asparentOrderReference. - Idempotent order creation with recovery. The POST /orders body is saved
before the first attempt and every retry sends the same body with the same
Idempotency-Key. A lost response is resolved withGET /orders?orderReference=and POST /orders/recover-keys, never with a second order. - Refunds only when Avrix confirmed it. A line is flagged for a refund only when Avrix confirmed that no live key exists for it (or the preview refused it before any order was sent). An unknown outcome is retried, never refunded.
- The full sales declaration on every order:
salesCountryCode,consumerIp(the buyer's IP captured at checkout, never your server's),currencyCode, per-unitsalesPriceGrossMinor/salesPriceNetMinor/salesTaxAmountMinor,salesTaxRatePercent,salesChannel,paymentMethodFamily,paymentProcessorReferenceandcheckoutSessionId. See Order context. - Signed webhooks with rotation. Every
v1signature is checked against your current and previous secret, so a rotation needs no downtime. Deliveries are deduplicated on the event id. - Keys at rest are encrypted (with a server secret, or the site salts on WordPress) and decrypted only to show them to the buyer.
Test each plugin end to end with a sandbox key (avrix_sk_sbx_…) and the
sandbox SKUs before switching to a production key.
WooCommerce#
Avrix Keys for WooCommerce is a WordPress plugin (PHP 8.1+, WooCommerce
8.5+, HPOS and block checkout compatible) on the avrix/seller-api PHP SDK.
| WooCommerce moment | What the plugin does |
|---|---|
| Order placed (classic or block checkout) | POST /orders/preview per Avrix line with the buyer's IP and country; a line Avrix cannot sell stops the checkout before payment. With checkout holds enabled, POST /orders/hold keeps the stock while the buyer pays. |
| Payment complete (or the order set to processing / completed) | A fresh preview binds the price, then POST /orders through the recovery helper. Keys are stored encrypted and shown on the thank-you page, in My Account and in the customer emails. |
| Backorder or pre-order accepted | Order on hold with a note; order.ready triggers POST /orders/{orderId}/fulfill and order.preorder_fulfilled reads the keys with POST /orders/recover-keys. |
| Refusal confirmed by Avrix | Order marked failed with a note telling you to refund the customer. |
| Refund with line items | POST /refunds with the refunded quantity and the WooCommerce refund id as refundReference. A full refund returns every remaining key; an amount-only partial refund keeps the keys live. |
| Every 15 minutes (WP-Cron) | Catalog snapshot on the first run, then the GET /catalog/changes cursor; the stock of mapped products is set from GET /availability. Optionally the regular price follows the suggested retail price. |
Install and configure
- Upload the plugin ZIP under Plugins → Add New → Upload Plugin and activate it. Ask support@avrix.io for the current release until the plugin is listed on WordPress.org.
- Open WooCommerce → Settings → Avrix: choose the environment, paste the API key (the field is write-only), check the store country and the sales channel. Options for checkout holds, backorders, stock and price sync are on the same page.
- Register the webhook URL shown on the settings page
(
https://<your-shop>/wp-json/avrix/v1/webhook) with POST /webhooks fororder.fulfilled,order.ready,order.preorder_fulfilled,order.failed,order.keys_returnedandrefund.completed, and paste the signing secret. During a rotation, keep the old secret in the Previous webhook secret field. - On each product or variation you sell through Avrix, fill in Avrix SKU
code with the
skuCode.
Shopify#
Avrix Keys for Shopify is the backend of a Shopify custom app (Node 20+)
on @avrix/seller-api-client and @avrix/seller-api-helpers. You host it;
Shopify only sends it webhooks and receives Admin API calls from it. A Shopify
variant is mapped to Avrix when its SKU equals the Avrix skuCode.
| Event | What the app does |
|---|---|
orders/paid (HMAC-verified with the app secret) | Records the order inside the webhook request, then previews and places each Avrix line through the recovery helper. The buyer IP comes from the order's browser_ip; tax, net, gross, currency and the payment gateway from the order. Keys are stored encrypted, written to the order metafield avrix.game_keys, and the line is fulfilled with a customer notification. |
refunds/create | POST /refunds per refunded Avrix line, keyed by the Shopify refund, so a redelivered webhook never refunds twice. |
Avrix order.fulfilled, order.ready, order.preorder_fulfilled | Replays a lost response, fulfils a backorder, or reads a released pre-order's keys, then delivers them. |
Avrix order.failed | Tags the order avrix-refund-required. |
| Catalog sync (timer) | Snapshot, then the change cursor; sets the available quantity of mapped, tracked variants at one location from GET /availability. |
Install and configure
- Create the app in the Shopify Partner / Dev Dashboard with custom distribution for your store. The app's source and install guide are available from support@avrix.io; App Store listing follows later.
- Host the backend on an https origin with persistent storage, and set its
environment: the Avrix API key (
AVRIX_API_KEY), the webhook secret (AVRIX_WEBHOOK_SECRET), the store country, the Shopify app secret, the shop domain, the inventory location and a key-encryption secret. - Deploy the app configuration (
shopify app deploy) to register the scopes and theorders/paid,refunds/createand compliance webhooks, then open the install link the backend serves and approve the scopes. - Register the backend's Avrix webhook URL with
POST /webhooksfor the events above. - Add the
avrix.game_keysorder metafield to your shipping confirmation notification and order status page so the buyer sees the keys.
Platform sketches#
Magento#
Implement a PHP module that hooks after successful payment at your PSP and
calls Avrix from the server with the avrix/seller-api SDK
(Orders::createWithRecovery). Persist orderReference as the Magento order
id (or a stable derived id). The WooCommerce plugin above is a complete
reference for the flow.
BigCommerce#
Same pattern: server-side app or middleware after payment capture. Sync catalog on a schedule; do not scrape the storefront for SKU authority — use Avrix snapshot + allocations.
Custom keyshop#
You own cart, tax, and PSP. Recommended flow:
Steam / Epic#
Steamworks and Epic Online Services are separate platform contracts. Avrix does not create Steam packages or Epic store offers. Use Avrix for inventory you sell through your commerce channels; use each platform’s APIs for sales inside that platform’s store.
Mapping store concepts#
| Your concept | Avrix field / API |
|---|---|
| SKU / product code | skuCode on preview and orders |
| Store order id | orderReference |
| Buyer country | countryCode / sales country in order context |
| Payment id | paymentProcessorReference (opaque) |
| Fulfilment email job | Triggered after order response or webhook |
Common mistakes#
- Calling Avrix from Shopify Liquid or Woo storefront JS.
- Using a new idempotency key on every PSP webhook retry.
- Syncing only
/productsand skipping/allocations— see Sellable SKU readiness.
Next steps#
- Creating orders — safe commit pattern
- Integration recipes — scopes and call order
- FAQ — short answers to common questions