event_id, store the submission result, and control retries from the merchant backend.XPay preserves the merchant-provided event_id, but the meter-event endpoint doesn't enforce uniqueness. Duplicate prevention is therefore a merchant responsibility.
Generate a stable event ID
Create one stable event_id for every logical usage event. Good identifiers are based on a durable merchant record, for example:
api-request-{{request_id}}transaction-{{transaction_id}}storage-snapshot-{{snapshot_id}}
Don't generate a new event ID each time the same event is retried.
Store submission state
For each event, store:
event_id- Meter ID
- Subscription ID
- Operation and value
- Event timestamp
- Submission state
- XPay response
Mark the event as submitted only after XPay returns a successful response.
Handle an uncertain response
event_id for the same logical usage event after an uncertain response.When the merchant doesn't know whether XPay accepted a request:
- Record the submission outcome as unknown.
- Don't immediately submit a new event with a new
event_id. - Check the merchant's stored request and response records.
- Repeat the request only when the merchant has established that XPay didn't accept it.
When XPay generates the invoice, compare the aggregate billed usage with the invoice's pricing_model_breakdown. This reconciliation can identify a usage discrepancy, but it can't confirm whether a specific meter event was accepted.
Keep event IDs scoped correctly
Use a globally unique value or include the relevant business scope in the identifier. Avoid short sequential values that can be reused across customers, subscriptions, meters, test mode, or live mode.
Treat test and live submissions as separate records even when they represent the same merchant activity.