Goodstack Donation Sessions API

openapi: 3.2.0
info:
  title: Goodstack Services Donation Sessions 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. We achieve this through the API''s listed and specified in this documentation. For all donations using the Goodstack API, Goodstack handles the vetting and validation of the good causes and onward the disbursement of the donation. The Goodstack API is organised around REST. All API responses, including errors, return JSON and use standard HTTP response codes. In all API requests you must specify the content-type HTTP header as application/json. All API requests must be made over HTTPS. # Authentication


    Authenticate your API requests by setting your live secret API key in the Authorization header. Two keys are provided to you, a publishable key prefixed with `pk_` and a secret key prefixed with `sk_`. Publishable API keys are meant solely to identify your goodstack account. These can safely be published in places like your JavaScript code, or in an Android or iPhone app and are meant for usage with our SDKs. Secret API keys should be kept confidential and only used in secure server environments. Anywhere that accepts a Publishable key will also accept a Secret key, but routes marked to accept a Secret key will not accept a Publishable key. # Formats


    ## IDs


    All ID fields are case-sensitive. For example, `abc123` and `ABC123` are treated as different IDs. ## Dates


    Dates are encoded as strings following the ISO 8601 standard `2025-08-01T12:00:00.000Z`. ## Pagination


    A maximum of 100 objects can be returned per request and the limit can be specified by using the pageSize query parameter. By default, the pageSize is set to 25. A `_links` object is included in paginated responses, which contains `next` and `prev` URLs to retrieve the next or previous pages of results. ## Monetary Values


    Throughout the API, monetary values are encoded as integers representing the amount in the smallest currency unit, for example 100 cents for a donation of $1.00. Currency is encoded as a string following the ISO 4217 standard (e.g. `USD`). ## Metadata


    Some objects have a metadata parameter that you can use to store key-value data. You can specify up to 20 keys, with key names up to 40 characters long and values up to 250 characters long. ## Errors


    The API returns standard HTTP response codes to indicate success or failure of API requests. Errors may include a custom error message. Error objects have these attributes, an `id`, a `message` corresponding to the HTTP response phrase of the error,

    an optional `invalid-params` attribute detailing issues with the request. An example error object returned from the API:

    ```json

    {

    error: {

    code: ''bad_request'',

    title: ''Bad request'',

    message: ''Something is wrong with your request, please check any parameters and try again'',

    reasons: [''amount is a required field'']

    }

    }

    ```


    A summary of the HTTP status codes returned from the api is listed in the table below. | Code | Title | Description |

    | ------------- |-------------| -----|

    | 200 | Success | Request successful |

    | 204 | No Content | Request successful with no content returned |

    | 400 | Bad Request | Request was invalid |

    | 401 | Unauthorised | Authorization header is invalid |

    | 403 | Forbidden | Insufficient permissions |

    | 404 | Not Found | Resource does not exist |

    | 429 | Too Many Requests | Rate Limited |

    | 500s | Internal Server Error | Something went wrong with the Goodstack API |


    # Enum Values


    Generally enum fields in our API are open-ended. New values may be added to an enum and this is not considered a breaking change. ## Integrating safely


    If your code handles enum values exhaustively — for example, a switch without a default case, or deserialisation into a strict typed enum — an unrecognised value may cause errors. We recommend adding a fallback handler for unknown enum values, so that any new value that does reach your integration degrades gracefully rather than failing.'
servers:
- url: https://api.goodstack.io
  description: Production server
- url: https://sandbox-api.goodstack.io
  description: Sandbox server
