Order Activities

An order activity log is a read-only, human-readable history of one order. Each row is one thing that happened (the order was created, a payment failed, a refund settled) with a description, a timestamp, and one reference you can click through to the resource it describes. It exists so you or a support agent can read an order top to bottom and make sense of it while debugging.

What It Is, and What It Is Not#

The log narrates history. It does not own truth. Everything a row shows is also available, authoritatively, on the resource it points at, and if the two ever disagree, the resource is right.

• Not a source of truth. For "did the money move", read the order and the refund. For "what is this payment doing right now", read the payment. The log tells you an event happened; the owning resource tells you the current, authoritative state.
• Not a webhook replacement. To react to events programmatically as they happen, use webhooks. This endpoint is pull-based and built for display and debugging. Do not poll it in a loop as an automation trigger.
• Not a ledger. Do not sum balance_delta_money across rows to compute an order balance. The order resource carries the authoritative totals. running_balance_money is there to help you read the log in context, not a figure to reconcile against.

Read an Order's History#

Fetch the log in chronological order with sort_direction=asc for timeline rendering. Newest-first (desc) is the default.

curl "https://api.withflintpay.com/v1/orders/ord_1kmn0aExample/activities?sort_direction=asc" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "order_activity_id": "act_01KWJZ8ZD3EDT7F78T82TZ6JXD",
      "activity_type": "created",
      "balance_delta_money": { "amount": 0, "currency": "USD" },
      "running_balance_money": { "amount": 5000, "currency": "USD" },
      "description": "Order created",
      "created_at": "2026-07-03T14:30:00Z"
    },
    {
      "order_activity_id": "act_01KWJZ8ZE1P6H1M3F0Z34B0K1R",
      "activity_type": "payment_failed",
      "balance_delta_money": { "amount": 0, "currency": "USD" },
      "running_balance_money": { "amount": 5000, "currency": "USD" },
      "description": "Payment failed: Your card was declined.",
      "payment_intent_id": "pi_01KWJZ8ZE9",
      "created_at": "2026-07-03T14:31:12Z"
    },
    {
      "order_activity_id": "act_01KWJZ8ZF7GXQ0S6E29Z4K3VD",
      "activity_type": "payment",
      "balance_delta_money": { "amount": -5000, "currency": "USD" },
      "running_balance_money": { "amount": 0, "currency": "USD" },
      "description": "Payment received",
      "payment_intent_id": "pi_01KWJZ8ZFA",
      "created_at": "2026-07-03T14:32:03Z"
    },
    {
      "order_activity_id": "act_01KWJZ8ZG2AEK5R5RZ025PX0S5",
      "activity_type": "refund",
      "balance_delta_money": { "amount": 2000, "currency": "USD" },
      "running_balance_money": { "amount": 2000, "currency": "USD" },
      "description": "Refund issued",
      "refund_id": "ref_01KWJZ8ZG6",
      "created_at": "2026-07-04T09:15:00Z"
    },
    {
      "order_activity_id": "act_01KWJZ8ZH9CAZK2XBKGRQXB4A",
      "activity_type": "refund_failed",
      "balance_delta_money": { "amount": 0, "currency": "USD" },
      "running_balance_money": { "amount": 2000, "currency": "USD" },
      "description": "Refund failed: The refund could not be processed.",
      "refund_id": "ref_01KWJZ8ZG6",
      "created_at": "2026-07-04T09:47:00Z"
    }
  ],
  "next_page_token": null,
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Read top to bottom, that log tells a complete story. Each row hands you the one place to go for the authoritative detail:

1. created starts the order at a $50.00 balance. Zero delta: creating an order moves no money.
2. payment_failed is the first collection attempt declining. The balance is unchanged, so the delta is 0. Click through to payment_intent_id for the payment's own state and next action.
3. payment is the successful charge. This is a real money movement, so balance_delta_money is -5000 and the running balance drops to 0. The payment_intent_id is the authoritative payment.
4. refund is a $20.00 partial refund settling. It carries a non-zero delta and raises the balance back to $20.00 owed. Follow refund_id for the refund's status and amounts.
5. refund_failed is a later attempt on the same refund_id that did not complete. It is a zero-delta note, not a reversal of row 4. To know what actually happened to the money, read the refund resource's status; do not infer "the customer both was and was not refunded" from seeing refund and refund_failed on one refund_id.

Deltas Separate Money Movement from Notes#

Only three activity types ever carry a non-zero balance_delta_money: payment, refund, and adjustment. Every other row (a failed payment, an expired checkout session, a line item edit) is informational and has balance_delta_money.amount == 0. That is a guarantee you can rely on to tell a money movement from a note at a glance. It is also why summing deltas is the wrong tool: read the order for totals, and use deltas only to read the story.

Filter a Busy Log#

A high-volume order (say, a hosted checkout that created and expired several sessions) can produce a long log. Narrow it with the type query parameter. Repeat the parameter or pass comma-separated values to match any of several types:

# Just the money movements
curl "https://api.withflintpay.com/v1/orders/ord_1kmn0aExample/activities?type=payment,refund" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Just the checkout session lifecycle
curl "https://api.withflintpay.com/v1/orders/ord_1kmn0aExample/activities?type=checkout_session_created&type=checkout_session_expired" \
  -H "Authorization: Bearer YOUR_API_KEY"

The filter composes with pagination: keep the same type values on every page. An unrecognized value returns a 400 that lists the accepted types.

Handle Unknown Types Gracefully#

activity_type is a stable but open string. The reference lists exactly the types Flint emits today, and there are no reserved-but-unused values, so what you see documented is what you will actually receive. But Flint adds new activity types over time, so write your renderer to fall back to a generic row for a value it does not recognize rather than throwing. That one habit keeps future additions from breaking your timeline.

The types Flint emits today:

Exactly one reference field (payment_intent_id, refund_id, checkout_session_id, and so on) is populated when a concrete resource exists for the row. Switch on activity_type to know which one to read, then click through to that resource for the truth.