Enterprise Commerce

Enterprise Commerce is an open-source, enterprise-grade Next.js template designed for high-performance e-commerce. It uses a decoupled architecture:

• Shopify: Acts as the e-commerce backend for product data and categories.
• Algolia: Serves as the data middle-layer for fast-lookup tasks including searching, faceting, filtering, and recommendations.
• Next.js (App Router): Powers the storefront with optimized rendering strategies.

This architecture is designed to handle massive product volumes and complex search/filter combinations with minimal latency.

To set up the Enterprise Commerce application, follow the detailed instructions provided in the official documentation at docs.blazity.com.

Alternatively, you can deploy the project directly to Vercel using the one-click deployment button available in the repository.

The Cart object represents the user's current shopping session.

Cart Structure

• lines: A connection of BaseCartLine objects representing items in the cart.
• cost: The CartCost of the cart.
• buyerIdentity: Information about the customer or their location.
• discountCodes: Applied discount codes.

Cart Line Items

Each BaseCartLine includes:

• merchandise: The product/variant being purchased.
• quantity: The number of items.
• cost: The CartLineCost.
• Deprecated: Use cost instead of estimatedCost.

Cart Operations and Errors

Mutations for updating the cart (like CartLinesAddPayload or CartLinesUpdatePayload) return userErrors of type CartUserError.

Common CartErrorCode values:

• INVALID
• INVALID_DELIVERY_GROUP
• INVALID_MERCHANDISE_LINE
• MISSING_DISCOUNT_CODE
• PAYMENT_METHOD_NOT_SUPPORTED

The API provides types for managing blog content.

Article

An Article contains content, metadata, and author information.

• Deprecated: Use authorV2 instead of author.
• Fields: content, contentHtml, excerpt, handle, publishedAt, tags, etc.

Blog

A Blog acts as a container for Article objects.

• Fields: articles (a connection), authors, handle, title.

Sorting Articles

When querying articles, you can use ArticleSortKeys to sort the results:

• AUTHOR
• BLOG_TITLE
• ID
• PUBLISHED_AT
• RELEVANCE
• TITLE
• UPDATED_AT

export enum ArticleSortKeys {
  Author = "AUTHOR",
  BlogTitle = "BLOG_TITLE",
  Id = "ID",
  PublishedAt = "PUBLISHED_AT",
  Relevance = "RELEVANCE",
  Title = "TITLE",
  UpdatedAt = "UPDATED_AT",
}

Shopify uses Metafields and Metaobjects to extend data models.

Metafields

Metafields are key-value pairs attached to resources like Product, Customer, or Order.

• Metafield: Contains id, key, namespace, type, and the value (as a string).
• MetafieldReference: A metafield can reference other entities like Collection, ProductVariant, or MediaImage.
• HasMetafields: An interface implemented by resources that support metafields.

Metaobjects

Metaobjects allow you to define custom data structures.

• Metaobject: Contains a type (the definition handle), fields (an array of MetaobjectField), and a handle.
• MetaobjectField: Represents a specific field within a metaobject definition.

Collections group products together.

Collection

A Collection includes:

• products: A connection to the products within the collection.
• handle: The unique identifier for the collection.
• title: The display name.
• description: Text and HTML descriptions.

Sorting Collections

Use CollectionSortKeys to order collections:

• ID
• RELEVANCE
• TITLE
• UPDATED_AT

export enum CollectionSortKeys {
  Id = "ID",
  Relevance = "RELEVANCE",
  Title = "TITLE",
  UpdatedAt = "UPDATED_AT",
}

Selling plans (subscriptions or special offers) can include price adjustments. These adjustments are represented by the SellingPlanPriceAdjustment type, which uses a union type SellingPlanPriceAdjustmentValue.

Available adjustment types include:

• SellingPlanFixedAmountPriceAdjustment: A specific amount subtracted/added.
• SellingPlanFixedPriceAdjustment: A fixed price for the plan.
• SellingPlanPercentagePriceAdjustment: A percentage-based adjustment.

Additionally, SellingPlanAllocationPriceAdjustment provides details on how the price is adjusted per delivery, including compareAtPrice, perDeliveryPrice, and price (all as MoneyV2).

export type SellingPlanPriceAdjustmentValue =
  | SellingPlanFixedAmountPriceAdjustment
  | SellingPlanFixedPriceAdjustment
  | SellingPlanPercentagePriceAdjustment;

When running the sync script, keep the following error handling behaviors in mind:

• Execution Failures: The script uses a top-level try/catch block. If an error occurs, it will log the error and exit with a non-zero exit code.
• Empty Datasets: The script is designed to handle empty datasets from Shopify gracefully without crashing.