> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.helpyousponsor.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Preview a staff-entered donation receipt
> Validates the proposed gift and renders the actual receipt plan without creating a donation, charging, advancing a commitment or sending email. Split amounts must align and sum to the gift total. Plans honor suppression, notification preferences, source-specific templates, disclosure and recipient selection. HTTP200 may report skipped/suppressed/unavailable. DAF/QCD source preview requires the organization rollout and eligible owner/advisor/custodian records. Requires permission: one of donations, reports_view, reports_manage.
## OpenAPI
````yaml post /admin/donations/receipt-preview
openapi: 3.0.0
info:
title: Gratona API
description: >-
REST API for the Gratona fundraising platform, including donor, donation,
sponsorship, program, event, and integration workflows. Endpoints are
organized by tag. Most endpoints require either a Passport bearer token or
an issued API key — see the Security Schemes section.
contact:
name: Gratona Engineering
url: https://gratona.com
email: devs@gratona.com
version: 1.0.0
servers:
- url: https://api.gratona.com/v1
description: Server Version 1.0.0
security: []
tags:
- name: Auth
description: >-
Login, signup, logout, password reset, and email verification for admin
users and donors.
- name: Donors
description: >-
Donor records: CRUD, profile fields, household linkage, search, filters,
merge, and duplicate detection.
- name: Donations
description: >-
Individual donation records, recurring commitments, soft credits, refunds,
designations, and exports.
- name: Sponsorships
description: >-
Donor-to-entity commitment relationships, lifecycle transitions, and
commitment-specific filters.
- name: Entities
description: >-
Recipient records (children, families, projects, animals, etc.), their
status, and entity-level fields.
- name: Programs
description: >-
Program / campaign configuration: hierarchy, settings, and program-level
metadata.
- name: Forms
description: >-
Custom form builder (HysForm), form fields, standardized donor fields, and
field migrations.
- name: Trips
description: >-
Mission-trip management: trips, participants, budgets, tasks,
e-signatures, fundraising milestones, and background checks.
- name: Communications
description: >-
Email templates, SMS, newsletters, donor email manager, and per-donor
notes.
- name: Payments
description: >-
Payment-gateway management (Stripe, PayPal, Flutterwave, QuickBooks).
Excludes inbound webhooks — see the Webhooks tag.
- name: Reports
description: Dashboards, analytics, scheduled reports, and exports.
- name: Admin
description: >-
Client-account administration: users, groups/permissions, settings,
integrations, and account lifecycle.
- name: Donor Portal
description: >-
Endpoints consumed by the donor-facing portal (donor login, dashboard,
donation history, messages).
- name: Recipient Portal
description: Endpoints consumed by the recipient-facing portal.
- name: Public
description: >-
Unauthenticated public endpoints: donor signup, public trip pages,
peer-to-peer campaigns, public checkout.
- name: Webhooks
description: >-
Inbound webhooks from third parties (Stripe, PayPal, Flutterwave, Checkr,
DropboxSign). Annotated minimally for reference; payload shapes are owned
by the upstream provider.
- name: Events
description: >-
Event setup, invitations, registration, ticketing, attendance and event
reporting.
- name: Journeys
description: >-
Journey graphs, activation, enrollment, message templates and event
follow-up automations.
- name: Tasks
description: Workspace tasks, assignments, saved task views and record collaboration.
- name: Fundraising
description: >-
Fundraising portfolios, stewardship plans, giving anniversaries and
personal donor follow-up.
- name: Impact Stories
description: Story intake, review, assets, consent and publication workflows.
- name: Integrations
description: Workspace integration connections, mappings, synchronization and recovery.
- name: Email Calendar
description: Connected email/calendar accounts and donor interactions.
- name: Spaces
description: Workspace Spaces and collaborative Pages.
- name: Library
description: Workspace documents, source connections, files and analysis.
- name: Intelligence
description: Donor intelligence and Tali workspace workflows.
- name: Automation
description: >-
V3 automation primitive discovery, input validation, invocation and Zapier
contracts.
- name: Schema
description: V3 model, enum, capability and scope discovery.
- name: Zapier
description: Zapier automation connections, polling feeds and actions.
- name: Files
description: Files
- name: Client
description: Client
- name: Payment Gateways
description: Payment Gateways
- name: Email Settings
description: Email Settings
- name: Admin Dashboard
description: Admin Dashboard
- name: Recipients
description: Recipients
- name: Historical Archived Updates
description: Historical Archived Updates
- name: Team & access
description: Team & access
- name: Settings
description: Settings
- name: Notifications
description: Notifications
- name: Participation
description: Participation
- name: Users
description: Users
- name: Wrapped
description: Wrapped
- name: Donor SignUp
description: Donor SignUp
- name: Frontend
description: Frontend
- name: User
description: User
- name: Workspace
description: Workspace
paths:
/admin/donations/receipt-preview:
post:
tags:
- Donations
summary: Preview a staff-entered donation receipt
description: >-
Validates the proposed gift and renders the actual receipt plan without
creating a donation, charging, advancing a commitment or sending email.
Split amounts must align and sum to the gift total. Plans honor
suppression, notification preferences, source-specific templates,
disclosure and recipient selection. HTTP200 may report
skipped/suppressed/unavailable. DAF/QCD source preview requires the
organization rollout and eligible owner/advisor/custodian records.
Requires permission: one of donations, reports_view, reports_manage.
operationId: reference_Admin_DonationController_previewDonationReceipt
requestBody:
description: Validated request fields for this operation.
required: true
content:
application/json:
schema:
required:
- donor_id
- designation
- amount
- method
properties:
donor_id:
description: >-
Active organization donor; financial party rules depend on
giving_source.
type: integer
example: 21
designation:
description: >-
Organization-owned entity-ID or desig-ID reference, or split
allocation references. Array form requires matching
split_amounts.
anyOf:
- type: string
example: entity-42
- type: array
items:
type: string
example: entity-42
minItems: 1
amount:
description: >-
Total amount, at most two decimal places. Splits must sum
exactly to this amount.
type: number
minimum: 0.01
example: 75
method:
description: >-
Registered compatibility payment-method ID. DAF/QCD accept
received-money methods1,2,4,7.
anyOf:
- type: integer
example: 1
- type: string
example: '1'
split_amounts:
description: >-
Required when designation is an array; one positive amount
per reference.
type: array
items:
type: number
minimum: 0
exclusiveMinimum: true
example: 75
nullable: true
created_at:
type: string
format: date-time
example: '2026-10-20T12:00:00Z'
nullable: true
currency:
type: string
maxLength: 10
example: $
nullable: true
dont_notify:
description: Compatibility boolean flag; use0/1 or false/true.
anyOf:
- type: boolean
example: false
- type: integer
example: 0
- type: string
example: '0'
- type: string
enum:
- null
nullable: true
in_kind_category:
type: string
maxLength: 100
example: goods
nullable: true
check_number:
type: string
maxLength: 100
example: '1042'
nullable: true
addSoftCredit:
description: >-
Enables manual Direct-gift recognition; requires donor,
active type and positive amount.
type: boolean
example: false
nullable: true
soft_credit_donor_id:
type: integer
example: 24
nullable: true
soft_credit_amount:
description: >-
Required when addSoftCredit is enabled; cannot exceed the
total gift.
type: number
minimum: 0
example: 25
nullable: true
soft_credit_split_amounts:
description: >-
For multiple allocations, sum to the soft credit total and
never exceed corresponding gift splits.
type: array
items:
type: number
minimum: 0
example: 25
nullable: true
soft_credit_type:
description: >-
Active manual type; automatic DAF/QCD types are not
selectable.
type: integer
example: 2
nullable: true
dont_send_soft_credit_email:
description: Compatibility boolean flag; use0/1 or false/true.
anyOf:
- type: boolean
example: false
- type: integer
example: 0
- type: string
example: '0'
- type: string
enum:
- null
nullable: true
is_tax_deductible:
description: >-
Scalar or allocation-aligned tax flag; QCD forces
non-deductible treatment.
anyOf:
- description: Compatibility boolean flag; use0/1 or false/true.
anyOf:
- type: boolean
example: false
- type: integer
example: 0
- type: string
example: '0'
- type: string
enum:
- null
nullable: true
- type: array
items:
description: Compatibility boolean flag; use0/1 or false/true.
anyOf:
- type: boolean
example: false
- type: integer
example: 0
- type: string
example: '0'
- type: string
enum:
- null
nullable: true
giving_source:
description: >-
Canonical source values; known compatibility aliases are
normalized. Special sources require daf_qcd_giving_v1.
type: string
maxLength: 40
example: direct
nullable: true
advisor_donor_id:
description: DAF recommending supporter; named disclosure requires it.
type: integer
example: 24
nullable: true
intermediary_donor_id:
description: Organization-owned IRA custodian required for QCD.
type: integer
example: 30
nullable: true
daf_disclosure:
description: >-
DAF acknowledgement disclosure; fund_only requires a
nonblank fund name.
type: string
maxLength: 16
enum:
- named
- fund_only
- anonymous
- null
example: named
nullable: true
daf_fund_name:
description: Permitted only for named or fund_only disclosure.
type: string
maxLength: 191
example: Community Fund
nullable: true
source_reference:
type: string
maxLength: 191
example: Grant reference123
nullable: true
custom_fields:
description: >-
Organization-defined gift field map. Definitions control
keys, scalar types, choices and conditional requirements.
Validated before preview; the receipt-preview handler
forwards only its explicit preview fields.
type: object
nullable: true
additionalProperties: true
type: object
responses:
'200':
description: Operation result.
content:
application/json:
schema:
$ref: '#/components/schemas/DonationReceiptPreview'
'401':
description: Authentication is required.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
'403':
description: >-
The authenticated user lacks access to this workflow or its related
records.
'422':
description: >-
Gift, allocation, recognition, custom field or giving-source
validation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/RequestRejection'
security:
- bearerAuth: []
- apiKeyAuth: []
servers:
- url: https://api.gratona.com/v1
description: Gratona API
components:
schemas:
DonationReceiptPreview:
required:
- status
- reason
- trigger
- recipient
- previews
- unavailable_designations
- recipients
properties:
status:
type: string
enum:
- available
- skipped
- suppressed
- unavailable
example: available
reason:
type: string
example: no_template
nullable: true
trigger:
type: string
enum:
- pay_receipt
- pay_fail
example: pay_receipt
recipient:
properties:
id:
type: integer
example: 21
nullable: true
name:
type: string
example: Jane Donor
email:
type: string
example: jane@example.org
type: object
previews:
type: array
items:
properties:
label:
type: string
example: Education
subject:
type: string
example: Thank you for your gift
body:
description: Rendered HTML email preview.
type: string
example: Thank you for supporting Education.
template_id:
type: integer
example: 42
type: object
unavailable_designations:
type: array
items:
type: string
example: Education
recipients:
type: array
items:
properties:
role:
type: string
enum:
- primary
- soft_credit
example: primary
role_label:
type: string
example: Donor
nullable: true
donation_type:
type: string
example: default
nullable: true
status:
type: string
enum:
- available
- skipped
- suppressed
- unavailable
example: available
reason:
type: string
example: no_email
nullable: true
acknowledgement_path:
type: string
example: print
nullable: true
recipient:
properties:
id:
type: integer
example: 21
nullable: true
name:
type: string
example: Jane Donor
email:
type: string
example: jane@example.org
type: object
previews:
type: array
items:
properties:
label:
type: string
example: Education
subject:
type: string
example: Thank you for your gift
body:
description: Rendered HTML email preview.
type: string
example: Thank you for supporting Education.
template_id:
type: integer
example: 42
type: object
unavailable_designations:
type: array
items:
type: string
example: Education
template_setup_issues:
type: array
items:
description: >-
Source-specific receipt template review details and
designation label.
type: object
additionalProperties: true
type: object
type: object
UnauthorizedResponse:
title: UnauthorizedResponse
description: >-
Returned with HTTP 401 when the request lacks a valid Passport bearer
token, a valid `X-HYS-API-Key`, or a valid session. The body is the
simple `{message, status}` envelope emitted by `AuthenticateApiOrKey`.
required:
- message
- status
properties:
message:
description: >-
Always the literal string `Unauthorized` from the `auth.api_or_key`
middleware. Login endpoints return `Invalid Credentials` instead.
type: string
example: Unauthorized
status:
type: string
example: error
type: object
RequestRejection:
description: >-
Request or workflow rejection. Framework field-validation failures
contain errors; semantic rejections may contain message without errors;
legacy/provider failures may use error and error_code. The operation
description identifies the rejected condition. Domain responses may add
current revision, limits or other conflict context.
anyOf:
- $ref: '#/components/schemas/ValidationErrorResponse'
- $ref: '#/components/schemas/ErrorResponse'
- required:
- error
properties:
error:
description: Legacy or provider-facing error message.
type: string
example: The request could not be completed.
error_code:
description: Stable domain error code, when provided.
type: string
example: WORKFLOW_UNAVAILABLE
type: object
ValidationErrorResponse:
title: ValidationErrorResponse
description: >-
Returned with HTTP 422 when `Validator::make($data, $rules)` fails. The
`errors` map is keyed by the failing field name; each value is an array
of human-readable error messages for that field. Most controllers also
include a top-level `status: error`.
required:
- errors
properties:
errors:
description: >-
Map of field name to array of validator error messages. Example:
`{email: [The email field is required.], amount: [The amount must be
a number.]}`.
type: object
additionalProperties:
type: array
items:
type: string
status:
description: Always the literal string `error`.
type: string
example: error
message:
description: >-
Optional summary message — present on some endpoints, absent on
others.
type: string
example: The given data was invalid.
nullable: true
type: object
ErrorResponse:
title: ErrorResponse
description: >-
Generic error envelope used by most controllers. Most error responses
pair a human-readable `message` with `status: error`. Some endpoints
additionally include `errors` (validator errors), `error` (legacy
single-error string), `code`, or domain-specific context fields.
required:
- message
properties:
message:
description: Human-readable error message.
type: string
example: Something went wrong. Please try again.
status:
description: >-
Always the literal string `error` for failures. Some endpoints omit
this field.
type: string
example: error
error:
description: Legacy single error code/string used by older endpoints.
type: string
example: invalid_request
nullable: true
code:
description: >-
Optional application-level error code (not all endpoints populate
this).
type: string
example: DONOR_NOT_FOUND
nullable: true
type: object
securitySchemes:
bearerAuth:
type: http
description: Passport bearer token authentication for legacy admin sessions.
scheme: bearer
bearerFormat: JWT
apiKeyAuth:
type: apiKey
description: Gratona API key sent with the compatibility header X-HYS-API-Key.
name: X-HYS-API-Key
in: header
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.