Skip to main content

Shopify integration

Alkax provides one hosted Shopify app at commerce.alkax.io. Integration setup starts in an Alkax Developer Project, not inside a standalone merchant configuration screen.

The Developer Project is the tenant boundary. A project can connect multiple Shopify stores, and every store connection selects either the project's Sandbox or Production environment.

Connect a store​

  1. Open Developer Console and select the project that should own the Shopify store.
  2. Open E-commerce → Shopify.
  3. Enter the store's *.myshopify.com domain.
  4. Choose Sandbox or Production.
  5. Choose Connect store.
  6. Complete Shopify installation/authorization at commerce.alkax.io.

Alkax creates a short-lived connection handoff. The shared Shopify runtime redeems it after Shopify authentication and binds the store to:

DeveloperProject.Id   -> tenant identity
DeveloperEnvironment  -> Sandbox or Production execution/billing context
Shopify shop domain   -> connected store

A store can have only one active Alkax project binding at a time.

What gets configured automatically​

Developers do not copy an Alkax API key into Shopify. On successful binding, Alkax issues an integration-only credential for the selected project/environment and returns it only to the shared commerce.alkax.io runtime.

Calls made by the Shopify integration therefore use the same project/environment attribution, limits, and billing path as normal Developer Platform traffic.

The credential stays server-side. It is never included in a checkout extension, customer account extension, or browser response.

Address autocomplete​

Address autocomplete is the base Shopify capability. The checkout extension calls the shared runtime with a Shopify session token. The runtime resolves the shop to its project tenant and calls:

GET /api/v1/addresses/suggestions?q=<query>&countryCode=<optional>&limit=5
X-Alkax-Key: <managed project/environment credential>

Suggestions come from Alkax-owned address search. Manual Shopify address entry remains available if Alkax is temporarily unavailable.

Availability of checkout address extensions is subject to Shopify's current checkout-plan, protected-customer-data, and network-access requirements.

Optional order tracking​

Order tracking is enabled per connected store from Developer Console → E-commerce → Shopify.

When a developer selects Enable tracking:

  1. Alkax marks tracking as requested for that project/store connection.
  2. The flow opens the installed Shopify app.
  3. Shopify asks the store to grant the optional read_orders scope.
  4. commerce.alkax.io reports that approval back to the canonical project integration.
  5. New orders/create webhooks can create project-scoped Alkax deliveries.
  6. The customer-account order-status extension can show the Alkax delivery state after verifying that the signed-in customer owns the order. Tracking is hidden for anonymous sessions or when Shopify cannot verify ownership.

Disabling tracking in the Developer Console takes effect at the canonical connection even if the Shopify permission has not yet been manually revoked. The installed app can also revoke unused order access.

Shared multi-tenant runtime​

Alkax Developer Project
  └── E-commerce
       └── Shopify
            ├── store-a.myshopify.com -> Sandbox
            └── store-b.myshopify.com -> Production
                         |
                         v
                commerce.alkax.io
             shared Shopify runtime
                         |
              tenant = DeveloperProject.Id
                         |
                         v
                  Alkax platform

The Alkax application database owns the canonical connection and feature state. The Shopify runtime database owns only operational Shopify state: OAuth sessions, the resolved tenant binding, webhook receipts, and Shopify-order ↔ Alkax-delivery mappings.

Operational rows include the project and environment identifiers so tenant attribution is explicit and auditable.

Connection security​

The project creates a random, short-lived handoff token. Alkax stores only its hash. The Shopify runtime stores the handoff just long enough to survive Shopify OAuth, then redeems it through a service-authenticated Alkax endpoint.

Redemption is one-time. Successful activation clears the handoff and automatically creates the project/environment credential used by that store connection.

Uninstalling or redacting a Shopify shop calls the Alkax control plane, marks the canonical connection disconnected, disables tracking, and revokes its integration credential.

Delivery identity and retries​

Each Shopify order maps deterministically using the shop domain and Shopify Order GID. The integration uses stable Alkax idempotency/activation values and stores Shopify webhook IDs, so Shopify retries and Alkax retries do not create duplicate deliveries.

When Shopify does not provide destination coordinates, the integration can resolve an Alkax Plus Code embedded in the selected address. If neither coordinates nor a usable Alkax code exists, the order is recorded as awaiting_address; no 0,0 delivery is created.

Maintainer configuration​

The implementation lives in integrations/shopify/ and is deployed separately from the main web frontend.

Required runtime configuration:

DATABASE_URL=postgresql://...
SHOPIFY_API_KEY=...
SHOPIFY_API_SECRET=...
SHOPIFY_APP_URL=https://commerce.alkax.io
SCOPES=

ALKAX_API_URL=https://<alkax-api-host>
ALKAX_SHOPIFY_SERVICE_KEY=<shared service identity>

The Alkax API deployment must configure the matching:

ShopifyIntegration:AppUrl=https://commerce.alkax.io
ShopifyIntegration:ServiceKey=<same shared service identity>

Local validation:

cd integrations/shopify
npm install
npm run prisma:generate
npm test
npm run typecheck
npm run build

See Developer Platform and Delivery Intelligence for the underlying project, quota, and delivery contracts.