Back to all articlesAPI integration planning

Preserve dates, times, and numeric meaning across API field mappings

Alactic Editorial10 min read

Prepared with AI assistance by Alactic Editorial. Examples identified as hypothetical are illustrative, not customer results.

A commitment date can move back a day when an integration treats it as midnight in a time zone. A decimal amount can arrive with the right digits but the wrong currency. A measured quantity can remain numerically unchanged while becoming a different physical quantity because its unit disappeared.

To preserve meaning across API field mappings, specify five things before implementing the conversion: what the source value means, how the destination represents it, which transformations are permitted, how much precision may be lost, and when the record must be rejected. Matching field names and data types is not enough.

The worksheet below turns those decisions into an implementable contract. All values, field names, limits, and scenarios in this article are hypothetical worked examples, not product specifications or customer results.

1. Start with meaning, not the visible format

Two fields can both contain 2027-04-18 without representing the same thing. One might mean a promised calendar date. Another might be the date extracted from an event timestamp. The first has no time of day; the second depends on how the event was interpreted.

Likewise, 1250 might mean a decimal amount, an amount in minor currency units, a count, or a measurement. A successful parse proves only that the software accepted the representation. It does not prove that the destination received the intended meaning.

For each field, answer these questions with the person responsible for its business meaning:

  • What does it describe? A calendar commitment, an event instant, a monetary amount, or a measured quantity?
  • What context is essential? Currency, unit, offset, named time zone, or measurement resolution?
  • Which distinctions must survive? Unknown versus zero, date-only versus midnight, or source precision versus display precision?
  • What may change? Formatting, unit representation, offset representation, or rounding under an explicitly agreed rule?

Put the answers beside the mapping, not only in a meeting note. Otherwise, a later change can preserve the data type while silently changing the contract.

2. Use a filled conversion worksheet

Fictional worked example: an integration transfers a service commitment, a recorded event, a quoted amount, and a package measurement. The destination accepts a date field, a UTC timestamp with milliseconds, a two-decimal amount with a separate currency field, and an integer measurement in grams.

The following entries are a filled artifact that a team could adapt for its own mapping review. Each entry includes a source value, destination output, conversion rule, precision boundary, and failure condition.

Worksheet A: Date-only commitment

Source field: commitment_date
Source value: "2027-04-18"
Source meaning: Calendar date on which service is promised;
               not an event instant and not midnight.
Destination field: promised_date
Destination representation: Date-only string, YYYY-MM-DD
Expected output: "2027-04-18"
Conversion rule: Validate calendar date; preserve year, month, day.
Time-zone rule: Do not apply an offset or time-zone conversion.
Precision limit: One calendar day; no time component exists.
Missing-value rule: Missing or null means no commitment recorded;
                    empty string is invalid.
Reject when: Date is impossible, format is ambiguous, or a time
             component is supplied without an agreed interpretation.
Owner: Service operations
Acceptance check: Output date equals source date exactly.

Worksheet B: Timestamp with an offset

Source field: event_recorded_at
Source value: "2027-04-18T09:10:11.250+05:30"
Source meaning: The instant when an event was recorded.
Destination field: event_recorded_at_utc
Destination representation: UTC timestamp with milliseconds
Expected output: "2027-04-18T03:40:11.250Z"
Conversion rule: Parse the explicit offset; convert the same instant
                 to UTC; retain the source offset in mapping metadata.
Precision limit: Milliseconds; nonzero finer digits are rejected.
Missing-value rule: Required; missing or null blocks this record.
Reject when: Offset is absent, timestamp is invalid, precision would
             be lost, or the instant exceeds destination range.
Owner: Integration engineering
Acceptance check: Source and output identify the same instant.

Worksheet C: Decimal amount with currency

Source fields: quoted_amount, quoted_currency
Source values: "1234.56", "USD"
Source meaning: Quoted amount expressed in major currency units.
Destination fields: amount_decimal, currency_code
Destination representation: Exact decimal with two fractional digits;
                            separate validated currency code.
Expected output: "1234.56", "USD"
Conversion rule: Parse as decimal, not binary floating point;
                 carry currency with amount; perform no FX conversion.
Precision limit: Two fractional digits; no implicit rounding.
Allowed example range: 0.00 through 999999.99
Missing-value rule: Amount and currency must both be present.
Reject when: Currency is unsupported, amount is out of range,
             amount is negative, or nonzero extra decimals exist.
Owner: Quoting operations
Acceptance check: Decimal value and currency both match the source.

Worksheet D: Measured quantity with units

Source fields: package_mass, package_mass_unit
Source values: "12.345", "kg"
Source meaning: Package mass recorded to 0.001 kg resolution.
Destination fields: mass_value, mass_unit
Destination representation: Integer grams plus explicit unit
Expected output: 12345, "g"
Conversion rule: Multiply the exact decimal value by 1000;
                 require an integer result; do not round.
Precision limit: One gram; no finer measurement may be discarded.
Allowed example range: 1 through 1000000 g
Missing-value rule: Value and unit must both be present.
Reject when: Unit is missing or unsupported, result is fractional,
             result is out of range, or quantity is negative or zero.
Owner: Fulfilment operations
Acceptance check: Convert output back to kg; result equals 12.345.

The ranges and negative-value restrictions above are business choices for this fictional workflow. They are not universal rules for amounts or measurements. Replace them deliberately rather than carrying them into a different use case unnoticed.

3. Keep date-only values out of timestamp conversions

A date-only commitment should usually remain a date-only value. Adding midnight makes a new assertion: that the date refers to a specific time in a specific zone. Converting that invented instant elsewhere can then change the calendar date.

If a destination offers only a timestamp field, do not quietly append T00:00:00Z. First determine whether another destination field or an additional date-only representation can preserve the original meaning. If neither is available, treat the mismatch as a design decision requiring approval, not a formatting fix.

