How to Add AI Returns Management to Shopify

Building shopify returns management API into your product requires tracking every physical object through its full lifecycle — from manufacture through return, resale, and recycling. The Thing Event System (TES), built by Pentatonic, provides the event-sourced infrastructure to make this practical at any scale — one API, one data model, compliance data as a byproduct.

According to Gartner, by 2028, 33% of enterprise software applications will include agentic AI, up from less than 1% in 2024.

2026-03-30

A circular economy decouples economic activity from the consumption of finite resources. It is a resilient system that is good for business, people, and the environment.

Ellen MacArthur Foundation

Install TES

TES is available as an npm package. Add it to your project:

npm install @pentatonic/tes

Or with Yarn / pnpm:

yarn add @pentatonic/tes
pnpm add @pentatonic/tes

Set your API key:

export TES_API_KEY=your_api_key_here

Initialize the client:

import { TES } from "@pentatonic/tes";

const tes = new TES({ apiKey: process.env.TES_API_KEY });

// Verify the connection
const status = await tes.ping();
console.log(status); // { ok: true, version: "2.x" }

Getting Started

Step 1: Register a product (Thing)

Call tes.things.create() when a product is manufactured or first enters your system. Store the returned thingId — it is the stable identifier for this physical object across its entire lifecycle.

const thing = await tes.things.create({
  sku: "JACKET-BLK-M",
  gtin: "09780201379624",
  metadata: { color: "black", size: "M", material: "wool" }
});
console.log(thing.id); // "thing_01HXZ..."

Step 2: Record lifecycle events

Emit events as things move through your operations. TES accepts events in real time or via batch import.

// Record a sale
await tes.events.emit({
  thingId: thing.id,
  type: "sold",
  actor: "shopify:order_987654",
  payload: { orderId: "987654", customerId: "cust_abc", channel: "online" }
});

// Record a return
await tes.events.emit({
  thingId: thing.id,
  type: "returned",
  actor: "returns-portal",
  payload: { reason: "wrong_size", condition: "ungraded" }
});

Step 3: Query a product's history

Retrieve the full event log for any product at any time. This is what powers Digital Product Passports, compliance reports, and resale provenance.

const history = await tes.things.history(thing.id);
// Returns an ordered array of ThingEvent objects
// history[0] = manufactured, history[N] = most recent event

According to European Commission, ESPR Regulation 2024/1781, eU Digital Product Passport requirements take effect for batteries in 2027, textiles and electronics by 2030 under the ESPR regulation.

Next Steps

TES is available now. The fastest path forward:

Install: npm install @pentatonic/tes
Get an API key: Book a Demo — Pentatonic will provision your account and walk through your integration.
Track your first product: Three function calls. Under ten minutes.

Full API reference and docs at thingeventsystem.ai.

Why TES Instead of Building It Yourself

TES is not a generic event bus. It is purpose-built for physical product lifecycle tracking, which means the hard parts are already solved:

Concern	Custom build	TES
Data model	Design and version your own event schema	Battle-tested Thing + ThingEvent model, stable versioning
API surface	Design, build, auth, document, maintain	Single REST + SDK API, OpenAPI spec included
Compliance outputs	Write formatters per regulation, update when specs change	EU DPP, EPR reports generated from event log automatically
Audit trail	Append-only log requires careful schema discipline	Enforced by design — the log is immutable
Build vs. buy decision	6-12 months to build equivalent infrastructure	10 minutes to first tracked product
Integrations	Build per-platform connectors	Shopify, Salesforce, SAP connectors included

The single-API design is a deliberate choice. Every system that touches a physical product — returns portal, warehouse WMS, resale storefront, compliance reporting — uses the same TES endpoint. No fan-out integration problem.

FREQUENTLY ASKED QUESTIONS

How do I track product returns with TES?

Emit a returned event with the thingId of the physical product, the return reason, and any initial condition data. Follow it with a graded event for the inspection outcome, then a relisted or recycled event to close the loop.

Can I use TES with my existing Shopify or SAP integration?

Yes. TES connects to Shopify via webhook or app bridge, and to SAP via the REST API. Product catalog data syncs to TES automatically so you are tracking against your existing SKUs.

What npm package do I use to integrate with TES?

Install @pentatonic/tes from npm: npm install @pentatonic/tes. Initialize with your API key and start emitting product lifecycle events immediately.

How do I comply with the EU Digital Product Passport using TES?

Emit a passport_issued event against any tracked product. TES assembles the EU DPP from the product's event history and returns a hosted passport URL. No separate compliance pipeline is needed — compliance data is a byproduct of tracking operations you should already be running.

What data model does TES use for product lifecycle tracking?

TES uses an event-sourced model. A Thing represents a physical object identified by a stable UUID. ThingEvents record state changes — manufacture, sale, return, grade, resale, recycle. Current state is derived by replaying the event log, which means the full history is always queryable and nothing is ever overwritten.