Next.js & server-side

The private API surface with @getenvie/client — dashboards, exports, automation, and customer merge from any Node server.

This page covers the private mode of @getenvie/client: full shop scope, server-side only — for Next.js apps, cron jobs, or anything with a backend.

Setup

Create a private key in the Shopify admin under Envie → Developers, and keep it in an environment variable:

npm i @getenvie/client

// lib/envie.ts
import { createEnvie } from "@getenvie/client";

export const envie = createEnvie({
	mode: "private",
	shop: "your-store.myshopify.com",
	secretKey: process.env.ENVIE_SECRET_KEY!, // env_sk_…
});

The key is shown once at creation. Rotation is one click (create a new key, delete the old one) and takes effect within a minute.

What the private surface gives you

// Shop state: plan, settings, usage counters
const shop = await envie.private.shop();

// Browse lists — cursor pagination, optionally per customer
const page = await envie.private.lists({ limit: 50 });
const next = await envie.private.lists({ cursor: page.pageInfo.nextCursor ?? undefined });

// Analytics
const top = await envie.private.topProducts("30d"); // "7d" | "30d" | "90d"
const activity = await envie.private.activity("7d");

// Exports — async job, poll for the signed download URL (valid 24 h)
const { jobId } = await envie.private.createExport("csv");
const job = await envie.private.export(jobId);

The storefront surface works in private mode too — that's how you merge a guest list into a customer's after login:

const envieForShopper = createEnvie({
	mode: "private",
	shop: "your-store.myshopify.com",
	secretKey: process.env.ENVIE_SECRET_KEY!,
	anonymousId: aidFromBrowser, // the shopper's `envie:aid`
});

await envieForShopper.identify({ customerId });

Errors

Every error is structured. The SDK throws a typed error carrying the HTTP status and a problem document with a stable type URL — open that URL for the explanation and fix:

import { EnvieApiError } from "@getenvie/client";

try {
	await envie.private.createExport("csv");
} catch (error) {
	if (error instanceof EnvieApiError) {
		console.error(error.status, error.problem.type, error.problem.detail);
	}
}

See the error reference for every type, and the SDK reference for the complete client surface.

Common mistakes

One global client for shopper-scoped calls. anonymousId is bound at construction. For merge-on-login, build a short-lived client per request with that shopper's id — don't set it on a shared singleton.
Polling exports in a tight loop. Export jobs are asynchronous; poll every few seconds. Private keys are limited to 600 requests per minute — a busy loop spends that on nothing.
Treating titleSnapshot as product data. It's a best-effort label for exports. Join on productId against your own catalog data for anything user-facing.

Next.js & server-side

Setup

What the private surface gives you

Errors

Common mistakes

On this page