ThoughtMetric

Data insert API

Order

GET https://data.thoughtmetric.io/d

Records an order. Orders are de-duplicated on transaction_id, so re-sending one updates the existing record. That is how you push status changes, refunds and corrected totals.

Always pair this with a customer event. Send an identify call for the same uid, or we cannot tell whether the buyer is new or returning and your new-versus-returning reporting will be wrong.

Example request

curl -G https://data.thoughtmetric.io/d \
  -d id=ID-bcd0aa692ce7e6b2 \
  -d uid=8824a9fc-002d-4fb8-bcea-9e60225a88f0 \
  -d ht=event \
  -d ev=order \
  -d v=api \
  -d ip=203.0.113.42 \
  --data-urlencode dl=https://example-store.com/checkout/thank-you \
  -d ts=2024-01-31T18:22:04Z \
  --data-urlencode 'ed={"transaction_id":"1091","status":"completed","currency":"USD","orderCurrency":"USD","total_price":108.95,"subtotal_price":99.00,"total_tax":14.21,"total_shipping":9.95,"total_discounts":0,"item_quantity":1,"items":[{"sku":"MWC-CHR-M","variant":"Charcoal / M","quantity":1,"discounts":0,"unit_price":99.00,"product_name":"Merino Wool Crew"}]}'

Query parameters

id string, required Your Project ID.
uid string, required UUID identifying the visitor. Use the same value as their pageviews so the order can be attributed to their visit.
ht string, required Always event for this call.
ev string, required Always order for this call.
ed string, required JSON object with the order details. Must contain transaction_id. Fields below.
v string Always api for this call.
ip string Visitor's IP address.
dl string URL the order was placed on, typically your thank-you page.
rl string Referring URL.
dc string Discount code used on the order.
ts string When the order was placed. ISO 8601 or Unix seconds. Backdate this for offline or imported orders.

The ed object

URL-encoded JSON describing the order. Only transaction_id is required; orders arriving without one are discarded. Everything else is optional, but sales metrics can only be as complete as what you send.

transaction_id string, required Your order identifier. The de-duplication key, and what appears as transaction_id in the REST API.
status string Order status: completed, refunded or failed.
currency string The currency your ThoughtMetric account reports in.
orderCurrency string The currency the order was actually placed in.
total_price number Total value of the order, including tax and shipping.
subtotal_price number Sum of line items after discounts, excluding tax and shipping.
total_tax number Tax charged.
tax_included boolean Whether tax is already included in the line item prices.
tax_rate number Tax rate applied.
total_shipping number Shipping charged.
total_discounts number Total discount applied, as a positive number, e.g. 10.00 for $10 off.
total_refund number Amount refunded. Send this on a follow-up call to record a refund.
discount_codes array Array of discount code strings used on the order.
item_quantity number Total units on the order.
items array Array of line item objects. Fields below.
subscription boolean Whether this is a subscription order.
platform string Where the order came from, for your own reference.

Line items

Each entry in items. These drive the product-level reporting.

sku string Product SKU. Used to match against your catalog for category reporting.
product_name string Product name, as it should appear in reports.
variant string Variant name, e.g. size or colour.
quantity number Units of this item.
unit_price number Price per unit before discounts.
discounts number Discount applied to this line.
quantity_refunded number Units refunded from this line.
refund_amount number Amount refunded on this line.

Example ed payload

ed (before URL encoding) 
{
  "transaction_id": "1091",
  "status": "completed",
  "currency": "USD",
  "orderCurrency": "USD",
  "total_price": 108.95,
  "subtotal_price": 99.00,
  "total_tax": 14.21,
  "total_shipping": 9.95,
  "total_discounts": 0,
  "total_refund": 0,
  "discount_codes": [],
  "item_quantity": 1,
  "items": [
    {
      "sku": "MWC-CHR-M",
      "variant": "Charcoal / M",
      "quantity": 1,
      "discounts": 0,
      "unit_price": 99.00,
      "product_name": "Merino Wool Crew"
    }
  ]
}

Notes

  • Recording a refund is a second call with the same transaction_id, a total_refund and status of refunded.
  • For offline or backfilled orders, set ts to when the order actually happened. Without a matching visit the order records as direct traffic.
  • Remember that ed must be URL-encoded as a query parameter. Most HTTP clients do this for you.
Pageview event ‹ Previous Customer event Next ›