checkout.returned

A return is the customer’s bank reversing a bank-rail payment after it succeeded (for example an ACH NSF or closed-account return). The charge moves to returned, and the customer is automatically restricted for deposits and withdrawals with reason code CHARGE_RETURNED. charge.failure_code and charge.failure_message are null on this event; the bank’s return code is not exposed today.A card chargeback is not a return: it does not change the charge’s status and no charge event fires. See Disputes and chargebacks for what you receive instead.

Payload Structure

interface WebhookEvent {
  event_id: string;
  data: {
    id: string; // id of the checkout you originally created
    line_items: Array<{
      product_id: string;
      quantity: number;
      total_amount_cents: number;
      product_name: string;
      product_url: string | null;
      product_price_cents: number;
      sku: string | null; // null when the product was created without a sku
    }>;
    line_items_total_amount_cents: number | null;
    type: "deposit" | "withdrawal"; // the checkout type — not the event type below
    charge: {
      id: string;
      amount_cents: number;
      transaction_type: "credit" | "debit";
      status: "returned";
      from_status: "succeeded";
      failure_code: string | null;
      failure_message: string | null;
    };
    customer: {
      id: string;
    };
    subscription: {
      id: string;
      interval: "day" | "week" | "month" | "year";
      interval_count: number;
      line_items: Array<{
        product_id: string;
        sku: string | null; // null when the product was created without a sku
        product_name: string;
        product_url: string | null;
        quantity: number;
        price_cents: number;
        total_amount_cents: number;
      }>;
      line_items_total_amount_cents: number | null;
    } | null; // null for non-subscription checkouts
  };
  type: "checkout.returned";
}

Example Response

{
  "event_id": "ev_tDaWu5aTVa2kbvDjGe55rxZpaMEmVFWB",
  "data": {
    "id": "chk_twijxXgVFofj9mdnvzF7vhbJSZEhfUpC",
    "line_items": [],
    "line_items_total_amount_cents": null,
    "type": "deposit",
    "charge": {
      "id": "ch_yRZcCGouimTgbz4thtrfbj2mh3ZT6vnz",
      "amount_cents": 2500,
      "transaction_type": "credit",
      "status": "returned",
      "from_status": "succeeded",
      "failure_code": null,
      "failure_message": null
    },
    "customer": {
      "id": "cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870"
    },
    "subscription": null
  },
  "type": "checkout.returned"
}

Updating Your Internal Ledger

This is essentially a reversal of the checkout.succeeded event. The transaction_type field in the charge object indicates the type of transaction:

credit: Money was originally added to the customer’s balance, so you should deduct it.
debit: Money was originally removed from the customer’s balance, so you should add it back.

API Documentation

API Endpoints

Webhooks

Testing

checkout.returned

Payload Structure

Example Response

Updating Your Internal Ledger

​Payload Structure

​Example Response

​Updating Your Internal Ledger

Payload Structure

Example Response

Updating Your Internal Ledger