Payload reference

Refund payloads

Refund events fire as a refund moves through its lifecycle. The entity that changed arrives under data.object as a RefundFatPayload, wrapped in the standard webhook envelope. The payloads on this page are built from real emitted examples.

Base fields

Every payload extends BaseEventPayload:

Field	Type	Nullable	Notes
`object`	string	No	Discriminator for the entity. `"refund"`.
`id`	string	No	Raw entity UUID, prefixed `ref_` in the example.
`workspace_id`	string	No	Raw workspace UUID the refund belongs to.
`created_at`	datetime	Yes	ISO 8601 creation timestamp.

Refund fields

In addition to the base fields, a refund carries:

Field	Type	Nullable	Notes
`sale_id`	string	No	The sale being refunded, prefixed `sl_`.
`team_member_id`	string	Yes	ID of the team member tied to the refund.
`commission_transaction_id`	string	Yes	ID of the affected commission transaction.
`team_member`	team_member object	Yes	Snapshot of the team member. See edge cases and nested objects.
`commission_transaction`	object	Yes	Snapshot of the affected commission transaction at refund time.
`refund_amount`	decimal	No	Total refund amount as a decimal string (e.g. `"100000.00"`).
`remaining_refund`	decimal	No	Refund amount still outstanding, as a decimal string. Decreases as the refund completes.
`refund_reason`	string	Yes	Free-text reason supplied with the refund.
`status`	string	No	`pending` on creation, `partial` (and beyond) as it completes.
`created_at`	datetime	No	ISO 8601 creation timestamp.
`updated_at`	datetime	No	ISO 8601 timestamp of the last change.

Confirmed wire contract. Money fields (refund_amount, remaining_refund) are decimal strings in major units - "100000.00" is 100,000.00, not minor units. Parse them as decimals, never as integers. The same convention applies to the nested commission_transaction amounts. Timestamps created_at and updated_at are emitted as ISO 8601 strings.

refund.created

Fires the moment a refund is initiated. status is pending and remaining_refund equals the full refund_amount.

Real refund.created payload


Code
{
  "event_id": "evt_9d2f1a55-6c3b-4e08-bb71-1f4a2c7d8e90",
  "event_type": "refund.created",
  "api_version": "2026-06-01",
  "created_at": "2026-06-20T12:41:30.898Z",
  "workspace_id": "ws_7c448c98-390c-4994-abe8-21d0f7b899a8",
  "livemode": false,
  "data": {
    "object": {
      "object": "refund",
      "id": "ref_d5d0252d-0000-0000-0000-000000000000",
      "sale_id": "sl_7a65f148-0000-0000-0000-000000000000",
      "team_member": {
        "object": "team_member",
        "id": "tm_b04d07fe-0000-0000-0000-000000000000",
        "first_name": "Closer",
        "last_name": "Abhinav",
        "email": "closer.abhinav@example.com",
        "roles": ["closer"],
        "department": "sales",
        "is_active": true
      },
      "commission_transaction": {
        "object": "commission_transaction",
        "id": "ct_31c980d7-0000-0000-0000-000000000000",
        "type": "commission_payment",
        "status": "completed",
        "amount": "988059.70",
        "fee": "11940.298507462687",
        "net": "976119.4014925372",
        "currency": "usd",
        "refund_adjustment": "0.00",
        "sale_id": "sl_7a65f148-0000-0000-0000-000000000000",
        "commission_rate": 10.0,
        "team_member": null,
        "installment": null,
        "payout": {
          "date": null,
          "transfer_id": "tr_1T1gOsHll432c94ednkzRyyp",
          "paused": false,
          "paused_until": null
        },
        "idempotency_key": "transfer_sale_member",
        "created": "2026-06-10T09:24:59.000Z",
        "updated": "2026-06-17T04:20:43.000Z"
      },
      "refund_amount": "100000.00",
      "remaining_refund": "100000.00",
      "refund_reason": "Testing Refund",
      "status": "pending",
      "created_at": "2026-06-20T12:41:30.898Z",
      "updated_at": "2026-06-20T12:41:30.898Z"
    }
  }
}

refund.completed

Fires as the refund settles. The data.object shape is identical to refund.created, with these differences:

status becomes partial (and later, terminal states as the refund fully settles).
remaining_refund decreases - e.g. from "100000.00" to "99107.74" - as portions are applied.
updated_at advances to the settlement time.

Track progress by reading remaining_refund and status on each event rather than assuming arrival order.

Edge cases

