docs(sync): document foreign key resolvers#495
Merged
Conversation
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.
5 tasks
Patryk Tomczyk (patzick)
left a comment
There was a problem hiding this comment.
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
Michael Telgmann (mitelg)
approved these changes
May 19, 2026
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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_codelocale.codepayment_method.technical_nameshipping_method.technical_namedocument_type.technical_namesalutation.salutation_keytax.tax_rateThe new section explains the
{ resolver, value, nullOnMissing }payload shape, lists each built-in resolver with the column it looks up, includes a runnable example usingcurrency.iso_codeandtax.tax_ratetogether, and warns explicitly thattax.tax_rateskips 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
theme: warningusage inREADME.md)