When do I need to submit the package ID as part of the template id for JSON API transactions?

You have to submit the package id if the pair (moduleName, templateName) is not unique among all DAML-LF packages uploaded to the ledger. I would generally recommend that you always include the package id for production applications but for testing and debugging it’s of course totally fine to omit it.

As for getting access to the package id, if you can I would recommend to use the JavaScript codegen which will automatically include this on all requests. If that is not an option for whatever reason, you can use daml damlc inspect-jar --json .daml/dist/mydar.dar to print out the package id. The main_package_id in there is the one of your current project but you also get the package id of your dependencies. If you want to extract it automatically, something like jq or your favorite JSON library will do the job.

4 Likes