Source: https://datafa.st/docs/api/website/payments/delete
Markdown source: https://datafa.st/docs/api/website/payments/delete.md
Description: Delete payment and free-trial records by transaction ID, visitor, or time range. Filters are evaluated in priority order: transaction ID first, then visitor, then bulk time range.

# Delete payments

`DELETE https://datafa.st/api/v1/payments`

Delete payment and free-trial records by transaction ID, visitor, or time range. Filters are evaluated in priority order: transaction ID first, then visitor, then bulk time range.

For bulk deletes without a transaction or visitor, `start` and `end` are **required** (this endpoint uses `start`/`end`, not `startAt`/`endAt`).

> **Related:** [Revenue attribution](/docs/revenue-attribution-guide)

## Request

#### Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `websiteId` | string | Required with dft_ | Required with a `dft_` account token on Website API routes. Omit with a `df_` website key. Example: `?websiteId=665f0b3c4d2e1a0012345678`. |
| `transaction_id / tx_id` | string | No | Delete one payment. Unique ID from your billing system — used for idempotency. Example: `"txn_abc123"`. Re-posting the same ID returns a duplicate message, not a second payment. |
| `datafast_visitor_id` | string | No | Delete all payments for one visitor. Visitor UUID from the `datafast_visitor_id` cookie or tracking script. Example: `"a3ab2331-989f-4cfa-91c6-2461c9e3c6bd"`. Alias: `visitorId` on some endpoints. |
| `start` | string | Conditional | ISO 8601 bounds for bulk delete. Example query: `start=2026-05-01T00:00:00Z&end=2026-05-19T23:59:59Z`. **Required together** when no other filter (transaction, visitor, or goal name) is provided. Note: uses `start`/`end`, not `startAt`/`endAt`. |
| `end` | string | Conditional | ISO 8601 end bound. Required with `start` for bulk deletes. |

#### Example queries

By transaction:

```http
DELETE /api/v1/payments?transaction_id=txn_abc123
```

Bulk by date range:

```http
DELETE /api/v1/payments?start=2026-05-01T00:00:00Z&end=2026-05-19T23:59:59Z
```

## Response

Returns a JSON object with `status: "success"` and endpoint-specific fields in `data` (and `pagination` when the endpoint is paginated).

#### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `status` | string | `success`. |
| `data[].message` | string | Human-readable confirmation or status message for the operation. |
| `data[].transaction_id` | string | Unique transaction ID from your payment provider. Used for idempotency and deletion. |
| `data[].datafast_visitor_id` | string | DataFast visitor UUID from the browser cookie or client SDK. Used to attach server-side events to a visitor journey. |
| `data[].timeRange.start` | string | Present for time range deletes. |
| `data[].timeRange.end` | string | Present for time range deletes. |

## Authentication

- **`df_` website API key:** The website is inferred from the key. You do not need a `websiteId` query parameter.
- **`dft_` account token:** Requires `payments:write` permission and `?websiteId=` on every request. The token must be allowed to access that website.

Read [authentication and scopes](/docs/api/authentication) for token creation, permission lists, and scoped tokens.

### Errors

**400** — No filter provided, invalid visitor ID, or missing `start`/`end` for bulk delete.

**404** — Transaction not found.

See [API errors](/docs/api#errors) for the standard error envelope, auth failures, validation errors, permission errors, and rate limits.

## Code examples

### Example request

```bash
curl -X DELETE "https://datafa.st/api/v1/payments?transaction_id=payment_456" \
  -H "Authorization: Bearer df_xxx"
```

### Success response

```json
{
  "status": "success",
  "data": [{
    "transaction_id": "payment_456",
    "message": "Payment deleted successfully"
  }]
}
```