Types and payload
Reference of the values accepted in the two capture channels. Applies to POST /capture/{token}/events and POST /capture/events.
Event fields
Section titled “Event fields”| Field | Type | Limit | Required |
|---|---|---|---|
type | string (enum) | see table below | Yes |
order_ref | string or number | 100 characters | Yes |
event_id | string or number | 64 characters | Yes in the browser, optional on the server |
payload | object | see accepted fields | No |
captured_at | string (ISO 8601) | - | No, and only the server channel uses it |
merchant_id | string (UUID) | - | Server channel only |
order_ref
Section titled “order_ref”It is the order identifier in your system, and it is the only thing that links the event to a transaction. Rapid looks, within your company and the given merchant, for:
- a transaction with
external_idequal toorder_ref - if not found, a transaction with
order_numberequal toorder_ref - if still not found, among transactions with
external_sourceshopify,order_refalso works without the leading#(1001finds#1001, and#1001finds1001) and as the order GID (gid://shopify/Order/<id>orgid://shopify/OrderIdentity/<id>finds<id>)
Always send the same value you used in external_id when creating the transaction. A wrong order_ref does not cause an error in the call: the event is accepted, finds no transaction and is discarded after the correlation window. To fix it, resend through the server with the same event_id and the right order_ref (see Idempotency).
Spaces at the start and end are removed. An integer is also accepted and becomes text (1001 is the same as "1001").
event_id
Section titled “event_id”Event identifier, generated by you. It works as an idempotency key: resending the same event_id for the same merchant does not create duplicate evidence. In the server channel, a resend with another order_ref, or after the event was discarded, replaces the previous send; in the browser, the same event_id is always treated as a repeat.
In the browser channel it is required (the snippet generates a UUID per event). In the server channel, if you omit it, Rapid generates one. Send your own whenever you might resend the same call, that is what guarantees idempotency.
Do not use : in event_id. The character is removed before internal use, which would make two different ids collide.
captured_at
Section titled “captured_at”When the fact happened, in ISO 8601.
| Channel | Behavior |
|---|---|
| Browser | ignored. Rapid records the time the event arrived |
| Server | used as sent. If omitted, the time of the call is used |
If the fact happened before the call (a nightly batch process, for example), use the server channel and send captured_at.
type values
Section titled “type values”| Value | What it records | Browser | Server |
|---|---|---|---|
checkout | Purchase completion, with device data | Yes | Yes |
terms_acceptance | Acceptance of terms, policy or contract | Yes | Yes |
access_log | Access to the product or the logged-in area | Yes | Yes |
usage_log | Actual use of the product or service | Yes | Yes |
delivery_confirmation | Delivery confirmed | No | Yes |
scan | Tracking code scan in transit | No | Yes |
delivery_gps | Delivery coordinate | No | Yes |
The last three exist only in the server channel: they are facts of your operation, not of the buyer’s browser. Using them in the browser channel returns 422 invalid_type.
payload fields
Section titled “payload fields”payload has a closed list of fields. A key outside the list is silently discarded, with no error, so check the spelling.
| Field | Type | Use in |
|---|---|---|
device_id | string, up to 100 characters | checkout |
device_fingerprint | string, up to 255 characters | checkout |
fp | string | checkout, indicates the origin of the identification (pro or fallback) |
fp_request_id | string | checkout, required to validate the identification |
url | string | terms_acceptance, access_log, usage_log |
note | string | any type |
carrier | string | delivery_confirmation, scan |
tracking | string | delivery_confirmation, scan |
lat | number | delivery_gps |
lng | number | delivery_gps |
Rules:
- in the browser channel, each type only accepts the fields the snippet builds:
checkouttakes the four device identification fields, andterms_acceptance,access_logandusage_logtake onlyurl.note,carrier,tracking,latandlngbelong to the server channel urlmust behttporhttps; anything else is discarded, with no error. Parameters (?...) and anchor (#...) are removed before saving, so buyer data in the URL does not stay in the evidence- in the browser channel, a
urlfrom a domain other than the site the event came from is also discarded. An event with no source site (noOriginorReferer) only keeps aurlfrom the store’s authorized sites; before there is an authorized site, itsurlis discarded latoutside -90 to 90 andlngoutside -180 to 180 are discarded, with no errorcarrierandtrackingfromdelivery_confirmationandscango in the dispute defense as the carrier and tracking number; a comma separates more than one value. When the delivery is confirmed with a date, only the delivery and the scans made up to it count. The firstscanwith either one, made after the purchase and before the confirmed delivery, becomes the shipping date- an access, usage, delivery or scan record dated before the purchase is not used as proof in the defense
- scalar values only (string, number, boolean). Objects and lists are discarded
device_idover 100 characters,device_fingerprintover 255 and other text fields over 512 return422 payload_too_large.device_idanddevice_fingerprintaccept an integer, stored as text- a missing or empty
payloadis accepted, but it does not count as proof in the defense:terms_acceptance,access_log,usage_loganddelivery_confirmationwith no data at all are saved and do not count as acceptance, access or delivery. In the browser channel, where these types only carryurl, that is the case of an event without a validurl
The checkout event
Section titled “The checkout event”checkout is the only type that writes data directly to the transaction, and not just as an attached record. It fills in the transaction’s device and IP only when those fields are empty: an earlier capture is never overwritten.
What each channel can write:
| Transaction data | Browser | Server |
|---|---|---|
device_id | does not write | writes |
device_fingerprint | only with validated identification | writes |
ip_address | only with validated identification | does not write |
The difference exists because the browser token is publishable: anyone who has it can send events. Unvalidated data never touches the fields that back the defense.
The server channel does not write the IP because the IP of the call is your server’s, not the buyer’s. Send the buyer’s IP in ip_address when you create the transaction.
Validated identification means: you sent fp_request_id and device_id in the payload, and Rapid confirmed the pair against Fingerprint on the server side. The identification must have been made at most 24 hours before the event and, in the browser channel, on the same site it came from. In that case the event also generates a device verification record, with bot, VPN and incognito window signals. Without validated identification, a browser-channel checkout does not fill in device or IP and generates no verification record, but it counts in the dashboard as a received event when the order’s transaction reaches Rapid. The other types (access_log, usage_log, terms_acceptance) become records as usual, with or without fp_request_id.
Each fp_request_id creates the device verification record in one transaction only. If the same pair arrives for another order, that order gets no verification record, but its device and IP fields are filled in as shown in the table above, only when they are empty.
Correlation window
Section titled “Correlation window”The event can arrive before the transaction exists. It stays in the queue and is retried for about 68 hours, at increasing intervals. Once the window passes with no matching transaction, the event is discarded.
In practice: sending checkout at the exact moment of the purchase works, even if your routine only sends the transaction to Rapid hours later.