Skip to content
Open appSchedule a pilot

Delete business

DELETE/api/v1/businesses/{business_id}

Schedule the deletion of a business after the grace period.

Safety: requires a JSON body with confirm_name matching the business's name (case-insensitive, trimmed) and a recent Clerk re-verification of the caller (step-up).

Effect: nothing is deleted now. The business is scheduled for permanent deletion BUSINESS_DELETION_GRACE_DAYS (default 30) days from now, as the privacy page promises, and the owners are emailed. Until then the business stays readable, owners and admins can export everything (POST /businesses/{business_id}/data-exports) or cancel (POST /businesses/{business_id}/deletion/cancel), and background syncs and scheduled jobs stop. Asking again keeps the original date.

After the grace period the nightly sweep runs the hard delete: third-party grants are revoked (Plaid, QuickBooks, Xero, Shopify, Square, Finch...), every business row, S3 object version and AI memory is deleted. That part is irreversible.

Returns: 202 with deletion_scheduled_for in data.

Operation ID: delete_business·View as markdown·OpenAPI slice

Authentication

Bearer token authentication. Pass your DayZero API token in the Authorization header and the target business UUID in x-business-id.

Parameters

Path

business_idstringrequired

Request body

Schema: BusinessDeleteRequest

confirm_passwordstring · password

Deprecated and ignored. Retained so clients sending the old body keep working during rollout. Step-up is now proven by Clerk re-verification (an emailed code, or the account's own factor), which works for SSO accounts that have no password.

business_idstring
confirm_namestringrequired

Exact business name as a typed confirmation. Must match the persisted business name (case-insensitive, trimmed). Required.

preserve_dz_usersboolean

Responses

202Successful Response

Schema: app__core__success__MessageResponse

successboolean
messagestring
codestring

401Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business

Schema: ErrorResponse

errorstringrequired

Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.

messagestringrequired

Human-readable explanation, safe to show to end users.

codestringrequired

Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).

request_idstring

Correlation id for support requests. Echoes the x-request-id request header when one was supplied.

errorsobject

Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

403Forbidden - Insufficient permissions

Schema: ErrorResponse

errorstringrequired

Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.

messagestringrequired

Human-readable explanation, safe to show to end users.

codestringrequired

Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).

request_idstring

Correlation id for support requests. Echoes the x-request-id request header when one was supplied.

errorsobject

Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

422Validation Error

Schema: ErrorResponse

errorstringrequired

Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.

messagestringrequired

Human-readable explanation, safe to show to end users.

codestringrequired

Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).

request_idstring

Correlation id for support requests. Echoes the x-request-id request header when one was supplied.

errorsobject

Field-level validation messages keyed by field name. Present on 400/422 validation failures only.