Two team_member shapes (confirmed). The top-level team_member is the Variant B shape - it carries {department, is_active} and has no user_id. The team_member nested inside commission_transaction follows the commission variant.
Nested team_member is null (confirmed). The commission_transaction.team_member can be null even when the top-level team_member is fully populated. Do not assume the nested member mirrors the top-level one - read each independently and tolerate null on the nested field.
Decimal-string money. Both the refund's own amounts and the nested commission amounts are decimal strings. Treat them as decimals.

Last modified on September 25, 2026

Product Processor

Field

Type

Nullable

Notes

object

string

Discriminator for the entity. "refund".

id

string

Raw entity UUID, prefixed ref_ in the example.

workspace_id

string

Raw workspace UUID the refund belongs to.

created_at

datetime

Yes

ISO 8601 creation timestamp.

Refund fields

In addition to the base fields, a refund carries:

Field

Type

Nullable

Notes

sale_id

string

The sale being refunded, prefixed sl_.

team_member_id

string

Yes

ID of the team member tied to the refund.

commission_transaction_id

string

Yes

ID of the affected commission transaction.

team_member

team_member object

Yes

Snapshot of the team member. See edge cases and nested objects.

commission_transaction

object

Yes

Snapshot of the affected commission transaction at refund time.

refund_amount

decimal

Total refund amount as a decimal string (e.g. "100000.00").

remaining_refund

decimal

Refund amount still outstanding, as a decimal string. Decreases as the refund completes.

refund_reason

string

Yes

Free-text reason supplied with the refund.

status

string

pending on creation, partial (and beyond) as it completes.

created_at

datetime

ISO 8601 creation timestamp.

updated_at

datetime

ISO 8601 timestamp of the last change.

refund.created

Fires the moment a refund is initiated. status is pending and remaining_refund equals the full refund_amount.

Real refund.created payload


Code
{
  "event_id": "evt_9d2f1a55-6c3b-4e08-bb71-1f4a2c7d8e90",
  "event_type": "refund.created",
  "api_version": "2026-06-01",
  "created_at": "2026-06-20T12:41:30.898Z",
  "workspace_id": "ws_7c448c98-390c-4994-abe8-21d0f7b899a8",
  "livemode": false,
  "data": {
    "object": {
      "object": "refund",
      "id": "ref_d5d0252d-0000-0000-0000-000000000000",
      "sale_id": "sl_7a65f148-0000-0000-0000-000000000000",
      "team_member": {
        "object": "team_member",
        "id": "tm_b04d07fe-0000-0000-0000-000000000000",
        "first_name": "Closer",
        "last_name": "Abhinav",
        "email": "closer.abhinav@example.com",
        "roles": ["closer"],
        "department": "sales",
        "is_active": true
      },
      "commission_transaction": {
        "object": "commission_transaction",
        "id": "ct_31c980d7-0000-0000-0000-000000000000",
        "type": "commission_payment",
        "status": "completed",
        "amount": "988059.70",
        "fee": "11940.298507462687",
        "net": "976119.4014925372",
        "currency": "usd",
        "refund_adjustment": "0.00",
        "sale_id": "sl_7a65f148-0000-0000-0000-000000000000",
        "commission_rate": 10.0,
        "team_member": null,
        "installment": null,
        "payout": {
          "date": null,
          "transfer_id": "tr_1T1gOsHll432c94ednkzRyyp",
          "paused": false,
          "paused_until": null
        },
        "idempotency_key": "transfer_sale_member",
        "created": "2026-06-10T09:24:59.000Z",
        "updated": "2026-06-17T04:20:43.000Z"
      },
      "refund_amount": "100000.00",
      "remaining_refund": "100000.00",
      "refund_reason": "Testing Refund",
      "status": "pending",
      "created_at": "2026-06-20T12:41:30.898Z",
      "updated_at": "2026-06-20T12:41:30.898Z"
    }
  }
}

refund.completed

Fires as the refund settles. The data.object shape is identical to refund.created, with these differences:

status becomes partial (and later, terminal states as the refund fully settles).

remaining_refund decreases - e.g. from "100000.00" to "99107.74" - as portions are applied.

updated_at advances to the settlement time.

Track progress by reading remaining_refund and status on each event rather than assuming arrival order.

Edge cases

Two team_member shapes (confirmed). The top-level team_member is the Variant B shape - it carries {department, is_active} and has no user_id. The team_member nested inside commission_transaction follows the commission variant.

Nested team_member is null (confirmed). The commission_transaction.team_member can be null even when the top-level team_member is fully populated. Do not assume the nested member mirrors the top-level one - read each independently and tolerate null on the nested field.

Decimal-string money. Both the refund's own amounts and the nested commission amounts are decimal strings. Treat them as decimals.

Last modified on September 25, 2026