Skip to content

docs(sync): document foreign key resolvers#495

Merged
Soner (shyim) merged 1 commit into
mainfrom
docs/sync-fk-resolvers
May 20, 2026
Merged

docs(sync): document foreign key resolvers#495
Soner (shyim) merged 1 commit into
mainfrom
docs/sync-fk-resolvers

Conversation

@shyim
Copy link
Copy Markdown
Member

Summary

Adds a new Foreign key resolvers section to the Sync API guide (docs/concepts/endpoint-structure/writing-entities/bulk-payloads.md).

The Sync API has supported FK resolvers for a while via ProductNumberFkResolver, but the feature has never been documented. This PR fills that gap and lists the seven new tier-1 resolvers landing in the platform repo:

  • product.number (existing)
  • currency.iso_code
  • locale.code
  • payment_method.technical_name
  • shipping_method.technical_name
  • document_type.technical_name
  • salutation.salutation_key
  • tax.tax_rate

The new section explains the { resolver, value, nullOnMissing } payload shape, lists each built-in resolver with the column it looks up, includes a runnable example using currency.iso_code and tax.tax_rate together, and warns explicitly that tax.tax_rate skips ambiguous rates instead of picking one — a behavior integrators will otherwise hit blind.

Draft until the platform PR for the new resolvers merges, since the resolver names need to match.

Test plan

  • Render the page locally and confirm the table and example code blocks display correctly
  • Cross-check resolver names against the platform PR once merged
  • Verify the warning theme block renders as a callout (matches the existing theme: warning usage in README.md)

Adds a new "Foreign key resolvers" section to the Sync API guide
covering the {resolver, value, nullOnMissing} payload shape and
listing the eight built-in resolvers (product.number plus the seven
new tier-1 resolvers for currency, locale, payment_method,
shipping_method, document_type, salutation, tax).

Includes a warning about tax.tax_rate's non-unique column behavior.
@lasomethingsomething
Copy link
Copy Markdown

cc Patryk Tomczyk (@patzick) Michael Telgmann (@mitelg) Björn Meyer (@BrocksiNet) Martin Bens (@SpiGAndromeda)

Copy link
Copy Markdown

@patzick Patryk Tomczyk (patzick) left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would be nice to update OpenAPI schema with this knowledge, currently it defines pauload as array of objects, so basically anything

"payload": {
                "description": "Contains a list of changesets for an entity. If the action type is `delete`,\n    a list of identifiers can be provided.",
                "type": "array",
                "items": {
                  "type": "object"
                }
              },

current preview of the schema

@shyim Soner (shyim) marked this pull request as ready for review May 20, 2026 05:47
@shyim Soner (shyim) merged commit 76df87f into main May 20, 2026
1 check passed
@shyim Soner (shyim) deleted the docs/sync-fk-resolvers branch May 20, 2026 05:48
Micha Hobert (Isengo1989) added a commit that referenced this pull request May 22, 2026
* [create-pull-request] automated change (#488)

Co-authored-by: shopwareBot <example@example.com>

* [create-pull-request] automated change (#500)

Co-authored-by: shopwareBot <example@example.com>

* docs(sync): document foreign key resolvers (#495)

Adds a new "Foreign key resolvers" section to the Sync API guide
covering the {resolver, value, nullOnMissing} payload shape and
listing the eight built-in resolvers (product.number plus the seven
new tier-1 resolvers for currency, locale, payment_method,
shipping_method, document_type, salutation, tax).

Includes a warning about tax.tax_rate's non-unique column behavior.

* add/ignore-file (#501)

* [create-pull-request] automated change (#498)

Co-authored-by: shopwareBot <example@example.com>

* [create-pull-request] automated change

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: shopwareBot <example@example.com>
Co-authored-by: Soner <github@shyim.de>
Co-authored-by: Micha Hobert <m.hobert@shopware.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants