Transaction

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/thisisbud/main/json-schema/thisisbud-schemas-transaction-schema.json",
  "title": "Transaction",
  "description": "A financial transaction",
  "x-generated": "2026-10-21",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/thisisbud-openapi-us-openapi.yml#/components/schemas/schemas-Transaction",
  "type": "object",
  "required": [
    "transaction_id",
    "account_id",
    "description",
    "amount",
    "credit_debit_indicator",
    "status",
    "date_time",
    "suggested_description"
  ],
  "properties": {
    "transaction_id": {
      "type": "string",
      "description": "Unique identifier for the transaction. May be mutable depending on original ingestion source."
    },
    "account_id": {
      "type": "string",
      "description": "Identifier for the account associated with the transaction."
    },
    "provider": {
      "type": "string",
      "description": "Name of the transaction source provider. Optional as it may not have been supplied when using first party data."
    },
    "description": {
      "type": "string",
      "description": "Description of the transaction."
    },
    "credit_debit_indicator": {
      "type": "string",
      "description": "Credit/Debit Indicator",
      "enum": [
        "credit",
        "debit"
      ]
    },
    "status": {
      "type": "string",
      "description": "Status of the transaction. Defaults to booked.\n\nNote: declined transactions are only available for transactions ingested by First Party Ingestion endpoints.\n",
      "enum": [
        "booked",
        "pending",
        "declined"
      ]
    },
    "suggested_description": {
      "type": "string",
      "description": "The description Bud suggests client apps show for a given transaction."
    },
    "suggested_logo": {
      "type": "string",
      "description": "The logo Bud suggests client apps show for a given transaction."
    },
    "transaction_type": {
      "$ref": "#/$defs/BudTransactionType"
    },
    "amount": {
      "$ref": "#/$defs/BudAmount"
    },
    "date_time": {
      "type": "string",
      "description": "Date that the transaction occured compliant with RFC3339."
    },
    "posted_date_time": {
      "deprecated": true,
      "type": "string",
      "description": "Date the assets involved in the transaction transferred compliant with RFC3339. For credits this is the date that the asset becomes available, for debits this is the date that the asset ceased to be available"
    },
    "value_date_time": {
      "type": "string",
      "description": "Date the assets involved in the transaction transferred compliant with RFC3339. For credits this is the date that the asset becomes available, for debits this is the date that the asset ceased to be available"
    },
    "enrichments": {
      "$ref": "#/$defs/schemas-Enrichments"
    },
    "merchant_category_code": {
      "type": "string",
      "description": "Merchant category code conforming to ISO 18245, related to the type of services or goods the merchant provides for the transaction."
    },
    "running_balance": {
      "description": "The running balance for the account that the transaction takes place against",
      "title": "Standard Bud Amount",
      "type": "object",
      "required": [
        "value",
        "currency"
      ],
      "properties": {
        "value": {
          "$ref": "#/$defs/BudMonetaryValue"
        },
        "currency": {
          "$ref": "#/$defs/BudCurrency"
        }
      }
    },
    "running_balance_credit_debit_indicator": {
      "type": "string",
      "description": "Credit/Debit Indicator for the running balance field",
      "enum": [
        "credit",
        "debit"
      ]
    },
    "counterparty": {
      "type": "object",
      "description": "An object containing details of the counterparty in this transaction",
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the counterparty involved in this transaction."
        },
        "identifier": {
          "type": "string",
          "description": "An identifier for the account of the other party"
        }
      }
    },
    "tags": {
      "type": "array",
      "description": "A list of potential tags associated with the transaction after contextual enrichment, which can be used for filtering.\n\nRegion and client specific.\n\n| Value                   | Description                                               |\n|:------------------------|:----------------------------------------------------------|\n| `benefit`               | A government/non-profit benefit transaction               |\n| `debt-collection`       | A transaction associated with a known debt-collector      |\n| `loan`                  | A transaction associated with a loan                      |\n| `hcst`                  | A transaction associated with a high cost short term loan |\n| `income`                | A transaction associated with income                      |\n| `pending`               | A transaction which has not been booked                   |\n| `regular-transaction`   | A transaction predicted to occur with a regular frequency |\n| `subscription`          | A transaction associated with a subscription service      |\n| `online`                | A transaction associated with an online merchant          |\n| `bill`                  | A transaction associated with an bill payment             |\n| `internal-transfer`     | A transaction between a customers accounts                |\n",
      "items": {
        "type": "string"
      }
    },
    "client_attributes": {
      "$ref": "#/$defs/schemas-ClientAttributes"
    },
    "labels": {
      "type": "array",
      "description": "Customer-defined labels currently attached to this transaction. Managed via the __Manage Transaction Labels__ endpoints, and attached/removed via the __Assign Transaction Label__ and __Unassign Transaction Label__ endpoints.\n",
      "items": {
        "$ref": "#/$defs/TransactionLabel"
      }
    }
  },
  "$defs": {
    "BudAmount": {
      "title": "Standard Bud Amount",
      "type": "object",
      "description": "The monetary amount.",
      "required": [
        "value",
        "currency"
      ],
      "properties": {
        "value": {
          "$ref": "#/$defs/BudMonetaryValue"
        },
        "currency": {
          "$ref": "#/$defs/BudCurrency"
        }
      }
    },
    "BudCurrency": {
      "title": "Currency",
      "description": "The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) of the monetary amount.\n\nExample: `GBP`\n",
      "type": "string"
    },
    "BudMonetaryValue": {
      "title": "Monetary Value",
      "description": "The value of the monetary amount. The value is formatted with the number of decimal places for the respective currency. \n\nExample: `10.98`\n",
      "type": "string"
    },
    "BudTransactionType": {
      "title": "transaction_type",
      "type": "object",
      "description": "The code and a description of the transaction type. Providing these fields may help improve enrichment accuracy.\n",
      "properties": {
        "bud_code": {
          "type": "string",
          "description": "The code representing the type of the given transaction. This typically comes in the form of a proprietary code respective to the __provider__.\n\nCurrent list of valid accepted codes:\n\n| Code  | Meaning\n|:------|:-------------------------------------------------------------------|\n| DEB   | [Debit / Credit] Card                                              |\n| CSQ   | Cash / Cheque(s)                                                   |\n| CHG   | Charge                                                             |\n| COR   | Correction                                                         |\n| CPT   | Cashpoint / ATM                                                    |\n| INT   | Interest                                                           |\n| OTH   | Other                                                              |\n| BAT   | Bank Transfer (e.g. FP/MP/IB/BACS/CHAPS/SWIFT)                     |\n| DD    | Direct Debit                                                       |\n| SO    | Standing Order                                                     |\n"
        },
        "description": {
          "type": "string",
          "description": "A human-readable description of the given __bud_code__.\nexample: `Contactless POS`\n"
        }
      }
    },
    "Category": {
      "title": "Category",
      "type": "object",
      "description": "Category associated with a Transaction",
      "required": [
        "slug",
        "confidence"
      ],
      "properties": {
        "slug": {
          "type": "string",
          "description": "Unique human readable identifier of the category. Not subject to version control."
        },
        "confidence": {
          "type": "string",
          "description": "Degree of belief of correct assignment, expressed as a probability."
        }
      }
    },
    "Token": {
      "title": "Token",
      "type": "object",
      "description": "The token item.",
      "required": [
        "value",
        "confidence"
      ],
      "properties": {
        "value": {
          "type": "string"
        },
        "confidence": {
          "type": "string",
          "description": "Degree of belief of correct assignment, expressed as a probability."
        }
      }
    },
    "TransactionLabel": {
      "title": "Transaction Label",
      "type": "object",
      "description": "A customer-defined label attached to a transaction.",
      "required": [
        "id",
        "name"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Unique identifier of the label."
        },
        "name": {
          "type": "string",
          "description": "Display name of the label."
        }
      }
    },
    "schemas-Categories": {
      "title": "Categories",
      "type": "object",
      "description": "Categories enrichment associated with a Transaction, as generated by Bud's artificial intelligence models.  Currently two levels of category are supported, with `l1` being a coarse-grained category level and `l2` being more refined.\n",
      "properties": {
        "l1": {
          "$ref": "#/$defs/Category",
          "description": "Level 1 Category"
        },
        "l2": {
          "$ref": "#/$defs/Category",
          "description": "Level 2 Category"
        }
      }
    },
    "schemas-ClientAttributes": {
      "title": "Client Attributes",
      "type": "object",
      "description": "An optional map of key-value string pairs that allows clients to attach arbitrary metadata to the transaction.\nThis field can be used to store any relevant information specific to the client's needs, such as:\nThese attributes can be added using the [Ingest Transactions](#operation/v2_ingest_transactions_post) endpoint.\n",
      "properties": {
        "key": {
          "type": "string",
          "description": "An arbitrary key-value pair for the client attribute."
        }
      }
    },
    "schemas-Corrections": {
      "title": "Corrections",
      "type": "object",
      "description": "Identifiers for correction rules that were applied to this transaction during enrichment. Returned only when correction-rule surfacing is enabled for your organisation.\n",
      "properties": {
        "applied_rule_ids": {
          "type": "array",
          "description": "IDs of correction rules that were applied to this transaction.",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "schemas-Enrichments": {
      "title": "Enrichments",
      "type": "object",
      "description": "Contextual enrichments associated with a Transaction",
      "properties": {
        "categories": {
          "$ref": "#/$defs/schemas-Categories"
        },
        "merchant": {
          "$ref": "#/$defs/schemas-Merchant"
        },
        "processor": {
          "$ref": "#/$defs/schemas-Processor"
        },
        "regularity": {
          "$ref": "#/$defs/schemas-Regularity"
        },
        "corrections": {
          "$ref": "#/$defs/schemas-Corrections"
        },
        "location": {
          "$ref": "#/$defs/schemas-Location"
        },
        "transaction_types": {
          "type": "array",
          "description": "Transaction types associated with the transaction",
          "items": {
            "type": "string"
          }
        },
        "names": {
          "type": "array",
          "description": "Names that were detected in the transaction description",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "schemas-Location": {
      "title": "Location",
      "type": "object",
      "description": "Location enrichment associated with a Transaction",
      "properties": {
        "address": {
          "type": "object",
          "description": "The address where the transaction occurred. The level of detail depends on the resolution with which we are able to detect the transaction location.",
          "properties": {
            "address_lines": {
              "type": "array",
              "description": "A list of all the address lines detected for the transaction. This could be anything from a full street address down to just the region.",
              "items": {
                "type": "string"
              }
            },
            "street_address": {
              "type": "string",
              "description": "The street address where the transaction occurred. Typically this will consist of the street number and street name with an optional suite."
            },
            "city": {
              "type": "string",
              "description": "The city or town where the transaction occurred."
            },
            "region": {
              "type": "string",
              "description": "The county or region where the transaction occurred."
            },
            "postal_code": {
              "type": "string",
              "description": "The postcode where the transaction occurred."
            },
            "country": {
              "type": "string",
              "description": "The ISO 3166-1 alpha-2 country code representing the country where the transaction occurred.\n\nIf a location could not be determined, but a `country_code` was supplied in the ingestion request; that value will be reflected here.\n"
            }
          }
        },
        "geolocation": {
          "type": "object",
          "description": "The geolocation where the transaction occurred. This is only available if we are able to narrow down the transaction location to an exact match.",
          "properties": {
            "latitude": {
              "type": "number",
              "format": "double",
              "description": "The latitudinal position where the transaction occurred."
            },
            "longitude": {
              "type": "number",
              "format": "double",
              "description": "The longitudinal position where the transaction occurred."
            }
          }
        },
        "tokens": {
          "type": "array",
          "description": "A list of substrings from the description identified as being relevant to the transaction location.",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "schemas-Merchant": {
      "title": "Merchant",
      "type": "object",
      "description": "Merchant enrichment associated with a Transaction, as generated using a combination of Bud's artificial  intelligence models and database of known merchants.\n",
      "properties": {
        "id": {
          "type": "string",
          "description": "UUID corresponding to the merchant, if available. Subject to version control."
        },
        "slug": {
          "type": "string",
          "description": "Unique human readable identifier of the merchant. Not subject to version control."
        },
        "display_name": {
          "type": "string",
          "description": "UI friendly display name for the merchant."
        },
        "logo": {
          "type": "string",
          "description": "URL supplying merchant logo, if available."
        },
        "tokens": {
          "type": "array",
          "description": "A list of tokens calculated from the transaction model, used to identify the Merchant.  This list is often present even if the merchant details (id, slug, disply_name, logo) are not returned.\n",
          "items": {
            "$ref": "#/$defs/Token"
          }
        },
        "website": {
          "type": "string",
          "description": "URL supplying merchant website, if available."
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "A list of tags describing the merchant"
        }
      }
    },
    "schemas-Processor": {
      "title": "Processor",
      "type": "object",
      "description": "Processor enrichment associated with a Transaction, as generated using a combination of Bud's artificial  intelligence models and database of known payment processors.\n",
      "properties": {
        "id": {
          "type": "string",
          "description": "UUID corresponding to the processor, if available. Subject to version control."
        },
        "slug": {
          "type": "string",
          "description": "Unique human readable identifier of the processor. Not subject to version control."
        },
        "display_name": {
          "type": "string",
          "description": "UI friendly display name for the processor."
        },
        "logo": {
          "type": "string",
          "description": "URL supplying processor logo, if available."
        },
        "tokens": {
          "type": "array",
          "description": "A list of tokens calculated from the transaction model, used to identify the Merchant.  This list is often present even if the merchant details (id, slug, disply_name, logo) are not returned.\n",
          "items": {
            "$ref": "#/$defs/Token"
          }
        },
        "website": {
          "type": "string",
          "description": "URL supplying merchant website, if available."
        }
      }
    },
    "schemas-Regularity": {
      "title": "Regularity",
      "type": "object",
      "description": "Regularity enrichment associated with a Transaction, as generated by Bud's artificial intelligence models.  Transactions that are similar and have a known frequency will all have the same regularity enrichment.\n",
      "properties": {
        "frequency": {
          "type": "string",
          "description": "Detected frequency of the Transaction.",
          "enum": [
            "unknown",
            "daily",
            "weekly",
            "biweekly",
            "monthly",
            "quarterly"
          ]
        },
        "predicted_date_times": {
          "type": "array",
          "description": "Expected date times for the Transaction to repeat.",
          "items": {
            "type": "string"
          }
        },
        "group_label": {
          "type": "string",
          "description": "Unique label applied to multiple transactions in the same group."
        }
      }
    }
  }
}