settlement

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/spendesk/json-schema/spendesk-settlement-schema.json",
  "title": "settlement",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/spendesk-settlements-and-wallet-api-openapi.yml#/components/schemas/settlement",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "The ID of the settlement."
    },
    "version": {
      "type": "number",
      "description": "Version of the settlement."
    },
    "type": {
      "type": "string",
      "enum": [
        "payment",
        "refund",
        "advance",
        "cashReturn",
        "chargeback",
        "reimbursement"
      ],
      "description": "Indicates the type of the settlement. \n\nType | Description |\n---------|----------|\n `payment` | A payment to a supplier | \n `reimbursement` | A payment to an employee | \n `refund` | A refund |\n  `advance` | A cash advance |\n  `cashReturn` | A cash return |\n  `chargeback` | A card disputes/chargeback |\""
    },
    "medium": {
      "type": "string",
      "enum": [
        "card",
        "wiretransfer"
      ],
      "description": "The medium as through which this settlement is processed."
    },
    "paidFrom": {
      "type": "string",
      "enum": [
        "spendeskAccount",
        "externalAccount"
      ],
      "description": "The bank account the wire transfer is emitted from (Spendesk or external). For card payments the value is always `spendeskAccount`."
    },
    "transactionDescription": {
      "type": "string",
      "description": "Description of the transaction."
    },
    "clearedAt": {
      "allOf": [
        {
          "$ref": "#/$defs/dateTime"
        }
      ],
      "description": "Time and date that the transaction cleared. In the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format."
    },
    "amount": {
      "allOf": [
        {
          "$ref": "#/$defs/priceAmount"
        }
      ],
      "description": "If the payment was made in a foreign currency, this amount is in the foreign currency. Expressed in smallest units of the currency (e.g. cents for EUR and USD, but yen for JPY). Contains negative values for refunds."
    },
    "currency": {
      "$ref": "#/$defs/currency"
    },
    "billingAmount": {
      "allOf": [
        {
          "$ref": "#/$defs/priceAmount"
        }
      ],
      "description": "Amount is in the account's currency. Expressed in smallest units of the currency (e.g. cents for EUR and USD, but yen for JPY)."
    },
    "billingCurrency": {
      "$ref": "#/$defs/currency"
    },
    "billingExchangeRate": {
      "type": "number",
      "description": "If the payment was made in a foreign currency, this is the exchange rate between the two currencies at the time of the payment."
    },
    "state": {
      "type": "string",
      "enum": [
        "created",
        "exported",
        "failedToExport"
      ],
      "description": "Indicates the current state of the settlement: created, exported, or failed to export. \n\nType | Description |\n---------|----------|\n `created` | Created but not exported | \n `exported` | Exported | \n `failedToExport` | Tried to export but failed |\""
    },
    "exportedAt": {
      "oneOf": [
        {
          "$ref": "#/$defs/dateTime"
        },
        {
          "type": [
            "object",
            "null"
          ]
        }
      ],
      "description": "The date and time the settlement was exported at."
    },
    "statusUpdatedAt": {
      "oneOf": [
        {
          "$ref": "#/$defs/dateTime"
        },
        {
          "type": [
            "object",
            "null"
          ]
        }
      ],
      "description": "The date and time the settlement status was updated."
    },
    "allocations": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "amount": {
            "$ref": "#/$defs/priceAmount"
          },
          "currency": {
            "$ref": "#/$defs/currency"
          },
          "payableId": {
            "allOf": [
              {
                "$ref": "#/$defs/id"
              }
            ],
            "description": "The ID of the associated payable."
          }
        },
        "required": [
          "amount",
          "currency",
          "payableId"
        ]
      },
      "description": "Allocations this settlement is part of, with at most one entry per payableId: if a settlement has several allocations to the same payable only one is returned, so allocation amounts may not add up to the settlement amount."
    }
  },
  "required": [
    "id",
    "version",
    "type",
    "medium",
    "paidFrom",
    "transactionDescription",
    "clearedAt",
    "amount",
    "currency",
    "billingAmount",
    "billingCurrency",
    "billingExchangeRate",
    "state",
    "exportedAt",
    "statusUpdatedAt",
    "allocations"
  ],
  "$defs": {
    "currency": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "description": "If the payment was made in a foreign currency, this amount will be the one in the payment currency. Three-letter [ISO currency codes](https://www.iso.org/iso-4217-currency-codes.html).",
      "title": "currency"
    },
    "dateTime": {
      "type": "string",
      "format": "date-time",
      "description": "String containing a UTC datetime expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format like `2023-05-12T14:06:40Z`.",
      "title": "dateTime"
    },
    "priceAmount": {
      "type": "number",
      "description": "If the payment was made in a foreign currency, this amount will be the one in the payment currency.\nCan contain a negative value in case of refunds.\nExpressed in smallest units of the currency (e.g. cents for EUR and USD, but yen for JPY).",
      "title": "priceAmount"
    }
  }
}