Skip to content

liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/commerce-catalogs

commerce-catalogs

Verified

Standards for managing Liferay Commerce catalogs, products, SKUs, and B2B account onboarding via Headless APIs. Use when the user works with commerce products, variants, options, specifications, product images, or B2B accounts and roles.

Commerce Catalogs

Standards for managing Liferay Commerce catalogs, products, SKUs, and B2B account onboarding via the Headless APIs.

When to Invoke

  • "Manage commerce products", "add a product variant", "create SKUs"
  • "Set product options, specifications, or images"
  • "Onboard a B2B account", "assign account roles"

Product Management via Headless APIs

When programmatically managing products, follow these strict architectural findings:

  • The ERC mandate: the externalReferenceCode (ERC) is the only reliable identifier for a product. Always use the ERC based endpoints (e.g., /products/by-externalReferenceCode/{ERC}) for PATCH, DELETE, and subresource operations to avoid 404 NOT FOUND errors.
  • Product options: options (size, color, etc.) are global, prerequisite entities. They must be created via the global options endpoint before you can link them to a specific product.
  • Specifications: do not use nested POST endpoints for specifications. Instead, PATCH the product itself via its ERC and supply a productSpecifications array containing the specificationKey and value.

REST Gotchas (headless-commerce-admin-catalog)

Verified on 2026.Q2 during a bulk migration of more than 500 products:

  • externalReferenceCode and SKU are VARCHAR(75) — longer values fail with 500 on create. Cap at 75 (shorten longer ones with a hash suffix).
  • POST /products with a defaultSku string creates the default SKU automatically, at price 0. Set its price via PATCH /skus/by-externalReferenceCode/{erc} — do NOT POST a second SKU.
  • Specification keys are lowercased on create (productLine → productline); reference the lowercase key or the attach silently skips.
  • Categories attach by numeric id only: categories must already exist (in a site or asset library vocabulary — you cannot create a vocabulary in the catalog group itself), then PATCH /products/by-externalReferenceCode/{erc}/categories with [{"id": <categoryId>}]. Attaching by name returns 500. Attaching a category from a vocabulary in another scope (site vocabulary → catalog product) works. The PATCH replaces the full category set.
  • relatedProducts needs the numeric productId of the related product — ERC alone fails "productId must not be null".
  • productOptions POST expects an ARRAY of ProductOption (a single object fails "Unable to map JSON path").
  • Variant skuOptions want the CPDefinitionOptionRel IDs, not the global option ID: optionId = the CPDefinitionOptionRel ID (the id returned when the option was attached to the product) and optionValueId = the productOptionValue ID — or use the key form {"key": "<optionKey>", "value": "<valueKey>"}. Passing the global CPOption ID is silently dropped (200, no CPInstanceOptionValueRel) and reads as "variants do not persist over REST". POST a SINGLE Sku object, not an array.
  • /products list caps pageSize at 500 (silently, even if you ask for more) — paginate for a complete ERC→ID map.
  • The product list returns both id and productId — correlate on productId. id is the internal CPDefinition ID; SKU, pricing, and attachment operations key on productId, and mixing them up produces writes to the wrong target that look successful.
  • Order updates accept only PATCH: PATCH /o/headless-commerce-admin-order/v1.0/orders/{id} works; PUT returns 405.
  • Single catalog reads are the singular path: /catalog/{id} or /catalog/by-externalReferenceCode/{erc}; /catalogs/{id} 404s.
  • The batch engine works for bulk loads: POST /products/batch (also /products/skus/batch, /options/batch, …) → 202 + async ImportTask; poll /o/headless-batch-engine/v1.0/import-task/{id} for COMPLETED (then check failedItems — COMPLETED alone is not success).

Catalog vs. Channel Scoping

Three verified boundaries decide where things live:

  • The storefront scopes by CHANNEL, not catalog. A product with the Visibility → Channels filter OFF appears in every channel, whatever catalog it is in; the delivery search filters on commerceChannelGroupId only. The admin Products portlet scopes by catalog — which is why catalog segregation by brand works for catalog managers but does not fence the storefront.
  • Price lists are scoped at the catalog group level. Price resolution walks the SKU's catalog group, so a price list in catalog A is never found for a SKU in catalog B — you cannot move a product between catalogs without orphaning its tier prices (the SKU base price travels; tiers do not).
  • The storefront "Catalog" facet is aggregationTerms=groupId on the delivery /products endpoint (the catalog group ID — commerceCatalogId returns empty facet values in the delivery index). The product payload also carries catalogName for labels.

A Site's Channel From a Site Initializer

A site initializer's tree can create the site's channel: site-initializer/commerce-channel.json, which the Commerce extender upserts by site. It takes Channel's own fields only, and every later run PUTs it, which clears the price display type and the discount target (verified on 2026.Q3). The format and every behavior are documented in rules/site-initializer-format.md → "commerce-channel.json". Without a channel, the account selector fragment renders "This site does not have a channel" and Liferay.CommerceContext.account is empty, so fragment JS that reads the selected account gets nothing.