A documented compromise might retain the original date in a separate supported field while storing a derived timestamp for a restricted technical purpose. That derived value must not become the authoritative commitment date. If downstream consumers cannot maintain that distinction, block the mapping.

Also define accepted input formats. An ambiguous value such as 04/05/2027 should not be interpreted using the integration server's locale. Either establish a source-specific format or return an error that identifies the ambiguity. Accommodating known formats is different from guessing.

4. Preserve the instant without inventing a time zone

For an event timestamp, the invariant is usually the instant, not the displayed clock time. In Worksheet B, 09:10:11.250+05:30 and 03:40:11.250Z represent the same instant. Copying the clock digits and replacing the offset with Z would change the event time.

An explicit offset is enough to locate that event instant, but it does not identify a named time zone or its rules. Do not infer a geographic zone from an offset. Retain a supplied named zone separately when the source meaning requires it.

A local date-time without an offset needs a different contract. If it is meant to identify an instant, the mapping needs an authoritative zone and a rule for local times that are ambiguous or do not exist during clock changes. If it is intentionally just a local clock reading, keep that meaning rather than manufacturing an instant.

Precision needs the same discipline. If a source supplies finer-than-millisecond timestamps but the destination stores milliseconds, choose explicitly between rejection and an approved loss of precision. For event ordering, truncation may collapse distinct events into the same stored timestamp. Retaining the source timestamp or a separate ordering key may be necessary; adding invented fractional digits is not a remedy.

5. Treat currency and units as part of the value

An amount without currency and a quantity without units are incomplete mappings. Keep the context coupled to the value through validation, conversion, and writing. A partial update that changes an amount but leaves an old currency can be more misleading than a rejected record.

For decimal amounts, separate storage precision from display formatting. Displaying two decimal places does not prove that the underlying value has two-decimal precision. Use decimal arithmetic or a validated scaled-integer representation when the contract requires exact decimal values.

Do not assume that every currency or destination uses the same scale. Worksheet C deliberately allows only a specified currency and two decimals. A broader mapping needs an explicit supported-currency and scale policy. Converting major units to minor units is also a transformation, not merely a field rename.

For measurements, validate the unit before applying a conversion. Worksheet D's multiplication applies to kilograms and grams; it cannot safely process an unlabeled value. Other unit conversions may require more than multiplication, so an approved conversion registry is safer than a universal factor field.

Where rounding is allowed, specify the stage, scale, and tie-breaking method. In a hypothetical two-decimal conversion, 1234.565 becomes 1234.56 under round-half-to-even and 1234.57 under round-half-up. Neither rule should be selected accidentally by a programming language's default. Worksheet C instead rejects that input.

6. Reject unsafe conversions without losing the record

Rejection should prevent a misleading write while leaving a clear path to correction. For each failed conversion, record the field, source representation, reason, mapping version, and correction owner. Retain only the context needed for diagnosis, with appropriate access and retention controls.

Use reasons that distinguish the underlying problem:

  • Missing context: an amount has no currency or a measurement has no unit.
  • Ambiguous interpretation: a date format or local time has multiple plausible meanings.
  • Unsupported precision: the destination cannot represent the value without an unapproved change.
  • Out of range: the converted value exceeds the agreed destination or business limit.
  • Invalid representation: the input cannot be parsed under the documented contract.

Decide whether one invalid field blocks the entire record. Related value-and-context fields should not be written independently. Where the destination cannot update them together, design a controlled recovery path rather than leaving a mixed state.

Retrying unchanged data will not fix an absent unit or excessive precision. Route those cases for correction. Before replaying a corrected record, establish whether any earlier write succeeded and use the integration's agreed duplicate-prevention mechanism. Keep the original failure linked to the corrected attempt so reviewers can understand what changed.

7. Test semantic equality, not just successful writes

A destination accepting a value is only the first check. Read it back and compare the meaning against the worksheet. Test the actual source, transformation, destination storage, and read-back path: any of them may alter formatting or precision.

For the fictional worksheet, a minimum acceptance pack includes:

  1. The date-only commitment remains 2027-04-18, regardless of the integration host's time-zone setting.
  2. The offset timestamp returns as the same instant with milliseconds intact.
  3. An offset-free event timestamp is rejected rather than assigned the host's zone.
  4. 1234.56 USD survives exactly, while 1234.565 USD is rejected.
  5. 12.345 kg becomes 12345 g; 12.3456 kg is rejected because it requires fractional grams.
  6. Missing, null, empty, and zero values follow their separate documented rules.
  7. Values at each agreed range boundary pass, while values just outside fail with the expected reason.

Round-trip checks are useful but insufficient on their own: a forward and reverse conversion can share the same mistaken assumption. Keep independently calculated expected outputs, such as the UTC timestamp in Worksheet B, in the acceptance pack.

8. Make the worksheet the release gate

Before releasing a mapping change, have the business owner confirm meaning and the implementation owner confirm representability. Version the worksheet alongside the transformation so a changed scale, unit, or time-zone assumption is visible during review.

As a concrete next action, select one temporal field and one numeric field from an integration under review. Fill every worksheet line, calculate the expected destination values independently, and run both accepted and rejected cases through a read-back test.

Measure three outcomes: every selected field has an explicit meaning and conversion rule; every accepted test preserves the agreed invariant; and every unsafe case is blocked with an actionable reason. Any silent rounding, guessed zone, or missing unit is a release issue—not a cosmetic discrepancy.

API integrationField mappingData qualityTime zonesNumeric precision

Put the next conversation to work.

Explore Alactic Communications for WhatsApp conversations, campaigns and AI-assisted workflows. Choose the product and plan that fit your team.

Explore Communications