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.

`startAt` and `endAt` are canonical for every ranged delete. They are optional when filtering by visitor and required for an unfiltered bulk delete. Deprecated aliases: `start` and `end` remain accepted together for compatibility. Incomplete or conflicting ranges return **400** instead of falling back to an all-time delete. Date parameters are ignored when `transaction_id` is present.

> **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. |
| `startAt` | string | Conditional | Canonical ISO 8601 bounds for every ranged delete. Pass `startAt` and `endAt` together. They are optional for a filtered delete and required for an unfiltered bulk delete. Example: `startAt=2026-05-01T00:00:00Z&endAt=2026-05-19T23:59:59Z`. |
| `endAt` | string | Conditional | End of the reporting window. Must be paired with `startAt` so DataFast can build the date range. Canonical end bound. Required with `startAt` whenever either bound is provided. |
| `start` | string | No | Deprecated aliases for `startAt` and `endAt`. Existing clients may continue to pass `start` and `end` together. Incomplete or conflicting ranges return **400**. |
| `end` | string | No | Deprecated alias for `endAt`. Pass together with `start`. |

#### Example queries

By transaction:

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

By visitor and optional canonical range:

```http
DELETE /api/v1/payments?datafast_visitor_id=a3ab2331-989f-4cfa-91c6-2461c9e3c6bd&startAt=2026-05-01T00:00:00Z&endAt=2026-05-19T23:59:59Z
```

Bulk by date range (also uses `startAt` + `endAt`):

```http
DELETE /api/v1/payments?startAt=2026-05-01T00:00:00Z&endAt=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, invalid, incomplete, or conflicting range, or missing `startAt`/`endAt` 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"
  }]
}
```