Use a Transformation when Payloads needs to change a value before sending it, returning it, or saving it.

Transformations are Integration-level records. That means several Payloads in the same Integration can reuse the same rule where the same value conversion applies. This is useful for things like amount formatting, status mapping, date formatting, or API-specific naming rules that would otherwise be repeated across several mappings.

A good Transformation should make the intent obvious. When another admin sees it attached to a Body Element, Header, Parameter, Modifier, or Data Target field, they should be able to understand why the value changes.

Use a Transformation when the source value is not the final value the target system or Salesforce field expects.

Common examples include:

Do not use a Transformation just to move a value from one place to another. If the value can be mapped directly, map it directly. Transformations are most helpful when they capture a real rule, not when they hide a simple mapping.

Payloads supports Salesforce Formula and Payloads Formula transformations.

Use Salesforce Formula when the transformation fits Salesforce's formula expression model and return types. Use Payloads Formula when the transformation needs Payloads-specific formula behaviour, options, or structured inputs.

The older Formula value may appear in metadata for compatibility. For new configuration, choose the current option shown in the UI.

Set the Input Type to the kind of value the transformation expects.

Supported input types include Boolean, Date, Date/Time, Number, Id, String, Time, Array, and Object.

Set the Return Type to the kind of value the transformation should produce.

The return type matters because downstream mappings depend on the output. For example, a Target Field mapped to a Salesforce checkbox should receive a boolean value, not the text true. If the return type does not match the destination, the Payload may build successfully but fail at runtime.

Write the formula for one focused conversion.

Keep transformation names specific. Convert Amount To Stripe Minor Units is easier to review than Amount Formula, because it tells the next admin what business or API rule the formula represents.

If the transformation uses options, configure those options from the formula options panel so the purpose of each option is visible to the next admin.

The Transformation page keeps the formula, expected input type, return type, helper menus, preview, and syntax check actions in one place.

Transformations can be attached to values in Body Elements, Headers, Parameters, Modifiers, and Target Fields.

Use the Transformation close to the mapping that needs it. That keeps the configured source value and the conversion rule visible together during review. If the same conversion is needed in several places, reuse the Transformation instead of creating several slightly different versions.

Use transformations where the mapped source value needs to be adjusted before Payloads uses it.

Use the Transformation UI to check syntax or run a test value where available.

Then test the Payload and review the Job. The Job shows the final body, headers, parameters, modifiers, target output, and error message if the transformation failed during runtime. The Job is the best place to confirm whether the transformed value ended up in the right part of the request or target record.

For runtime troubleshooting, see Troubleshoot Payload mappings with Job data.

Before using a Transformation in a live Payload, check that:

If a transformation is used by several Payloads, review each usage before changing it.