Create Stripe Checkout session for onboarding

POST/api/v1/onboarding/prepare-checkout

Collects plan and add-on selections, creates a Stripe Checkout session with a 1-month (30-day) trial. Business is NOT created until /complete is called.

Operation ID: prepare_checkout·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.

Request body

Schema: PrepareCheckoutRequest

account_typestringrequired

'self-managed', 'dz-managed', or 'advisory-firm'

business_namestringrequired

mailboxstringrequired

default_currencystring

Default business currency. Supported out of the box: USD, CAD, AUD, EUR, GBP.

tax_year_end_monthinteger

selected_addonsarray · string

Optional list of addon slugs to include on the Stripe Checkout. Capped at 50 entries.

trial_agreedbooleanrequired

User has agreed to the 1-month (30-day) free trial terms

billing_intervalstring

Billing cadence for the subscription. 'year' resolves the discounted annual catalog prices; defaults to 'month'.

One of: month, year

firm_namestring

firm_plan_tierstring

Graduated firm plan tier (defaults to firm_starter)

einstring

logo_urlstring

addressstring

num_full_time_accountantsinteger

num_part_time_accountantsinteger

current_toolsarray · string

referral_sourcestring

Self-reported acquisition channel: referral, accountant, search, social, ads, event, marketplace, other.

referred_by_emailstring

Email of whoever referred this user. Free text — not resolved against existing accounts.

success_pathstring

Optional path-only override (no host) to land on after Stripe Checkout. Defaults to /onboarding/complete.

cancel_pathstring

Optional path-only override (no host) for cancelled checkout. Defaults to /welcome.

Responses

201Successful Response

Schema: SuccessEnvelope_PrepareCheckoutResponse_

successboolean
messagestring
codestring
dataPrepareCheckoutResponse

400Bad Request - Invalid input

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.

409Conflict - Resource already exists or is in an incompatible state

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.

429Too Many Requests - Rate limit exceeded; back off and retry

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.

503Service Unavailable

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.

Code samples

POST/api/v1/onboarding/prepare-checkout

bash

curl -X POST 'https://api.ondayzero.com/api/v1/onboarding/prepare-checkout' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "account_type": "string",
  "business_name": "string",
  "mailbox": "string",
  "trial_agreed": false
}'