Recommended workflow

Use this workflow before creating, editing, or publishing offerings.

The goal is to avoid duplicate offerings, invalid payloads, incomplete translations, and unsafe publishing.

Standard catalog workflow

1. Identify the authenticated company
   Call whoami to confirm the company and available scopes.

2. Read the catalog guidance
   Call catalog-readme before mutating catalog data.

3. Check supported languages
   Call get-supported-languages before creating translations.

4. Search before creating
   Call list-offerings using any available title, SKU, brand, URL, or identifier.

5. Create or choose the offering
   Create a new draft only when no existing offering is a good match.

6. Write core fields
   Use new-offering for initial creation or update-offering-core for main-language scalar fields.

7. Write offering translations
   Use upsert-offering-translations for supported non-main languages.

8. Write attribute bases
   Use upsert-offering-attributes for factual buyer-comparison attributes.

9. Write attribute translations
   Use upsert-offering-attribute-translations for each attribute that needs translated labels, descriptions, or value labels.

10. Check publish readiness
    Always call check-offering-publish-readiness before publishing.

11. Publish only if ready
    Call publish-offering only when readiness returns publishable: true.

12. Fix and retry if needed
    If readiness returns errors, fix the draft and check readiness again.

Create offering workflow

whoami
catalog-readme
get-supported-languages
list-offerings
new-offering
upsert-offering-translations
upsert-offering-attributes
upsert-offering-attribute-translations
check-offering-publish-readiness
publish-offering

Only call publish-offering when publishing was requested and readiness passed.

Revise offering workflow

whoami
catalog-readme
list-offerings or get-offering
update-offering-core
upsert-offering-translations
upsert-offering-attributes
upsert-offering-attribute-translations
check-offering-publish-readiness
publish-offering

When multiple offerings may match the request, do not mutate anything. Ask the user to choose the correct offering.

Translation rules

• Do not include the offering main language in translation payloads.
• Use supported language codes only.
• Offering translations are additive: languages included in a call are replaced, and languages not included are preserved.
• Before publishing, all supported non-main languages must be present.

Attribute rules

• Attribute name is a stable machine key.
• Use the same name to update an existing attribute.
• If an attribute has unit, its value must be a number.
• If an attribute has valueLabel, its value must be a string.
• If an attribute has description, translated descriptions are needed for publishing.
• If an attribute has valueLabel, translated value labels are needed for publishing.

Safe behavior

Do not invent product facts, category codes, HS codes, origin, certifications, quantities, prices, or technical specifications.

When source data is incomplete, leave the offering as draft and report what is missing.