Refunds

Reverse tree, plastic bottle, or charity donation registrations.

Time limits

Registrations can typically only be refunded if they were created within the current billing cycle (or the last 30 days). For older records, contact saif@thegoodapi.com.

Refund trees

POST https://app.thegoodapi.com/refund/trees

Headers

Name	Value
Content-Type	application/json
Authorization	<your_api_key>

Request body

Name	Type	Description
id	string	Tree ID — fetch via the Get Total Trees Planted endpoint

Response — 200 OK

{
  "refunded_trees": 1001,
  "total_planted_trees": 15,
  "refund_details": [
    {
      "id": "Vf0YF7PuL5LDH0wh82Kt",
      "count": 1001,
      "fractional_count": 0,
      "created_at": "2025-07-07T00:24:06.884162Z",
      "idempotency_key": "",
      "metadata": {
        "key1": "val1",
        "key2": 714
      },
      "attribution": "saif282@gmail.com",
      "refunded": false
    }
  ],
  "refund_id": "refund-Vf0YF7PuL5LDH0wh82Kt"
}

Refund plastic bottles

POST https://app.thegoodapi.com/refund/plastic_bottles

Headers

Name	Value
Content-Type	application/json
Authorization	<your_api_key>

Request body

Name	Type	Description
id	string	Bottle ID — fetch via the Get Total Rescued Plastic Bottles endpoint

Response — 200 OK

{
  "refunded_bottles": 1,
  "total_rescued_bottles": 10,
  "refund_details": [
    {
      "id": "Vf0YF7PuL5LDH0wh82Kt",
      "count": 1001,
      "fractional_count": 0,
      "created_at": "2025-07-07T00:24:06.884162Z",
      "idempotency_key": "",
      "metadata": {
        "key1": "val1",
        "key2": 714
      },
      "attribution": "saif282@gmail.com",
      "refunded": false
    }
  ],
  "refund_id": "refund-Vf0YF7PuL5LDH0wh82Kt"
}

Refund charity donations

POST https://app.thegoodapi.com/refund/donations

Note

Refunding a donation marks it as refunded in the GoodAPI database (soft-delete). It does not automatically reverse Stripe metered usage.

Headers

Name	Value
Content-Type	application/json
Authorization	<your_api_key>

Request body

Name	Type	Required	Description
id	string	Yes	The unique donation ID to refund
reason	string	No	Human-readable reason for the refund
idempotency_key	string	No	Unique key to prevent duplicate refund processing
metadata	object	No	Arbitrary key-value pairs stored with the refund

Response — 200 OK

{
  "refunded_amount_cents": 5000,
  "total_donations": 14,
  "refund_details": [
    {
      "id": "don_abc123",
      "amount_cents": 5000,
      "currency": "USD",
      "ein": "53-0196605",
      "nonprofit_id": "n_abc123",
      "charity_name": "American Red Cross",
      "created_at": "2025-06-15T10:30:00Z",
      "idempotency_key": "order-12345-donate",
      "attribution": "checkout-flow",
      "metadata": {
        "order_id": "12345",
        "customer_email": "user@example.com"
      },
      "refunded": true
    }
  ],
  "refund_id": "refund-don_abc123"
}