A Donation object tracks the lifecycle of a Donation from creation and payment to disbursement to the nonprofit. Donations can be created during a Donation Session by the Hosted Donation Gateway or created directly by calling the [Create A Donation API](create-a-donation).
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/goodstack-donations-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Goodstack Services Donations API
version: v1
x-logo:
url: https://docs.goodstack.io/img/logo.png
altText: Goodstack logo
x-dark-logo:
url: https://docs.goodstack.io/img/icons/Logo-white.svg
altText: Goodstack logo
contact:
email: engineering-support@goodstack.io
name: Api support
description: '# Introduction
Goodstack API allows you to build good into your product by facilitating charitable donations.'
servers:
- url: https://api.goodstack.io
description: Production server
- url: https://sandbox-api.goodstack.io
description: Sandbox server
tags:
- name: Donations
description: 'A Donation object tracks the lifecycle of a Donation from creation and payment to disbursement to the nonprofit.
Donations can be created during a Donation Session by the Hosted Donation Gateway or created directly by calling the Create A Donation API.'
paths:
/v1/donations:
get:
security:
- SecretApiKey: []
summary: List Donations
description: 'Retrieve a list of donations.
PII fields (`firstName`, `lastName` & `email`) will be included or excluded depending on your partner settings.'
tags:
- Donations
parameters:
- in: query
name: userId
schema:
type: string
example: user_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
required: false
description: Filter results by userId.
- in: query
name: status
schema:
type: string
enum:
- ACTIVE
- REQUESTED_PAYMENT
- RECEIVED_PAYMENT
- DISBURSED
- CANCELLED
required: false
description: Filter results by status.
- in: query
name: startDate
schema:
type: string
format: date-time
description: Start date to retrieve users donations from.
example: '2020-10-13T17:46:54.000Z'
- in: query
name: endDate
schema:
type: string
format: date-time
description: End date to retrieve users donations from.
example: '2020-10-13T17:46:54.000Z'
- in: query
name: organisationId
schema:
type: string
example: organisation_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
required: false
description: Filter results by organisationId.
- $ref: '#/components/parameters/cursor'
- $ref: '#/components/parameters/pageSize'
responses:
'200':
description: Successfully listed Donations
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
anyOf:
- $ref: '#/components/schemas/DonationDirect'
- $ref: '#/components/schemas/DonationHosted'
object:
type: string
example: donation
totalResults:
type: integer
example: 33
pageSize:
type: integer
example: 25
_links:
$ref: '#/components/schemas/CursorLinks'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
IncorrectParams:
$ref: '#/components/examples/IncorrectParams'
CursorError:
$ref: '#/components/examples/Pagination.CursorError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/ForbiddenScope'
operationId: getV1Donations
x-operation-id-source: derived
post:
security:
- SecretApiKey: []
summary: Create a donation
description: 'Creates a new Donation of type `direct`. We will request payment from you for the Donations aggregated over a period. Goodstack and our associated foundations will then handle the ongoing safe and efficient disbursement of funds to the nonprofit.
Please note that if you are creating with a `userId` and no `organisationId` the user must be already supporting an organisation.'
parameters:
- in: header
name: Idempotency-Key
schema:
type: string
required: false
description: Idempotency key.
tags:
- Donations
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- type: object
title: DirectDonation with Organisation ID
properties:
amount:
description: Amount to be donated. A positive integer representing how much to donate in the smallest currency unit, for example 100 pence to donate £1.00.
type: integer
example: 120
currencyCode:
description: Three-letter ISO currency code. Only currency codes supported by our foundations will be accepted.
type: string
example: GBP
organisationId:
type: string
firstName:
type: string
maxLength: 255
lastName:
type: string
maxLength: 255
email:
type: string
maxLength: 255
consentedToBeContactedByOrg:
type: string
enum:
- 'yes'
- 'no'
anonymous:
type: string
enum:
- 'yes'
- 'no'
metadata:
type: object
description: '[Key-value data](/#section/Formats/Metadata) that you can attach to a Donation.
'
example:
key1: value1
key2: value2
required:
- amount
- currencyCode
- organisationId
- type: object
title: DirectDonation with User ID
properties:
amount:
type: integer
example: 120
currencyCode:
description: Three-letter ISO currency code.
type: string
example: GBP
userId:
type: string
example: user_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
organisationId:
type: string
firstName:
type: string
maxLength: 255
lastName:
type: string
maxLength: 255
email:
type: string
maxLength: 255
consentedToBeContactedByOrg:
type: string
enum:
- 'yes'
- 'no'
anonymous:
type: string
enum:
- 'yes'
- 'no'
metadata:
type: object
description: '[Key-value data](/#section/Formats/Metadata) that you can attach to a Donation.
'
example:
key1: value1
key2: value2
required:
- amount
- currencyCode
- userId
responses:
'200':
description: Successfully created a Donation
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/DonationDirect'
object:
type: string
example: donation
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
IncorrectParams:
$ref: '#/components/examples/IncorrectParams'
UserNotFound:
$ref: '#/components/examples/Donations.UserNotFound'
MissingOrganisation:
$ref: '#/components/examples/Donations.MissingOrganisation'
WrongTargetCurrency:
$ref: '#/components/examples/Donations.WrongTargetCurrency'
WrongPartnerCurrency:
$ref: '#/components/examples/Donations.WrongPartnerCurrency'
CannotAcceptDonations:
$ref: '#/components/examples/Donations.CannotAcceptDonations'
GiftAidMissing:
$ref: '#/components/examples/Donations.GiftAidMissing'
OriginalCallInProgress:
$ref: '#/components/examples/Idempotency.OriginalCallInProgress'
SameKeyDifferentData:
$ref: '#/components/examples/Idempotency.SameKeyDifferentData'
KeyInUse:
$ref: '#/components/examples/Idempotency.KeyInUse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/ForbiddenScope'
operationId: postV1Donations
x-operation-id-source: derived
/v1/donations/{id}:
parameters:
- in: path
name: id
schema:
type: integer
required: true
description: Id of the Donation.
get:
security:
- SecretApiKey: []
summary: Retrieve a Donation
description: 'Retrieve a donation by its ID.
PII fields (`firstName`, `lastName` & `email`) will be included or excluded depending on your partner settings.'
tags:
- Donations
responses:
'200':
description: Successfully retrieves a Donation
content:
application/json:
schema:
type: object
properties:
data:
oneOf:
- $ref: '#/components/schemas/DonationDirect'
- $ref: '#/components/schemas/DonationHosted'
object:
type: string
example: donation
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/ForbiddenScope'
'404':
$ref: '#/components/responses/NotFound'
operationId: getV1DonationsById
x-operation-id-source: derived
patch:
security:
- SecretApiKey: []
summary: Edit a Donation
description: Update the recipient organisation, metadata of a Donation. The recipient organisation can only be changed for `direct` type Donations created directly through the Create A Donation API that are in an `ACTIVE` status.
tags:
- Donations
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
organisationId:
type: string
metadata:
type: object
description: '[Key-value data](/#section/Formats/Metadata) that you can attach to a Donation.
'
example:
key1: value1
key2: value2
responses:
'200':
description: Successfully edited a particular donation
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/DonationDirect'
object:
type: string
example: donation
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
IncorrectParams:
$ref: '#/components/examples/IncorrectParams'
InvalidState:
$ref: '#/components/examples/Donations.InvalidState'
InvalidMetadata:
$ref: '#/components/examples/Donations.InvalidMetadata'
InvalidTypeForEditOrganisation:
$ref: '#/components/examples/Donations.InvalidTypeForEditOrganisation'
MissingOrganisation:
$ref: '#/components/examples/Donations.MissingOrganisation'
WrongTargetCurrency:
$ref: '#/components/examples/Donations.WrongTargetCurrency'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/ForbiddenScope'
operationId: patchV1DonationsById
x-operation-id-source: derived
/v1/donations/{id}/cancel:
parameters:
- in: path
name: id
schema:
type: integer
required: true
description: Id of the Donation to cancel.
post:
security:
- SecretApiKey: []
summary: Cancel a Donation
description: Applicable only to `direct` type Donations created directly through the Create A Donation API.
tags:
- Donations
responses:
'200':
description: Successfully cancelled a Donation
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/DonationDirect'
object:
type: string
example: donation
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
InvalidState:
$ref: '#/components/examples/Donations.InvalidState'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/ForbiddenScope'
operationId: postV1DonationsByIdCancel
x-operation-id-source: derived
components:
examples:
Donations.UserNotFound:
summary: Donation - User not found
description: User not found
value:
error:
code: donation/user_not_found
title: Bad request
message: User not found
Donations.WrongPartnerCurrency:
summary: Donation - Wrong partner currency
description: You can not accept donations in this currency
value:
error:
code: donation/wrong_partner_currency
title: Bad request
message: You can only donate in GBP
Idempotency.OriginalCallInProgress:
summary: Idempotency - Original call in progress
description: Original call with this idempotency key is still in progress, please wait and try again
value:
error:
code: idempotency/original_call_in_progress
title: Bad request
message: Original call with this idempotency key is still in progress
IncorrectParams:
summary: 400 Incorrect Parameters
description: Bad Request - Incorrect parameters
value:
error:
code: bad_request
title: Bad request
message: One or more of the inputs were invalid
reasons:
- pageSize must be greater than or equal to 0
Donations.InvalidState:
summary: Donation - Invalid state
description: Donation is not in a valid state to update
value:
error:
code: donation/invalid_state
title: Bad request
message: Donation is not in a valid state to update
Donations.WrongTargetCurrency:
summary: Donation - Wrong target currency
description: The organisation can not accept donations in this currency
value:
error:
code: donation/wrong_target_currency
title: Bad request
message: This organisation can not accept donations in GBP
Donations.MissingOrganisation:
summary: Donation - Organisation missing
description: User must be supporting a cause, or organisationId must be provided
value:
error:
code: donation/missing_organisation
title: Bad request
message: User must be supporting a cause, or organisationId must be provided
Donations.InvalidMetadata:
summary: 400 Bad request
description: Metadata provided not correct format
value:
error:
title: Bad request
message: Metadata can only contain from 1 up to 20 keys, with key names up to 50 characters long and values up to 500 characters long
code: donation/invalid_metadata
Pagination.CursorError:
summary: Error in cursor parameter
description: We were unable to decode the cursor
value:
error:
code: pagination/cursor_error
title: Bad request
message: Unable to find the next page
Idempotency.KeyInUse:
summary: Idempotency - Key in use
description: Idempotency Key is already in use
value:
error:
code: idempotency/key_already_in_use
title: Bad request
message: Idempotency Key is already in use
Idempotency.SameKeyDifferentData:
summary: Idempotency - Data has changed from previous request
description: Data has changed from previous request with this key
value:
error:
code: idempotency/same_key_different_data
title: Bad request
message: Data has changed from previous request
Donations.CannotAcceptDonations:
summary: Donation - Organisation can not accept donations
description: This Organisation can not accept donations at this time
value:
error:
code: donation/cannot_accept_donations
title: Bad request
message: This organisation is currently unable to accept donations
Donations.InvalidTypeForEditOrganisation:
summary: Donation - Organisation cannot be updated for this type of donation
description: Organisation cannot be updated for this type of donation
value:
error:
code: donation/cannot_edit_organisation_invalid_donation_type
title: Bad request
message: Organisation cannot be updated for this type of donation
Donations.GiftAidMissing:
summary: Donation - GiftAid missing
description: Can not find required gift aid for this donation
value:
error:
code: donation/gift_aid_missing
title: Bad request
message: Can not find required gift aid for this donation
responses:
ForbiddenScope:
description: Forbidden (scope)
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: forbidden
title:
type: string
example: Forbidden
message:
type: string
example: Access is denied due to missing scope permissions
NotFound:
description: The specified resource was not found
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: not_found
title:
type: string
example: Resource not found
message:
type: string
example: This endpoint is unavailable or can not be found
Unauthorized:
description: Unauthorized
schemas:
DonationHosted:
type: object
title: hosted donation
allOf:
- $ref: '#/components/schemas/DonationBase'
- type: object
properties:
type:
type: string
enum:
- hosted
hosted:
type: object
description: Contains additional fields available for hosted Donations.
properties:
sessionId:
type: string
example: donationsession_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
description: Donation Session Id
DonationDirect:
title: direct donation
type: object
allOf:
- $ref: '#/components/schemas/DonationBase'
- type: object
properties:
type:
type: string
enum:
- direct
CursorLinks:
type: object
properties:
current:
type: string
example: https://.../v1/...?cursor=eyJ2Ijox...N3AifQ%3D%3D
next:
type: string
example: https://.../v1/...?cursor=eyJ2Ijox...N3AifQ%3D%3D
prev:
type: string
example: https://.../v1/...?cursor=eyJ2Ijox...N3AifQ%3D%3D
DonationBase:
type: object
properties:
id:
type: string
example: donation_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
userId:
type:
- string
- 'null'
organisationId:
type:
- string
- 'null'
amount:
description: Donation amount. A positive integer representing donation amount in the smallest currency unit, for example 100 pence for a donation of £1.00.
type: integer
example: 123
currencyCode:
description: Three-letter ISO currency code
type: string
example: AUD
createdAt:
type: string
format: date-time
example: '2020-10-13T17:46:54.000Z'
status:
type: string
enum:
- ACTIVE
- REQUESTED_PAYMENT
- RECEIVED_PAYMENT
- DISBURSED
- CANCELLED
firstName:
type:
- string
- 'null'
description: Users first name.
lastName:
type:
- string
- 'null'
description: Users last name.
email:
type:
- string
- 'null'
description: Users email.
consentedToBeContacted:
type:
- string
- 'null'
enum:
- 'yes'
- 'no'
description: Whether the user consented to be contacted by the benefitting organisation.
anonymous:
type:
- string
- 'null'
enum:
- 'yes'
- 'no'
description: Whether the user wants to share their donation publicly or not.
metadata:
type:
- object
- 'null'
additionalProperties:
type: string
description: Key-value data that you can attach to an object.
giftAidId:
type:
- string
- 'null'
cancelledAt:
type:
- string
- 'null'
format: date-time
example: '2020-10-13T17:46:54.000Z'
donationRequestId:
type:
- string
- 'null'
example: donationrequest_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
accountId:
type:
- string
- 'null'
example: account_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
title:
type: string
message:
type: string
reasons:
type:
- array
- 'null'
items:
type: string
parameters:
cursor:
in: query
name: cursor
required: false
schema:
type: string
example: eyJ2IjoxLCJkIjoibmV4dCIsImlkIjoiZG9uYXRpb25fMDAwMDAwQnc3U1BhMHBxOHBRMFFsckVaWGFaN3AifQ%3D%3D
description: A cursor that points to where to start the page
pageSize:
in: query
name: pageSize
required: false
schema:
type: integer
minimum: 0
default: 25
description: How many items per page, for pagination.
securitySchemes:
PublishableApiKey:
type: apiKey
in: header
name: Authorization
description: API key starting with 'pk_' that can be made public
SecretApiKey:
type: apiKey
in: header
description: API key starting with 'sk_' that must be kept secure
name: Authorization
DonationSessionToken:
type: apiKey
in: header
name: donation-session-token
description: Donation session token
x-tagGroups:
- name: NONPROFIT DATA
tags:
- Organisations
- Countries
- Registries
- Categories
- name: NONPROFIT VALIDATIONS
tags:
- Validation Requests
- Validation Request Documents
- Validation Invites
- Validation Submissions
- Validation Submission Documents
- Validation Submission Configuration
- Monitoring Subscriptions
- Eligibility Subscriptions
- Activities
- Agent Verifications
- name: MONETARY DONATIONS
tags:
- Donations
- Donation Sessions
- Users
- Gift Aid
- name: WEBHOOK SUBSCRIPTIONS
tags:
- Webhook Subscriptions