commercetools Commerce Integration Layer

Testing, validating, and pushing a Commerce Integration Layer bundle

1. Unit-test resolvers and handlers

import { describe, expect, it } from "vitest";
import type { ExtensionInput } from "@commercetools/platform-sdk";
import { apiExtensions } from "./extension.js";

const ctx = (config: Record<string, string> = {}) => ({ now: () => Date.now(), config });
const { handler } = apiExtensions.find((e) => e.key === "cart-sku-blocker")!;

const cartWith = (action: "Create" | "Update", skus: string[]) =>
  ({
    action,
    resource: {
      typeId: "cart",
      id: "cart-1",
      obj: { id: "cart-1", lineItems: skus.map((sku, i) => ({ id: `li-${i}`, quantity: 1, variant: { sku } })) },
    },
  }) as unknown as ExtensionInput;

describe("cart-sku-blocker", () => {
  it("approves a cart without blocked SKUs", () => {
    expect(handler(cartWith("Create", ["OK-1"]), ctx())).toEqual({});
  });

  it.each(["Create", "Update"] as const)("blocks a blocked SKU on %s", (action) => {
    expect(handler(cartWith(action, ["BLOCKED-SKU"]), ctx())).toMatchObject({
      errors: [expect.objectContaining({ code: "InvalidInput" })],
    });
  });

  it("reads the blocked list from config", () => {
    expect(handler(cartWith("Create", ["X"]), ctx({ BLOCKED_SKU: "X,Y" }))).toHaveProperty("errors");
  });
});

2. Fire the handlers at the merged bundle, offline

# Scaffold realistic payloads once, edit them, and keep them in the repo as fixtures
commercetools integration-layer extension create-api-extension-input --resource-type cart --action Create --out payloads/cart-create.json
commercetools integration-layer extension create-api-extension-input --resource-type cart --action Update --out payloads/cart-update.json

commercetools integration-layer extension invoke-api-extension --all --input payloads/cart-create.json
commercetools integration-layer extension invoke-api-extension --all --input payloads/cart-update.json --config MAX_LINE_QUANTITY=10

3. Query the merged schema through a gateway

{ product(id: "…") { name loyaltyPoints(price: 1000) } }

• /graphql is the gateway.
• /_extension is the raw merged subgraph.
• /composed shows the merged schema.

If an edit does not compose, the log lists the collisions and the server keeps serving the last good schema, so watch the log, not only the query result.

• Fields that use @requires or @override only show their real behavior in the composed graph. Test them here, not in a standalone server.
• External services: when you are logged in, resolver fetch goes through the same Project host allowlist as production. Add the provider's host with allowlist add <host> before testing. Without a login, fetch is unrestricted locally, so an allowlist gap only shows up once you log in.
• Customer-scoped fields: commercetools integration-layer explore --as <email>, run from an extension directory, composes your working tree against the Project and runs operations as that customer.
• One extension in isolation: pnpm --filter @extensions/<name> dev serves just that subgraph, offline. Exercise entity fields through the _entities query.

4. Run real writes through your local handlers

ngrok http 4000   # or any HTTPS tunnel
commercetools integration-layer extension serve-api-extension --all --public-url https://<tunnel-host>

This is the only layer where commercetools itself validates the request before your handler runs. Use it to:

• send every entry point of the business action through the API: a cart created with lineItems, addLineItem, adding a Shopping List;
• confirm that a condition triggers on the writes it should, and only those;
• confirm the case from the write path: a value the request needs to pass validation has to be on the request itself, because your handler never sees a request that fails validation.

5. Validate the merged bundle

6. Push and confirm the revision is running

• A failed revision drops out of service. The Project keeps serving the newest revision that did not fail. When a pushed change does not appear, check whether the push reported running.
• extension status shows the stored bundle (version, size, upload time, recorded source revision), not whether it loaded. The push's wait is where the load verdict is reported.
• Rolling back means pushing the previous code again. There is no unpublish command, and the recorded source revision (from git, or EXTENSION_SOURCE_REVISION in CI) tells you which code is deployed.
• --force skips only the remote checks, for a coordinated breaking change. Through a package script, forward it explicitly: pnpm push -- --force.
• Configuration set with config set <KEY> <VALUE> (add --secret for credentials) takes effect without a new push.

commercetools integration-layer explore --deployed        # the composed schema the router actually serves
commercetools integration-layer extension invoke-api-extension --deployed --input payloads/cart-create.json   # the deployed handlers; nothing is persisted

EXTENSION_SOURCE_REVISION="$BUILD_ID" \
  commercetools integration-layer extension push --all --wait-timeout 300

The write path in the Commerce Integration Layer

Changing commercetools write behavior

1. Start with a Managed API Extension

Two conditions put a requirement beyond an API Extension:

• The field is immutable once set. An extension firing after the fact cannot change it, so the value must be right on the incoming draft or action.
• The request must be valid on arrival. commercetools validates a request before any extension runs, so a value the request needs in order to pass validation has to be on it already.

If neither condition holds, build a Managed API Extension and stop here.

2. Reach out to commercetools support

If an API Extension cannot solve it, contact commercetools support with the use case before building anything else. Describe the business requirement, not only the field you want to set: the right answer is often a modeling option or feature that makes custom logic unnecessary.

3. Final step: override the existing mutation with @override

It is the final step because your resolver now owns the whole operation:

• It must keep up with the core mutation. Fields and behavior the core mutation gains later are not inherited automatically. Re-check the override when you update the bundle.
• It only covers traffic through the Experience API. Writes from the Merchant Center or direct API clients do not pass through it, unlike an API Extension.

Writes to an external service provider

Scope the logic to the business action, not the update action

Before you ship, list every entry point for the business action and check that each one is covered.