Call Shopify

Two APIs, one store connection#

Use await shopify.admin.graphql(query, variables) for Admin operations and await shopify.storefront.graphql(query, variables) for published catalog data and carts. Littleworks manages the existing store connection and keeps credentials outside your code. Both APIs use version 2026-07. The result is Shopify’s raw GraphQL envelope, including data, errors, and extensions when present.

const result = await shopify.admin.graphql(query, variables);

if (result.errors?.length) {
  throw new Error("Shopify could not complete the request");
}

return result.data;

The snippet assumes you have defined a query and its variables for what you’re building. Use Shopify’s Admin GraphQL reference for operation-specific fields and required access scopes. Mutations may also return operation-specific userErrors inside data; inspect those too.

Declare permission explicitly#

Set permissions.shopify to true in the manifest. This enables both clients for the work; it does not grant new Shopify scopes. The store installation’s approved scopes remain the outer limit. Read get_context to see those scopes before planning an operation.

{
  "permissions": { "shopify": true }
}

The required scopes are write_app_proxy for the shared storefront route, unauthenticated_read_product_listings for Storefront catalog access, and unauthenticated_write_checkouts for carts (including reads). Admin data scopes are optional. Open Littleworks → Agent access → Permissions to see required access and configure optional Admin and Storefront permissions. Editing includes viewing. Permissions apply to all works with Shopify access enabled, in test runs and real runs. Removing access can stop dependent works.

When a build needs more access#

Agents should read get_context.shopify.permissions: granted is the current Shopify access when verified is true, optional lists the scopes Littleworks can request, and manageUrl opens this store’s Permissions page. Explain the minimum scopes needed and send that link to the merchant. After they approve in Shopify, call get_context again to verify access. A failed verification is not an empty grant list; refresh before proceeding.

Optional Admin permissions cover products, inventory, locations, metaobjects and their definitions, content, files, discounts, orders, order edits, merchant-managed and third-party fulfillment orders, fulfillments, customers, and draft orders. Customers, locations, and fulfillments offer viewing only. Other listed resources also offer editing. Scopes outside this set are not currently available. Protected customer data still requires separate Shopify approval, and normal order-history restrictions apply.

For order routing and order operations, ask only for what the build uses. write_orders covers tagsAdd and tagsRemove on orders, orderUpdate, orderClose, and orderCancel. write_order_edits covers order editing (orderEditBegin through orderEditCommit). write_merchant_managed_fulfillment_orders covers fulfillment orders at the store’s own locations, and write_third_party_fulfillment_orders covers those at locations run by fulfillment services; either lets a work move (fulfillmentOrderMove), hold, release, or reschedule those fulfillment orders. Creating fulfillments with fulfillmentCreate works for merchant-managed fulfillment orders; Shopify leaves fulfilling a fulfillment service’s orders to that service. Orders are available for the last 60 days: read_all_orders needs Shopify’s approval for Littleworks, which it does not have, so it is not offered.

For uploads, shopify.files wraps Shopify’s Files API: the browser uploads straight to Shopify and a work saves the file. See Store files.

Optional Storefront read permissions cover content and navigation, metaobjects, inventory quantities, pickup locations, product tags, selling plans, and Shop Pay installment pricing. These use unauthenticated_* scope names and are independent of Admin scopes. Littleworks does not request Storefront customer scopes or provide a Customer Account API client.

Read the catalog or work with carts#

const result = await shopify.storefront.graphql(
  `query Catalog($count: Int!) {
    products(first: $count) { nodes { id title handle } }
  }`,
  { count: 5 },
);
if (result.errors?.length) throw new Error("Catalog request failed");
return result.data;

Use Shopify’s Storefront GraphQL reference for product discovery and cart operations such as cartCreate, cartLinesAdd, and cartLinesUpdate. Admin and Storefront have different schemas. Storefront product visibility depends on publication and market context; use @inContext for language or country. A product missing from Storefront results can be a publication or market issue, even when Admin can read it.

Storefront calls use a private token held by Littleworks. No extra token or Headless channel setup is needed. For shopper-triggered direct public/token HTTP requests and verified app-proxy requests, Littleworks forwards the buyer IP when available, and for a headless storefront’s customer assertion, the buyerIp it signs; callable runs and cached works have no buyer context, so a cached work passes market and language explicitly with @inContext(country:, language:). This helps Shopify apply traffic protections and checkout behavior. It does not authenticate a customer: context.customer.id is not a customer access token and does not automatically sign a buyer into checkout. Treat cart IDs containing keys and checkout URLs as sensitive, and do not log them.

Both clients are subject to Shopify’s API limits. Neither requires the external HTTP feature or spends its request allowance. Requests have a seven-second timeout and a 256 KiB response limit, within the run deadline. There are no automatic retries. Handle HTTP 429 (throttling) and 430 (Shopify security rejection) without blind retries.

Test runs use the real store#

Test runs use the same Shopify connection as real runs. Read-only checks are useful for testing; mutations, when permitted, affect the real store and are not removed by delete_test_records.

Handle failures deliberately#

A work may have already changed a document or completed a Shopify operation before a later error. Check the run and the affected state before retrying. Littleworks does not promise exactly-once external effects or transactions spanning storage and Shopify.

Keep logs operational. Do not log customer payloads, credentials, or full GraphQL responses containing personal data. See Inspect and troubleshoot.