tags:
- name: Donation Sessions
paths:
  /v1/donation-sessions:
    get:
      security:
      - SecretApiKey: []
      summary: List Donation Sessions
      tags:
      - Donation Sessions
      parameters:
      - $ref: '#/components/parameters/direction'
      - $ref: '#/components/parameters/cursor'
      - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          description: Successfully lists Donation Sessions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DonationSession'
                  object:
                    type: string
                    example: donation_session
                  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'
                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: getV1DonationSessions
      x-operation-id-source: derived
    post:
      security:
      - SecretApiKey: []
      summary: Create a Donation Session
      description: 'To create a Donation Session you must supply the `organisationId` of the nonprofit you want to let your user donate to.


        After creating the Donation Session, direct your user to the URL for the hosted Donation gateway returned in the response. Your user will receive an email receipt after a successful Donation.


        The status field of the Donation Session object after creation will be `open`. After a successful Donation is made the status will transition to `completed` otherwise if no Donation is completed before the `expiresAt` time the status will be `expired`.'
      tags:
      - Donation Sessions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                organisationId:
                  description: Organisation that can be donated to during Donation session.
                  type: string
                  example: organisation_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
                successUrl:
                  description: Optional URL the donor will be directed to after making a Donation.
                  type: string
                  example: https://example.com/donation-completed
                userId:
                  description: Id of the User who this donation belongs to, if one exists.
                  type: string
                  example: user_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
                metadata:
                  type: object
                  description: '[Key-value data](/#section/Formats/Metadata) that you can attach to a DonationSession. When a Donation is created from a DonationSession, the DonationSession copies its metadata to the Donation.

                    '
                  example:
                    key1: value1
                    key2: value2
                language:
                  description: Donation session's default language
                  type: string
                  enum:
                  - en-US
                  - en-GB
                  - en-IE
                  - en-NZ
                  - de-DE
                  - de-CH
                  - de-AT
                  - fr-FR
                  - fr-BE
                  - it-IT
                  - nl-NL
                  - sv-SE
                  - da-DK
                  - pl-PL
                  - en-AU
                  - fr-CA
                  - en-CA
                  - es-ES
                  - ja-JP
                  - es-MX
                  - ko-KR
                  - pt-BR
                  - en-SG
                  - ms-MY
                  - th-TH
                  - id-ID
                  - vi-VN
                  - hu-HU
                  - cs-CZ
                  - ro-RO
                  - fil-PH
                  - tr-TR
                currency:
                  type: string
                  example: GBP
                  description: 3-letter currency code
              required:
              - organisationId
      responses:
        '200':
          description: Successfully created a Donation Session
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DonationSession'
                  object:
                    type: string
                    example: donation_session
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                BadRequest:
                  $ref: '#/components/examples/BadRequest'
                IncorrectParams:
                  $ref: '#/components/examples/IncorrectParams'
                OrganisationNotFound:
                  $ref: '#/components/examples/DonationSession.OrganisationNotFound'
                InvalidMetadata:
                  $ref: '#/components/examples/DonationSession.InvalidMetadata'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenScope'
      operationId: postV1DonationSessions
      x-operation-id-source: derived
  /v1/donation-sessions/{id}:
    get:
      security:
      - SecretApiKey: []
      summary: Retrieve donation session
      tags:
      - Donation Sessions
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
        description: Id of the donation session to retrieve.
      responses:
        '200':
          description: Successfully retrieved a donation session
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DonationSession'
                  object:
                    type: string
                    example: donation_session
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                BadRequest:
                  $ref: '#/components/examples/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ForbiddenScope'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getV1DonationSessionsById
      x-operation-id-source: derived
  /v1/donation-sessions/{sessionId}/donations:
    patch:
      security:
      - PublishableApiKey: []
      summary: Update donor details for donation session
      description: 'Updates the email address, name, consent preferences, and/or gift note for any donations linked to the specified donation session.

        This endpoint requires both a public API key and a valid donation session token in the headers.

        At least one field (email, firstName, lastName, consentedToBeContactedByOrg, or giftNote) must be provided in the request body.

        If no donation is linked to the session, the endpoint will return success without making any changes.'
      tags:
      - Donation Sessions
      parameters:
      - in: path
        name: sessionId
        schema:
          type: string
        required: true
        description: Id of the donation session whose linked donations should be updated.
        example: donation_session_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
      - in: header
        name: donation-session-token
        schema:
          type: string
        required: true
        description: Valid donation session token for authentication.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  description: New email address for the donor
                  type: string
                  format: email
                  maxLength: 255
                  example: donor@example.com
                firstName:
                  description: New first name for the donor
                  type: string
                  maxLength: 255
                  example: John
                lastName:
                  description: New last name for the donor
                  type: string
                  maxLength: 255
                  example: Doe
                consentedToBeContactedByOrg:
                  description: Whether the donor consents to be contacted by the organization
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                  example: 'yes'
                giftNote:
                  description: Optional personal message from the donor to the organisation receiving the gift
                  type: string
                  maxLength: 500
                  example: Happy Birthday! Hope this helps with your amazing work.
              minProperties: 1
              additionalProperties: false
            examples:
              UpdateEmail:
                summary: Update email only
                value:
                  email: newemail@example.com
              UpdateFirstName:
                summary: Update first name only
                value:
                  firstName: Jane
              UpdateLastName:
                summary: Update last name only
                value:
                  lastName: Smith
              UpdateConsent:
                summary: Update consent only
                value:
                  consentedToBeContactedByOrg: 'no'
              UpdateGiftNote:
                summary: Update gift note only
                value:
                  giftNote: Thank you for your incredible work helping families in need!
              UpdateMultipleFields:
                summary: Update multiple fields
                value:
                  email: updated@example.com
                  firstName: John
                  lastName: Doe
                  consentedToBeContactedByOrg: 'yes'
                  giftNote: With love and gratitude for all you do!
      responses:
        '200':
          description: Successfully updated donor details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      updated:
                        type: boolean
                        example: true
                  object:
                    type: string
                    example: donation_session
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                BadRequest:
                  $ref: '#/components/examples/BadRequest'
                IncorrectParams:
                  $ref: '#/components/examples/IncorrectParams'
                MissingFields:
                  summary: At least one field required
                  value:
                    error:
                      code: bad_request
                      message: At least one field (email, consentedToBeContactedByOrg, firstName, or lastName) must be provided
                      title: Bad request
                InvalidEmail:
                  summary: Invalid email format
                  value:
                    error:
                      code: bad_request
                      message: Invalid email
                      title: Bad request
                InvalidConsent:
                  summary: Invalid consent value
                  value:
                    error:
                      code: bad_request
                      message: Invalid enum value. Expected 'yes' | 'no', received 'maybe'
                      title: Bad request
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Forbidden - missing donation session token or invalid scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                ForbiddenScope:
                  $ref: '#/components/examples/ForbiddenScope'
                MissingToken:
                  summary: Missing donation session token
                  value:
                    error:
                      code: donation_session/donation_session_token_missing
                      message: Donation session token missing
                      title: Forbidden
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: patchV1DonationSessionsBySessionIdDonations
      x-operation-id-source: derived
