Verify against final controller

This page documents the D.3 damage-charge endpoint. Verify exact field names and error codes against the final ConditionReportController before publishing.

Send Damage Charge

Send the customer a Stripe payment link for damage recorded at return. EquipDash creates the Stripe payment link, emails and texts it to the customer, and attaches a read-only dispute-defense page showing the damage photos, timestamp, item, and staff notes.

The charge is always staff-reviewed before sending — recording an estimated_charge_cents amount on a condition report does not automatically notify the customer. A staff member must call this endpoint (or tap Send damage charge in the web UI) to trigger the send.

Endpoint

POST /v1/condition-reports/{id}/send-damage-charge

Authentication

Requires an API key with the bookings:write scope. The authenticated supplier user must also have the bookings.fulfillment permission.

Path Parameters

Parameter	Type	Description
id	integer	Condition report ID

Prerequisites

The condition report must:

• Have estimated_charge_cents > 0
• Have charge_status = "pending" (charge not yet sent)
• Belong to a return context (context = "return")

Example Request

curl -X POST "https://app.equipdash.com/api/v1/condition-reports/42/send-damage-charge" \
  -H "Authorization: Bearer YOUR_API_KEY"

No request body is required.

Response

Success (200 OK)

{
  "data": {
    "id": 42,
    "booking_id": 123,
    "inventory_log_id": 456,
    "inventory_id": 78,
    "product_id": 12,
    "context": "return",
    "condition": "damaged",
    "condition_label": "Damaged",
    "notes": "Deep scratch on frame, chain broken",
    "estimated_charge_cents": 8500,
    "charge_status": "sent",
    "payment_link_url": "https://buy.stripe.com/test_abc123xyz",
    "dispute_evidence_url": "https://app.equipdash.com/booking/evidence/tok_abc123",
    "reported_by": {
      "id": 5,
      "name": "Sarah Marshall"
    },
    "reported_at": "2026-03-26T16:30:00Z",
    "photos": [
      {
        "id": 1,
        "url": "https://app.equipdash.com/storage/conditionReports/abc123.jpg",
        "order": 0
      }
    ],
    "created_at": "2026-03-26T16:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-26T16:35:00Z"
  }
}

Response Fields

Field	Type	Description
estimated_charge_cents	integer	The charge amount in cents
charge_status	string	pending → sent after this call; also paid, waived, disputed
payment_link_url	string|null	Stripe-hosted payment URL sent to the customer. Populated after send.
dispute_evidence_url	string|null	Read-only evidence page URL (photos + timestamp + staff notes). Shared with customer and usable for chargeback defense.

Charge Status Lifecycle

none  →  pending  →  sent  →  paid
                  ↘  waived
                  ↘  disputed

Status	Meaning
none	No charge was recorded on this condition report
pending	A charge amount was entered at return but not yet sent to the customer
sent	Payment link sent; waiting for customer payment
paid	Customer paid via Stripe (set automatically via webhook)
waived	Charge cancelled before or after sending (set manually in the web UI)
disputed	Customer disputed the charge with their bank

Submitting a Charge Amount at Return

Record the damage amount when confirming a return using the existing return endpoint:

POST /v1/bookings/{id}/items/return

{
  "item_ids": ["456"],
  "condition_reports": {
    "456": {
      "condition": "damaged",
      "notes": "Deep scratch on frame, chain broken",
      "estimated_charge_cents": 8500
    }
  }
}

The condition report will have charge_status: "pending". Then call this endpoint to send the charge to the customer.

Errors

Status	Code	Description
401	authentication_required	No API key provided
401	invalid_api_key	Invalid API key
403	insufficient_scope	API key lacks bookings:write scope
403	insufficient_permissions	User lacks bookings.fulfillment permission
404	not_found	Condition report not found or belongs to another supplier
422	invalid_charge_state	charge_status is not pending (already sent or no amount recorded)
422	no_charge_amount	estimated_charge_cents is 0 or null

Webhook Event

When the customer pays via the Stripe link, EquipDash automatically updates charge_status to paid and emits a booking.damage_charge.paid webhook event:

{
  "event": "booking.damage_charge.paid",
  "data": {
    "booking_id": 123,
    "condition_report_id": 42,
    "charge_cents": 8500,
    "paid_at": "2026-03-27T11:00:00Z"
  }
}

See Webhooks Events for the full events reference.

Notes

• The payment link is a separate Stripe transaction, not a capture of any security deposit. Deposit release or capture is handled independently via the booking payments endpoints.
• Photos should be uploaded before sending the charge so the dispute-evidence page is as complete as possible. Use Upload Photos to attach photos to the condition report.
• The endpoint is idempotent-safe: calling it again when charge_status is already sent returns HTTP 422 rather than creating a second payment link.

Related Endpoints

• Condition Reports on Pickup/Return — submit condition at return with charge amount
• Get Condition Report — retrieve a report and check charge_status
• Upload Photos — attach damage photos to the report
• Webhooks Events — booking.damage_charge.paid