Skip to content

Product Documents

You can maintain typed product documents on a BC item – datasheet, manual, declaration of conformity, safety data sheet, brochure, and more. The Shopware 6 connector uploads these documents into the shop's own media and links them via custom fields on the product. Customers find the downloads publicly on the product page.

Maintained centrally in the hub

The documents live centrally in the merchantCENTRAL Hub per BC item (ALN MC Product Document) and are therefore available to all marketplace connectors – not just Shopware. The connector transfers them to the shop.

Opening the page

  • Product documents are maintained on the BC item (hub feature "Product Documents").
  • Transfer happens during the item upload to the shop; the per-shop storage status is tracked internally in Shopware 6 Product Document Media.

Sources

Each document line has a source – in all cases the file ends up in the shop media (no dead links, shop CDN/caching included):

Source Storage
BC item attachment Standard attachments (Document Attachment) on the item
Hub file Media field directly on the document line in the hub
External URL just the link (manufacturer PDF); Shopware fetches the file itself (upload-from-URL)

Settings (setup / per shop)

Field Where Description
Sync Product Documents Shop (override) Whether product documents are uploaded to this shop on item push (Default / Yes / No).
Product Documents Field Name Setup / Shop Technical Shopware custom field that receives the document list as JSON text (field type text – the Shopware admin offers no JSON field type; the theme decodes the text). Default ad_documents – set it to the target theme's custom field.
Datasheet URL Field Name Setup / Shop Custom field for the primary datasheet URL. Default ad_datasheet_url.
Upload Documents to Shop Setup / Shop (override) Separate toggle: uploads posted invoices/credit memos as PDF to the shop order (not to the product).

Only changed documents

Unchanged documents are skipped on re-upload (per-shop timestamp comparison). A newer document in the hub triggers a re-upload automatically.

Workflow

  1. Maintain the product documents on the BC item (choose a source per line).
  2. In the shop setup, set the matching custom field (theme) under Product Documents Field Name.
  3. Leave Sync Product Documents at Default or Yes per shop.
  4. Upload the item – the documents are loaded into the shop media and linked on the product.
  5. Display the documents on the product page in the storefront/theme (theme-dependent).

Data format (for theme developers)

The custom field carries the document list as JSON text, an array of objects:

[
  {
    "type": "manual",
    "typeLabel": "Manual",
    "title": "User guide",
    "url": "https://shop.example.com/media/…/user-guide.pdf",
    "mediaId": "018f36cd6a1e7c9b…",
    "position": 1
  }
]
Key Meaning
type Stable, language-independent type key – the theme groups and translates by it (snippets). Values: datasheet, manual, certificate, safety_data_sheet, brochure, other. Unknown future types arrive as other.
typeLabel Type caption in the BC session language – readable fallback for themes without their own snippets.
title Document title (left empty → type caption).
url Public media URL of the file in the shop.
mediaId UUID of the media entity in the shop.
position Sort order from the BC document list.

The second field (Datasheet URL Field Name, default ad_datasheet_url) carries, as plain text, the URL of the first datasheet – for themes that show just one prominent datasheet link.