/v2/push endpoint in batches. One component writes one object type: contacts, orders, or custom events.
When to use it
Use this destination to sync customer, order, or event data from your warehouse or other systems into Ometria for segmentation and campaigns. Typical uses:- Load customer profiles from a warehouse table so Ometria profiles stay current.
- Push order history so revenue-based segments and lifecycle stages update after each run.
- Send custom events (for example, subscription renewals or support interactions) that Ometria does not capture natively.
Connection
Select an existing Ometria connection or create a new one. The destination uses the same connection type as the source: a single API key sent as theX-Ometria-Auth header. A key that already works for the source works here unchanged.
See Connecting to Ometria for how to create the connection.
Destination properties
- Object - the Ometria object type this component writes:
contact(default),order, orcustom_event. The object determines which fields you can map (see Field mapping). - Merge mode - when enabled, the component sends each record as a partial update. Ometria updates only the fields present in the record. When disabled, fields you do not map are overwritten to null in Ometria. Enable merge mode when your pipeline carries a subset of the fields a record already has in Ometria.
Advanced options
- Requests per second - throttle applied to the push endpoint. Default is
8, matching Ometria’s documented push rate limit, which is double the read-endpoint limit. Maximum is100. The component posts from a single process, so this value is the real request rate against Ometria. - Records per batch - number of records sent per push request. Default and maximum are both
100, the cap Ometria enforces per request. - Maximum failed records - the job fails once cumulative failed records exceed this value. Default is
0(fail on the first failure). Set to-1for unlimited failures.
Field mapping
Each object type has a fixed payload schema. Map input fields to Ometria fields by exact name. The component raises a build-time error if a required field is missing from the mapping or a mapped field is not supported for the selected object.Contact
Ometria uses the identity fields to cluster contact records into a profile. Without one, the record cannot be matched to a customer.
extra_identifiers is a JSON array of {type, value} pairs and also counts as an identity.
marketing_optin is a string enum. Ometria accepts EXPLICITLY_OPTEDOUT, NOT_SPECIFIED, or EXPLICITLY_OPTEDIN. Any other value fails the row.
@force_optin is a boolean flag that overrides Ometria’s opt-in state. The component accepts a typed boolean column or the text true/false (case-insensitive) and emits a JSON boolean. Any other value fails the row.
Order
Orders need no identity field. The customer travels inside the nested
customer object.
discount, shipping, tax, and store are also mappable under their older spellings discount_total, shipping_total, tax_total, and store_id. Both spellings reach Ometria under the same name. Map one spelling per field: mapping both is rejected when you save the package.
The customer and lineitems fields are JSON fields: the input column must contain a JSON document, not plain text. customer is an object and lineitems is an array of line-item objects. The component embeds these values as structure in the push payload. Ometria rejects a plain-text value in these columns.
is_valid is a boolean flag with the same coercion rule as @force_optin on contacts: a typed boolean column or the text true/false (case-insensitive) is emitted as a JSON boolean, and any other value fails the row.
Custom event
A custom event needs one identity value.
profile_id alone is sufficient.
identity_email, identity_account_id, and identity_phone_number are also mappable under their contact-style spellings email, customer_id, and phone_number. Both spellings reach Ometria under the identity name. Map one spelling per field: mapping both is rejected when you save the package.
properties is a JSON object carrying the event’s attributes. event_type is optional here; Ometria enforces its own requirements when it processes the batch.
JSON fields
The component treats these fields as structured JSON rather than plain text. Map a column that carries a JSON document, or build one in Pig withTOMAP(...) for objects and TOBAG(...) for arrays. A plain-text value in one of these columns fails the row.
- Objects:
customer,properties,channels,subscriptions,shipping_address,billing_address. - Arrays:
lineitems,store_ids,extra_identifiers,@add_to_lists,@remove_from_lists.
properties or rename it before mapping. To put a custom field in properties, build the object with TOMAP('your_field', your_column) rather than mapping a single column to properties directly.
The id field
id is Ometria’s stable identifier for the record. It must not contain PII such as an email address or name. Use an internal key like a database primary key or order number.
Custom fields
The documented home for your own custom fields isproperties, a JSON object on all three record types. Build it in Pig with TOMAP('your_field', your_column, ...) so each custom field becomes a key inside the object.
You can also map a custom field as a flat top-level column. When a mapped column is not in the documented set, the component checks it against your account’s custom fields before rejecting it. If the component cannot fetch the custom-field list (for example, during an Ometria outage), it allows the column with a warning rather than blocking the build. Ometria decides whether it reads a top-level custom field. A rejected record counts toward Maximum failed records.
Error tracking
Enable Track failed records to write a CSV of records that failed to send, one row per failure, to a cloud storage connection and path you choose. Configure the storage connection and output path on the component. Ometria’s push endpoint accepts batches asynchronously: it queues records for processing rather than confirming each one. HTTP-level failures (4xx and 5xx responses) are tracked in the errors CSV. Per-record processing outcomes after Ometria accepts a batch are not visible to the job. Check Ometria’s own import reporting for post-acceptance validation issues.Example: syncing contacts from a warehouse query
A pipeline that reads recently updated customers from a warehouse and upserts them as Ometria contacts:contact and map each aliased column to the Ometria field of the same name. id satisfies the required field and email satisfies the identity requirement. Enable Merge mode so fields not in the query (for example phone_number) keep their current values in Ometria. Enable Track failed records to an S3 bucket so you can review rejected rows after the run.