Automate the pass lifecycle with Flow invocable actions (no code) or Apex (in-org code) — both drive the same engine and the same records. External and custom systems can also integrate through the Kemicard Server; see the note at the end of this page.
Apex — the upsertPasses invocable action
The core entry point for generating and updating passes is the global invocable method
AppleTemplatePassSFObjectDataService.upsertPasses(List<PassRequest>) — surfaced in Flow Builder
as the Generate Pass action (category: Apple/Google Pass). It creates or updates a
Kemicard Apple/Google Wallet pass from a structured pass request and returns a list containing the generated
or updated pass ID.
templatePassId and the Pass Configuration metadata record referenced via
configurationId. The request itself only carries per-invocation context.Request body — PassRequest
| Field | Type | Required | Description & Kemicard behavior |
|---|---|---|---|
configurationId | String | required | Salesforce record ID of the Kemicard Pass Configuration to use. Behavior: drives pass behavior — the referenced configuration record controls how a pass is generated and delivered. It defines the source object for generation and configures campaign manager and scanner usage, pass-field binding, template-field binding, Apple and Google pass generation, email delivery, the relevant date field, and the expiry date field. Changing the configuration record changes the resulting pass without any code change. |
whatId | Id | required | Salesforce record ID (e.g. Order, Contact, custom object) to associate the pass with.
Behavior: the pass is linked to this record for lookup and reporting. All merge fields referenced
in the template (e.g. {!Account.Name}, {!Order.OrderNumber}) are resolved against
this record at generation time. If the configuration uses email delivery, the recipient address is typically
resolved from this record as well. |
templatePassId | String | optional | ID of the template pass record used as the basis for the new pass. The template is normally determined
by the configuration's template binding; this parameter, if provided, overrides that binding.
Behavior: supplies the visual layout, image assets (logo, strip, thumbnail), barcode format, and
any default field values. The newly created pass record inherits these values; per-record merge fields are
then resolved against whatId and written on top. |
passId | String | optional | If provided, the action updates the existing pass record instead of creating a new one. Omit to create a new pass. Behavior: triggers the update path — merge fields are re-resolved, the pass artifact is re-rendered, and (if the configuration enables push notifications) a wallet update push is dispatched to all devices that have installed the pass. The pass record ID is preserved. |
messageValue | String | optional | Push notification body message displayed when an existing pass is updated. Behavior: only
consumed on the update path (when passId is set) — the string is surfaced as the user-facing
notification text on the device when the wallet refreshes the pass. Ignored when creating a new pass. |
Example invocation (Apex)
AppleTemplatePassSFObjectDataService.PassRequest req =
new AppleTemplatePassSFObjectDataService.PassRequest();
req.configurationId = 'a0B000000XXXXXX';
req.whatId = '0010000000ZZZZZZ';
// Optional — set passId + messageValue to trigger an update + push
// req.passId = 'a0D000000PPPPPP';
// req.messageValue = 'Your pass has been updated.';
List<String> result = AppleTemplatePassSFObjectDataService.upsertPasses(
new List<AppleTemplatePassSFObjectDataService.PassRequest>{ req });
String passId = result[0];Response
List<String>— passIds: a single-element list containing the ID of the created or updated pass record. Index 0 holds the pass ID.null: returned when the input list is empty — no pass is created or updated.- Apex exception: thrown on DML errors, invalid IDs, or misconfigured pass templates. Propagates as a Flow fault in screen flow context.
passRequests[0]) is processed per invocation. The action is designed for single-record flow
invocations — passing multiple requests does not generate multiple passes.In Flow Builder the action is registered as “Generate Pass from list of String as pass details” under the Apple Pass category. Prefer clicks over code? See the Flow Integration & Apex Action guide.
Flow invocable actions
The Generate Pass action is the Flow surface of upsertPasses — its inputs are exactly the PassRequest fields documented above (configurationId, whatId, and optionally templatePassId, passId, messageValue).
| Action | Inputs | What it does |
|---|---|---|
| Generate Pass | PassRequest — see field reference above | Creates the pass and writes the signed add-to-wallet URL to the record. |
| Send Message | passId | recordId, message | Push notification to one pass; use Bulk Actions for segments. |
| Switch Template | passId, templateName | Changes an installed pass's design in real time. |
| Expire Pass | passId, expiryDate | Sets or clears expiry; expired passes move to the wallet's expired section. |
Error handling
- 401 Unauthorized — named credential password wrong or user reset; re-enter credentials (see Troubleshooting).
- 409 Conflict — provisioning mismatch; verify Org ID and licensing.
- 429 Too Many Requests — back off; coordinate very large batches with support.
Integrating external systems
Salesforce is Kemicard's native home — but the Kemicard Server sits outside Salesforce and can be integrated with third-party platforms and custom systems using standard RESTful patterns as part of a scoped engagement. If your data lives outside Salesforce, talk to us about an integration project, and see the architecture overview for how the pieces fit.
API FAQ
- Should I use Flow or Apex? Use the Flow action for clicks-not-code automation; use Apex when the invocation lives inside existing trigger handlers or services. Both call the same
upsertPassesengine. - Can I test safely before production? Yes — install in a sandbox org with sandbox credentials; passes generated there never touch your production wallet audience.
