Skip to content

↑↓ navigate ↵ open Ctrl↵ new tab esc close

Reference of the values accepted in the two capture channels. Applies to POST /capture/{token}/events and POST /capture/events.

FieldTypeLimitRequired
typestring (enum)see table belowYes
order_refstring or number100 charactersYes
event_idstring or number64 charactersYes in the browser, optional on the server
payloadobjectsee accepted fieldsNo
captured_atstring (ISO 8601)-No, and only the server channel uses it
merchant_idstring (UUID)-Server channel only

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:

  1. a transaction with external_id equal to order_ref
  2. if not found, a transaction with order_number equal to order_ref
  3. if still not found, among transactions with external_source shopify, order_ref also works without the leading # (1001 finds #1001, and #1001 finds 1001) and as the order GID (gid://shopify/Order/<id> or gid://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 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.

When the fact happened, in ISO 8601.

ChannelBehavior
Browserignored. Rapid records the time the event arrived
Serverused 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.

ValueWhat it recordsBrowserServer
checkoutPurchase completion, with device dataYesYes
terms_acceptanceAcceptance of terms, policy or contractYesYes
access_logAccess to the product or the logged-in areaYesYes
usage_logActual use of the product or serviceYesYes
delivery_confirmationDelivery confirmedNoYes
scanTracking code scan in transitNoYes
delivery_gpsDelivery coordinateNoYes

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 has a closed list of fields. A key outside the list is silently discarded, with no error, so check the spelling.

FieldTypeUse in
device_idstring, up to 100 characterscheckout
device_fingerprintstring, up to 255 characterscheckout
fpstringcheckout, indicates the origin of the identification (pro or fallback)
fp_request_idstringcheckout, required to validate the identification
urlstringterms_acceptance, access_log, usage_log
notestringany type
carrierstringdelivery_confirmation, scan
trackingstringdelivery_confirmation, scan
latnumberdelivery_gps
lngnumberdelivery_gps

Rules:

  • in the browser channel, each type only accepts the fields the snippet builds: checkout takes the four device identification fields, and terms_acceptance, access_log and usage_log take only url. note, carrier, tracking, lat and lng belong to the server channel
  • url must be http or https; 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 url from a domain other than the site the event came from is also discarded. An event with no source site (no Origin or Referer) only keeps a url from the store’s authorized sites; before there is an authorized site, its url is discarded
  • lat outside -90 to 90 and lng outside -180 to 180 are discarded, with no error
  • carrier and tracking from delivery_confirmation and scan go 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 first scan with 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_id over 100 characters, device_fingerprint over 255 and other text fields over 512 return 422 payload_too_large. device_id and device_fingerprint accept an integer, stored as text
  • a missing or empty payload is accepted, but it does not count as proof in the defense: terms_acceptance, access_log, usage_log and delivery_confirmation with no data at all are saved and do not count as acceptance, access or delivery. In the browser channel, where these types only carry url, that is the case of an event without a valid url

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 dataBrowserServer
device_iddoes not writewrites
device_fingerprintonly with validated identificationwrites
ip_addressonly with validated identificationdoes 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.

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.