components:
  examples:
    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
    BadRequest:
      summary: 400 Bad Request
      description: Bad Request
      value:
        error:
          code: bad_request
          title: Bad request
          message: Something is wrong with your request, please check any parameters and try again
    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
    ForbiddenScope:
      summary: 403 Forbidden (Scope)
      description: Forbidden - Missing scope permission
      value:
        error:
          code: forbidden
          title: Forbidden
          message: Access is denied due to missing scope permissions
    DonationSession.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_session/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
    DonationSession.OrganisationNotFound:
      summary: 400 Bad request
      description: Organisation not found
      value:
        error:
          title: Bad request
          message: Organisation not found
          code: donation_session/organisation_not_found
    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
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            title:
              type: string
            message:
              type: string
            reasons:
              type:
              - array
              - 'null'
              items:
                type: string
    Metadata:
      type:
      - object
      - 'null'
      description: '[Key-value data](/docs/api/goodstack-services#metadata) that you can attach to an object.

        '
      additionalProperties:
        type: string
      example:
        key1: value1
        key2: value2
    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
    DonationSession:
      type: object
      properties:
        id:
          type: string
          example: donationsession_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        organisationId:
          type: string
          example: organisation_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        successUrl:
          description: Optional URL the donor will be directed to after making a donation.
          type:
          - string
          - 'null'
          example: https://example.com/donation-completed
        userId:
          description: Id of the User who this donation belongs to, if one exists.
          type:
          - string
          - 'null'
          example: user_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        accountId:
          description: Id of the Account who this donation belongs to, if one exists.
          type:
          - string
          - 'null'
          example: account_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        url:
          type: string
          example: https://donate.poweredbypercent.com/donation-session
        status:
          type: string
          enum:
          - open
          - completed
          - expired
        createdAt:
          type: string
          format: date-time
          example: '2021-10-13T17:46:54.000Z'
        expiresAt:
          type: string
          format: date-time
          example: '2021-10-13T17:46:54.000Z'
        language:
          type: string
          example: en-GB
          default: en-GB
        metadata:
          allOf:
          - $ref: '#/components/schemas/Metadata'
          - description: '[Key-value data](/docs/api/goodstack-services#metadata) that you can attach to an object. When a Donation is created from a DonationSession, the DonationSession copies its metadata to the Donation.

              '
        currency:
          type:
          - string
          - 'null'
          example: GBP
  parameters:
    direction:
      in: query
      name: direction
      required: false
      schema:
        type: string
        enum:
        - ASC
        - DESC
      description: Which way to sort by the given 'sort' field.  Default DESC
    pageSize:
      in: query
      name: pageSize
      required: false
      schema:
        type: integer
        minimum: 0
        default: 25
      description: How many items per page, for pagination.
    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
  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
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: unauthorized
                  title:
                    type: string
                    example: Unauthorized
                  message:
                    type: string
                    example: Access is denied due to invalid credentials
  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
    SCIMBearer:
      type: http
      scheme: bearer
      description: 'SCIM API key issued for the partner, presented as a bearer token in the

        `Authorization` header. The key is bound to a single partner and the

        partner must have the `scim_api` scope enabled. A missing or invalid key

        returns `401`; a valid key for a partner without the scope also returns

        `401` (`detail: "scim feature not enabled for this partner"`).

        '
x-tagGroups:
- name: NONPROFIT DATA
  tags:
  - Organisations
  - Countries
  - Registries
  - Categories
  - Organisation Branding
- 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
  - Monetary Donation Verifications
- name: WORKPLACE GIVING
  tags:
  - Employees
  - Giving Donations
  - Donation Match Request
  - Fundraising
  - Volunteering
  - Gamification
  - Campaigns
  - Budgets
  - Donation Wallets
- name: WEBHOOK SUBSCRIPTIONS
  tags:
  - Webhook Subscriptions
- name: WEBHOOK EVENTS
  tags:
  - Agent Verification Events
  - Country Compliance Check Events
  - Donation Events
  - Eligibility Subscription Events
  - Monitoring Subscription Events
  - Validation Request Events
  - Validation Submission Events
  - Monetary Donation Verification Events
x-provenance:
  method: harvested
  publisher: Goodstack
  source: https://reference.poweredbypercent.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)