Skip to main content

Integration contract

Use the API schema and configuration of your installed integration as the source of truth. BoxNCase documentation describes the public integration behavior; it does not introduce renamed third-party packages or alternate API field names.

Call the API directly​

Run authenticated requests on your server. Set COMMERCE_API_URL to the HTTPS GraphQL endpoint and COMMERCE_APP_TOKEN to the installed app's token in your deployment's secret store. These are local configuration names for this example, not HTTP header names supplied by the platform.

const endpoint = new URL(process.env.COMMERCE_API_URL);
if (endpoint.protocol !== "https:") throw new Error("HTTPS is required");
const response = await fetch(endpoint, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.COMMERCE_APP_TOKEN}`,
  },
  body: JSON.stringify({ query: "query ShopName { shop { name } }" }),
});
if (!response.ok) throw new Error("Commerce API request failed");
const result = await response.json();
if (result.errors?.length) throw new Error("GraphQL operation failed");

Grant only the permissions needed by the integration. Customer sessions and app tokens have different scopes; never put an app token in browser code.

Generate types from the deployed schema​

Use schema introspection against the configured endpoint to obtain exact operation, field, input, and type names. Display labels in this documentation describe concepts; they are not substitutes for schema identifiers. Generate client types from the deployed schema before compiling requests.

Configure webhook verification​

Use the signature and event header names supplied by your integration configuration. Verify the raw request body before parsing or processing it. Resolve verification keys only from the trusted API endpoint configured on your server, never an arbitrary URL supplied in an incoming request. Reject invalid signatures and unexpected events, and deduplicate deliveries before processing side effects.

SDK-dependent examples​

Some integration walkthroughs describe SDK behavior using clearly labeled pseudocode. Bracketed values represent deployment-specific packages, helpers, headers, app IDs, or schema fields. Resolve these from the installed integration's configuration and generated types; do not copy bracketed placeholders into a production implementation. The SDK-neutral HTTPS pattern above can be used without adopting an additional SDK.