liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/commerce-catalogs
commerce-catalogs
VerifiedStandards 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}) forPATCH,DELETE, and subresource operations to avoid404 NOT FOUNDerrors. - Product options: options (size, color, etc.) are global, prerequisite entities. They must be created via the global
optionsendpoint before you can link them to a specific product. - Specifications: do not use nested
POSTendpoints for specifications. Instead,PATCHthe product itself via its ERC and supply aproductSpecificationsarray containing thespecificationKeyandvalue.
REST Gotchas (headless-commerce-admin-catalog)
Verified on 2026.Q2 during a bulk migration of more than 500 products:
externalReferenceCodeand SKU are VARCHAR(75) — longer values fail with 500 on create. Cap at 75 (shorten longer ones with a hash suffix).POST /productswith adefaultSkustring creates the default SKU automatically, at price 0. Set its price viaPATCH /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
idonly: categories must already exist (in a site or asset library vocabulary — you cannot create a vocabulary in the catalog group itself), thenPATCH /products/by-externalReferenceCode/{erc}/categorieswith[{"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. relatedProductsneeds the numericproductIdof the related product — ERC alone fails "productId must not be null".productOptionsPOST expects an ARRAY of ProductOption (a single object fails "Unable to map JSON path").- Variant
skuOptionswant the CPDefinitionOptionRel IDs, not the global option ID:optionId= the CPDefinitionOptionRel ID (theidreturned when the option was attached to the product) andoptionValueId= the productOptionValue ID — or use the key form{"key": "<optionKey>", "value": "<valueKey>"}. Passing the global CPOption ID is silently dropped (200, noCPInstanceOptionValueRel) and reads as "variants do not persist over REST". POST a SINGLE Sku object, not an array. /productslist capspageSizeat 500 (silently, even if you ask for more) — paginate for a complete ERC→ID map.- The product list returns both
idandproductId— correlate onproductId.idis the internal CPDefinition ID; SKU, pricing, and attachment operations key onproductId, 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;PUTreturns 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}forCOMPLETED(then checkfailedItems— 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
commerceChannelGroupIdonly. 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=groupIdon the delivery/productsendpoint (the catalog group ID —commerceCatalogIdreturns empty facet values in the delivery index). The product payload also carriescatalogNamefor 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_PRICEon thecom.liferay.commerce.productroot 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 itscanSubmitonly inspects the errors of individual items. Diagnose via theCommerceOrderValidatorRegistry(Groovy). The minimum order rule type isminimum-order-amount(notorder-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/commerceShippingEngineCET). Theheadless-commerce-delivery-cartendpointPOST /carts/{id}/checkoutis a light transition that skips validators at the order level — for enforced placement useCommerceOrderEngineon the server.PATCH /carts/{id}silently does nothing withshippingOption/shippingMethod(paymentMethodand inline addresses DO persist) — always verify with anotherGET. To create a cart,POST /channels/{channelId}/cartswithaccountIdin the body; when adding an item,optionsis a JSON string ([{"key": "finish", "value": ["black"]}]), required for option products. - The
headless-commerce-delivery-catalog/productsendpoint 404s for an authenticated session with no account context (guests get the anonymous fallback). Resolve the current account via/channels/{id}/accountsfirst and passaccountId. In storefront fragment JS the active account is also available on the client asLiferay.CommerceContext.account.accountId(guard for null when no account is selected). headless-commerce-admin-orderaccount filtering can silently do nothing — afilter=accountId eq ...has been observed returning unfiltered results on some versions. When correctness matters, fetch withpageSize=100+ pagination and filter onorder.accountIdon 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-base64endpoint. - Persistence: always include
"neverExpire": truein the image payload to prevent the image from disappearing over time. - Update workflow: to replace an image, first
GETthe existing images,DELETEthem via theattachmentendpoint, then perform a newPOSTwith the updated content.
SKU Engineering
Creating variant SKUs (e.g., different pack sizes) is a multistep process:
-
Attach option:
PATCHthe product via its ERC to attach a global Option ID. -
Add option values:
POSTto theproductOptionValuesendpoint to define the specific variants (e.g., "10 pack", "20 pack"). -
Create SKU:
POSTthe SKU directly to the product's SKUs endpoint, including theskuOptionsblock to map the specificoptionValueId.
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-addressendpoint 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}answers204, and204again when the user is already a member, so it is safe to repeat. A user's ownGET /user-accounts/{id}lists the result inaccountBriefs[].externalReferenceCode. An account PUT that carries noaccountUserAccountskeeps the members (verified on 2026.Q3). - Logos:
logoBase64alone sets nothing on an account that has no logo. APATCHwith onlylogoBase64answers200and leaveslogoIdat0, because the resource treats a missinglogoIdandlogoExternalReferenceCodeas a request to delete the logo. Set the logo at creation (POSTtakeslogoBase64directly), or name a Documents and Media file in the company group withlogoExternalReferenceCode. ReadlogoIdback to confirm. A laterPATCHwithout logo fields keeps the logo. A fullPUT(including the site initializer'saccounts.jsonupsert) 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |