Blackbaud Charges API

openapi: 3.2.0
info:
  title: 'Blackbaud SKY API: Receivables Charges API'
  description: This API manages receivables, including clients, billing items, credits, charges, and invoices.
  version: '1.0'
  x-apievangelist-provenance:
    source: https://developer.sky.blackbaud.com/developer/apis/receivables
    method: assembled from Blackbaud's public API Management developer data API (operations, parameters, representations, examples, stored definitions); nothing authored
    assembled: '2026-10-14'
servers:
- url: https://api.sky.blackbaud.com/receivables
security:
- Bb-Api-Subscription-Key: []
  OAuth2: []
tags:
- name: Charges
paths:
  /v1/charges:
    get:
      operationId: ListCharges
      summary: Get a list of charges by page
      description: This returns a list of charges.
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: '25'
        description: The maximum number of items to return.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
        description: How many items to skip before returning the results.
      responses:
        '200':
          description: Returned when the operation succeeds. The response body contains a list of charges.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeListViewList'
              example:
                charges:
                - id: 84873654-2697-4b56-afc8-57dd45676276
                  lookup_id: '190'
                  client:
                    contact_id: '123'
                    contact_type: Person
                    third_party_billing: false
                  charge_date: '2021-01-01T12:00:00Z'
                  due_date: '2021-01-30T12:00:00Z'
                  post_date: '2021-01-31T12:00:00Z'
                  post_status: NotYetPosted
                  billing_item_id: c98dd541-4866-4806-ad56-66bca2bcc163
                  description: Test description
                  service_provider: ServiceProvider
                  flat_rate:
                    amount: 100
                    allow_changes_to_amount: false
                  variable_rate:
                    unit_of_measure_entry:
                      id: 1c079590-7790-4456-9d0f-5fa50d7aacff
                      value: Each
                    quantity: 1
                    quantity_decimals: 2
                    unit_price: 1.5
                    unit_price_decimals: 2
                    allow_changes_quantity_and_unit_price: false
                    trade_discount_percent: 0
                    trade_discount_amount: 0
                    amount: 1.5
                  sales_tax_billing_item:
                    id: '1'
                    value: '1'
                    amount: 1
                  charge_amount: 22
                  balance: 0
                  added_by: Supervisor
                  date_added: '2021-01-01T12:00:00Z'
                  last_changed_by: Supervisor
                  date_changed: '2021-01-01T12:00:00Z'
                limit: 10
                offset: 0
        '400':
          description: Returned when the request is not in the appropriate format.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponseTypes'
              example:
                type: urn:blackbaud:validation-error
                title: One or more validation errors occurred.
                status: 400
                detail: 'Transaction is missing required custom fields

                  '
                values:
                  errors:
                    property_name: custom_fields
                    error_message: Transaction is missing required custom fields
                    error_code: TransactionHasRequiredCustomFields
                trace_id: e566235f7b89ec65570213e86c42b059
                span_id: fda5afb92a47816e
        '403':
          description: Returned when the user does not have permission to view charges.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ForbiddenProblemDetails'
              example:
                type: urn:blackbaud:forbidden
                title: The requested action is forbidden.
                status: 403
                extensions: {}
      tags:
      - Charges
  /v1/charges/{id}:
    get:
      operationId: GetCharge
      summary: Get a charge
      description: This gets a charge by ID.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: The ID of the charge.
      responses:
        '200':
          description: Returned when the operation succeeds. The response body contains a charge.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeListView'
              example:
                id: 84873654-2697-4b56-afc8-57dd45676276
                lookup_id: '190'
                client:
                  contact_id: '123'
                  contact_type: Person
                  third_party_billing: false
                charge_date: '2021-01-01T12:00:00Z'
                due_date: '2021-01-30T12:00:00Z'
                post_date: '2021-01-31T12:00:00Z'
                post_status: NotYetPosted
                billing_item_id: c98dd541-4866-4806-ad56-66bca2bcc163
                description: Test description
                service_provider: ServiceProvider
                flat_rate:
                  amount: 100
                  allow_changes_to_amount: false
                variable_rate:
                  unit_of_measure_entry:
                    id: 1c079590-7790-4456-9d0f-5fa50d7aacff
                    value: Each
                  quantity: 1
                  quantity_decimals: 2
                  unit_price: 1.5
                  unit_price_decimals: 2
                  allow_changes_quantity_and_unit_price: false
                  trade_discount_percent: 0
                  trade_discount_amount: 0
                  amount: 1.5
                sales_tax_billing_item:
                  id: '1'
                  value: '1'
                  amount: 1
                charge_amount: 22
                balance: 0
                added_by: Supervisor
                date_added: '2021-01-01T12:00:00Z'
                last_changed_by: Supervisor
                date_changed: '2021-01-01T12:00:00Z'
        '404':
          description: Returned when the specified charge is not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: urn:blackbaud:model-validation-error
                title: One or more validation errors occurred.
                status: 400
                detail: Workflow Correlation Id was required but not supplied.
                trace_id: 0092384aa2c24842a550a0137bbf3172
                span_id: f7c9d108335d479588f5f165ca17a5e3
        '400':
          description: Returned when the request is not in the appropriate format.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponseTypes'
              example:
                type: urn:blackbaud:validation-error
                title: One or more validation errors occurred.
                status: 400
                detail: 'Transaction is missing required custom fields

                  '
                values:
                  errors:
                    property_name: custom_fields
                    error_message: Transaction is missing required custom fields
                    error_code: TransactionHasRequiredCustomFields
                trace_id: e566235f7b89ec65570213e86c42b059
                span_id: fda5afb92a47816e
        '403':
          description: Returned when the user does not have permission to view the charge.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ForbiddenProblemDetails'
              example:
                type: urn:blackbaud:forbidden
                title: The requested action is forbidden.
                status: 403
                extensions: {}
      tags:
      - Charges
components:
  schemas:
    ChargeListViewList:
      required:
      - charges
      - limit
      - offset
      type: object
      properties:
        charges:
          type: array
          items:
            $ref: '#/components/schemas/ChargeListView'
          description: The list of charges.
        limit:
          type: integer
          description: The maximum number of items to return.
          format: int32
        offset:
          type: integer
          description: The number of items skipped before this list was created.
          format: int32
      additionalProperties: false
      description: List of the charges for sql list
      x-bb-suppressions:
      - list_operation_pagination_style
    Contact:
      required:
      - contact_id
      - contact_type
      type: object
      properties:
        contact_id:
          minLength: 1
          type: string
          description: The ID of the contact.
        name:
          type:
          - string
          - 'null'
          description: The contact name.
        contact_type:
          $ref: '#/components/schemas/ContactType'
        third_party_billing:
          type: boolean
          description: Whether the client is used for third-party billing.
        client_status:
          type:
          - string
          - 'null'
          description: The client status.
      additionalProperties: false
      description: The contact.
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be "about:blank".
        title:
          type:
          - string
          - 'null'
          description: A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see [RFC7231], Section 3.4).
        status:
          type:
          - integer
          - 'null'
          description: The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type:
          - string
          - 'null'
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
        trace_id:
          type: string
          description: A request ID that can be provided to Blackbaud Support that may help with further troubleshooting.
        span_id:
          type: string
          description: A request ID that can be provided to Blackbaud Support that may help with further troubleshooting.
      additionalProperties: {}
      description: A machine-readable format for specifying errors in HTTP API responses based on https://tools.ietf.org/html/rfc7807.
    ForbiddenProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be "about:blank".
        title:
          type:
          - string
          - 'null'
          description: A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see [RFC7231], Section 3.4).
        status:
          type:
          - integer
          - 'null'
          description: The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type:
          - string
          - 'null'
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
        trace_id:
          type: string
          description: A request ID that can be provided to Blackbaud Support that may help with further troubleshooting.
        span_id:
          type: string
          description: A request ID that can be provided to Blackbaud Support that may help with further troubleshooting.
      additionalProperties: {}
      description: Problem details for 403 Forbidden responses
    ValidationErrorResponseTypes:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be "about:blank".<br/><br/>Available values:<table><tr><th>type</th><th>detail</th></tr><tr><td>urn:blackbaud:model-validation-error</td><td>A model validation rule was violated, such as a missing required field.</td></tr><tr><td>urn:blackbaud:validation-error</td><td>One or more validation errors occurred.</td></tr></table>
        title:
          type:
          - string
          - 'null'
          description: A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see [RFC7231], Section 3.4).
        status:
          type:
          - integer
          - 'null'
          description: The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type:
          - string
          - 'null'
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
        trace_id:
          type: string
          description: A request ID that can be provided to Blackbaud Support that may help with further troubleshooting.
        span_id:
          type: string
          description: A request ID that can be provided to Blackbaud Support that may help with further troubleshooting.
      additionalProperties: {}
      description: A machine-readable format for specifying errors in HTTP API responses based on https://tools.ietf.org/html/rfc7807.
      x-bb-error-types:
      - urn:blackbaud:model-validation-error
      - urn:blackbaud:validation-error
    ChargeListView:
      required:
      - balance
      - billing_item_id
      - billing_item_name
      - charge_amount
      - charge_date
      - client
      - due_date
      - id
      - lookup_id
      - post_date
      - post_status
      type: object
      properties:
        id:
          minLength: 1
          type: string
          description: The ID of the charge.
        lookup_id:
          minLength: 1
          type: string
          description: The ID of the lookup.
        notes:
          type:
          - string
          - 'null'
          description: The optional notes.
        client:
          $ref: '#/components/schemas/Contact'
        charge_date:
          type: string
          description: The original charge transaction time.
          format: date-time
        due_date:
          type: string
          description: The charge due date.
          format: date-time
        post_date:
          type: string
          description: The charge post date.
          format: date-time
        post_status:
          $ref: '#/components/schemas/PostStatus'
        print_status:
          $ref: '#/components/schemas/PrintStatus'
        billing_item_id:
          minLength: 1
          type: string
          description: The billing item.
        billing_item_name:
          minLength: 1
          type: string
          description: The billing item name.
        description:
          type:
          - string
          - 'null'
          description: 'The description of the billing item.

            Defaults from billing item, but user can override.'
        service_provider:
          type:
          - string
          - 'null'
          description: The service provider for the charge.
        flat_rate:
          $ref: '#/components/schemas/FlatRate'
        variable_rate:
          $ref: '#/components/schemas/VariableRate'
        sales_tax_billing_item:
          $ref: '#/components/schemas/SalesTaxItem'
        charge_amount:
          type: number
          description: The amount calculated from billing item values.
          format: decimal
        balance:
          type: number
          description: Total amount outstanding = committed amount - paid amount
          format: decimal
        added_by:
          type:
          - string
          - 'null'
          description: The user name who created the record.
        date_added:
          type: string
          description: The record create date.
          format: date-time
        last_changed_by:
          type:
          - string
          - 'null'
          description: The user name who last changed the record.
        date_changed:
          type:
          - string
          - 'null'
          description: The record last changed date.
          format: date-time
      additionalProperties: false
      description: Used to represent core charge information
    ContactType:
      title: ContactType
      enum:
      - Unknown
      - Person
      - Organization
      type: string
      description: Contact type
    FlatRate:
      type: object
      properties:
        amount:
          type:
          - number
          - 'null'
          description: The default flat rate.
          format: decimal
        allow_changes_to_amount:
          type: boolean
          description: Whether the user can edit the billing item amount after it's applied. For example, on a charge.
      additionalProperties: false
      description: The flat rate item details.
    SalesTaxItem:
      required:
      - id
      - value
      type: object
      properties:
        id:
          minLength: 1
          type: string
          description: ID
        value:
          minLength: 1
          type: string
          description: Value
        amount:
          type: number
          description: Amount
          format: decimal
      additionalProperties: false
      description: 'The sales tax item.

        Subset of BillingItemCore'
    VariableRate:
      required:
      - quantity
      - quantity_decimals
      - unit_price_decimals
      type: object
      properties:
        unit_of_measure_entry:
          $ref: '#/components/schemas/ReceivablesCodeTableEntry'
        quantity:
          type: number
          description: The quantity sold for a specified unit.
          format: decimal
        quantity_decimals:
          type: integer
          description: The number of decimals to input and round the quantity.
          format: int32
        unit_price:
          type:
          - number
          - 'null'
          description: The price per unit.
          format: decimal
        unit_price_decimals:
          type: integer
          description: The number of decimals to input and round the unit price.
          format: int32
        allow_changes_quantity_and_unit_price:
          type: boolean
          description: The user is allowed to edit the Billing Item's unit price after it is applied, such as on a Charge.
        trade_discount_percent:
          type: number
          description: Trade Discount Percentage for Charge and Line Item calculations.
          format: decimal
        trade_discount_amount:
          type: number
          description: Calculated Trade Discount Amount for Charge and Line Item calculations.
          format: decimal
          readOnly: true
        amount:
          type: number
          description: Amount calculated from other property values
          format: decimal
          readOnly: true
      additionalProperties: false
      description: The details for an item with variable quantity.
    PostStatus:
      title: PostStatus
      enum:
      - DoNotPost
      - NotYetPosted
      - Posted
      type: string
      description: Post status
    ReceivablesCodeTableEntry:
      required:
      - id
      - value
      type: object
      properties:
        id:
          type: string
          description: The ID of the code table entry.
        value:
          minLength: 1
          type: string
          description: The value of the code table entry.
      additionalProperties: false
      description: The request containing info for a code table entry.
    PrintStatus:
      title: PrintStatus
      enum:
      - NotYetPrinted
      - Printed
      - DoNotPrint
      - RePrint
      type: string
      description: Print status
  securitySchemes:
    Bb-Api-Subscription-Key:
      type: apiKey
      name: Bb-Api-Subscription-Key
      in: header
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.blackbaud.com/oauth/authorize
          tokenUrl: https://oauth2.sky.blackbaud.com/token
          scopes: {}