Storefront, Pricing Visibility, and Checkout

  • To hide prices from guests, revoke Guest VIEW_PRICE on the com.liferay.commerce.product root resource (at the company level). It is a permission, not a channel or OSGi config, and survives site reprovision.
  • A buyer persona needs the "Buyer" account role (grants CHECKOUT_OPEN / VIEW_OPEN_COMMERCE_ORDERS) — "Account Administrator" alone is not enough, and portal admins bypass account role checks entirely, so "works as admin" proves nothing about the buyer flow.
  • A failure of a validator at the order level (e.g., minimum-order-amount) 302s checkout back to the cart with NO message — the Mini Cart submit stays enabled because its canSubmit only inspects the errors of individual items. Diagnose via the CommerceOrderValidatorRegistry (Groovy). The minimum order rule type is minimum-order-amount (not order-limit), one rule per currency.
  • Checkout cannot be fully driven headlessly. Payment methods, shipping methods, and shipping rate rows have no REST create (Control Panel or a commercePaymentIntegration/commerceShippingEngine CET). The headless-commerce-delivery-cart endpoint POST /carts/{id}/checkout is a light transition that skips validators at the order level — for enforced placement use CommerceOrderEngine on the server. PATCH /carts/{id} silently does nothing with shippingOption/shippingMethod (paymentMethod and inline addresses DO persist) — always verify with another GET. To create a cart, POST /channels/{channelId}/carts with accountId in the body; when adding an item, options is a JSON string ([{"key": "finish", "value": ["black"]}]), required for option products.
  • The headless-commerce-delivery-catalog /products endpoint 404s for an authenticated session with no account context (guests get the anonymous fallback). Resolve the current account via /channels/{id}/accounts first and pass accountId. In storefront fragment JS the active account is also available on the client as Liferay.CommerceContext.account.accountId (guard for null when no account is selected).
  • headless-commerce-admin-order account filtering can silently do nothing — a filter=accountId eq ... has been observed returning unfiltered results on some versions. When correctness matters, fetch with pageSize=100 + pagination and filter on order.accountId on the client, or verify the filter against your version before trusting it.

Image Management

  • Direct upload: for robust image handling, Base64 encode the image content and use the /products/by-externalReferenceCode/{ERC}/images/by-base64 endpoint.
  • Persistence: always include "neverExpire": true in the image payload to prevent the image from disappearing over time.
  • Update workflow: to replace an image, first GET the existing images, DELETE them via the attachment endpoint, then perform a new POST with the updated content.

SKU Engineering

Creating variant SKUs (e.g., different pack sizes) is a multistep process:

  1. Attach option: PATCH the product via its ERC to attach a global Option ID.

  2. Add option values: POST to the productOptionValues endpoint to define the specific variants (e.g., "10 pack", "20 pack").

  3. Create SKU: POST the SKU directly to the product's SKUs endpoint, including the skuOptions block to map the specific optionValueId.

Price Lists — Use v2.0, Not v1.0

The headless-commerce-admin-pricing v1.0 endpoint that creates price lists is defective: it 403s every caller, including full admins (transposed group ID arguments route the permission check against group 0). Use v2.0 instead, and prefer PUT by external reference code, which upserts idempotently. Two v2.0 quirks: numeric id fields are checked by Bean Validation even when addressing by ERC (send them anyway), and the catalog read is the singular /catalog/{id} path. Reading the account groups relevant to price lists additionally requires the VIEW_ACCOUNT_GROUPS permission.

B2B Account Onboarding

When onboarding accounts and users via headless-admin-user APIs, adhere to these validation rules:

  • Postal addresses:
    • addressCountry: must match Liferay's internal name exactly (e.g., "United Kingdom", not "GB").
    • addressRegion: must perfectly match Liferay's region dictionary (e.g., "London, City of").
    • addressType: must be lowercase (e.g., "billing", "shipping").
  • User association: use the by-email-address endpoint to associate an existing user with an account: POST /accounts/{accountId}/user-accounts/by-email-address/{email}.
  • Role assignment: assign account roles by their ERC: POST /accounts/{accountId}/account-roles/by-external-reference-code/{ROLE_ERC}/user-accounts/{userId}.

Account Membership and Logos

  • Membership by ERC: POST /accounts/by-external-reference-code/{accountErc}/user-accounts/by-external-reference-code/{userErc} answers 204, and 204 again when the user is already a member, so it is safe to repeat. A user's own GET /user-accounts/{id} lists the result in accountBriefs[].externalReferenceCode. An account PUT that carries no accountUserAccounts keeps the members (verified on 2026.Q3).
  • Logos: logoBase64 alone sets nothing on an account that has no logo. A PATCH with only logoBase64 answers 200 and leaves logoId at 0, because the resource treats a missing logoId and logoExternalReferenceCode as a request to delete the logo. Set the logo at creation (POST takes logoBase64 directly), or name a Documents and Media file in the company group with logoExternalReferenceCode. Read logoId back to confirm. A later PATCH without logo fields keeps the logo. A full PUT (including the site initializer's accounts.json upsert) deletes it unless the body names a logo file.

Success Signal

TODO / inferred — verify against a running bundle. Confirm the created catalog, products, and SKUs list via the Commerce headless APIs and appear under Commerce → Catalogs in the Control Panel.

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall