Commerce platforms

Shopify, WooCommerce, Magento, keyshops, game backends, and platform-store boundaries.

TopicsReference

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 as parentOrderReference.
  • 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 with GET /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-unit salesPriceGrossMinor / salesPriceNetMinor / salesTaxAmountMinor, salesTaxRatePercent, salesChannel, paymentMethodFamily, paymentProcessorReference and checkoutSessionId. See Order context.
  • Signed webhooks with rotation. Every v1 signature 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 momentWhat 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 acceptedOrder 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 AvrixOrder marked failed with a note telling you to refund the customer.
Refund with line itemsPOST /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

  1. 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.
  2. 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.
  3. Register the webhook URL shown on the settings page (https://<your-shop>/wp-json/avrix/v1/webhook) with POST /webhooks for order.fulfilled, order.ready, order.preorder_fulfilled, order.failed, order.keys_returned and refund.completed, and paste the signing secret. During a rotation, keep the old secret in the Previous webhook secret field.
  4. 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.

EventWhat 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/createPOST /refunds per refunded Avrix line, keyed by the Shopify refund, so a redelivered webhook never refunds twice.
Avrix order.fulfilled, order.ready, order.preorder_fulfilledReplays a lost response, fulfils a backorder, or reads a released pre-order's keys, then delivers them.
Avrix order.failedTags 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

  1. 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.
  2. 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.
  3. Deploy the app configuration (shopify app deploy) to register the scopes and the orders/paid, refunds/create and compliance webhooks, then open the install link the backend serves and approve the scopes.
  4. Register the backend's Avrix webhook URL with POST /webhooks for the events above.
  5. Add the avrix.game_keys order 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:

Diagram

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 conceptAvrix field / API
SKU / product codeskuCode on preview and orders
Store order idorderReference
Buyer countrycountryCode / sales country in order context
Payment idpaymentProcessorReference (opaque)
Fulfilment email jobTriggered 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 /products and skipping /allocations — see Sellable SKU readiness.

Next steps#

What links here

Published guides that link to this page.

Search docs

Search documentation…