Order Entity

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/billieio/main/json-schema/billieio-order-schema.json",
  "title": "Order Entity",
  "x-generated": "2026-10-14",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/billieio-billie-direct-api-openapi.yml#/components/schemas/Order",
  "properties": {
    "external_code": {
      "type": [
        "string",
        "null"
      ]
    },
    "uuid": {
      "$ref": "#/$defs/UUID"
    },
    "state": {
      "$ref": "#/$defs/OrderStateV2"
    },
    "decline_reason": {
      "$ref": "#/$defs/OrderDeclineReason"
    },
    "amount": {
      "$ref": "#/$defs/TaxedMoney"
    },
    "unshipped_amount": {
      "$ref": "#/$defs/TaxedMoney"
    },
    "duration": {
      "$ref": "#/$defs/OrderDuration"
    },
    "created_at": {
      "$ref": "#/$defs/DateTime"
    },
    "delivery_address": {
      "$ref": "#/$defs/Address"
    },
    "debtor": {
      "$ref": "#/$defs/Debtor"
    },
    "invoices": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/OrderInvoiceResponse"
      },
      "nullable": false
    },
    "selected_payment_method": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "bank_transfer",
        "direct_debit"
      ]
    },
    "payment_methods": {
      "$ref": "#/$defs/PaymentMethodCollection"
    }
  },
  "type": "object",
  "$defs": {
    "Address": {
      "title": "Address data are all required except house number.",
      "required": [
        "street",
        "postal_code",
        "city",
        "country"
      ],
      "properties": {
        "house_number": {
          "$ref": "#/$defs/TinyText"
        },
        "street": {
          "$ref": "#/$defs/TinyText"
        },
        "postal_code": {
          "$ref": "#/$defs/TinyText"
        },
        "city": {
          "$ref": "#/$defs/TinyText"
        },
        "country": {
          "$ref": "#/$defs/CountryCode"
        }
      },
      "type": "object"
    },
    "BankAccount": {
      "title": "Simple representation of a bank account",
      "properties": {
        "iban": {
          "$ref": "#/$defs/TinyText"
        },
        "bic": {
          "$ref": "#/$defs/TinyText"
        }
      },
      "type": "object"
    },
    "CountryCode": {
      "title": "Country Code",
      "description": "ISO 3166-1 alpha-2 country code (two letters: DE, AT, etc.). See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2",
      "type": "string",
      "maxLength": 2,
      "minLength": 2
    },
    "DateTime": {
      "title": "Date-Time",
      "type": "string",
      "format": "date-time"
    },
    "Debtor": {
      "title": "Order Debtor",
      "properties": {
        "name": {
          "type": "string"
        },
        "company_address": {
          "$ref": "#/$defs/Address"
        },
        "billing_address": {
          "$ref": "#/$defs/Address"
        },
        "bank_account": {
          "$ref": "#/$defs/BankAccount"
        },
        "external_data": {
          "$ref": "#/$defs/DebtorExternalData"
        }
      },
      "type": "object"
    },
    "DebtorExternalData": {
      "title": "Debtor External Data",
      "properties": {
        "merchant_customer_id": {
          "$ref": "#/$defs/TinyText"
        },
        "name": {
          "$ref": "#/$defs/TinyText"
        },
        "industry_sector": {
          "type": [
            "string",
            "null"
          ]
        },
        "address": {
          "$ref": "#/$defs/Address"
        }
      },
      "type": "object"
    },
    "OrderDeclineReason": {
      "title": "Order Decline Reason",
      "type": "string",
      "enum": [
        "risk_policy",
        "risk_scoring_failed",
        "debtor_not_identified",
        "debtor_address",
        "risk_scoring_failed",
        "debtor_limit_exceeded"
      ]
    },
    "OrderDuration": {
      "title": "Order Duration",
      "type": "integer",
      "maximum": 120,
      "minimum": 1
    },
    "OrderInvoiceResponse": {
      "title": "Order Entity",
      "properties": {
        "uuid": {
          "$ref": "#/$defs/UUID"
        },
        "invoice_number": {
          "type": [
            "string",
            "null"
          ]
        },
        "state": {
          "type": [
            "string",
            "null"
          ]
        },
        "payout_amount": {
          "type": [
            "number",
            "null"
          ],
          "format": "float"
        },
        "amount": {
          "type": "number",
          "format": "float"
        },
        "amount_net": {
          "type": "number",
          "format": "float"
        },
        "amount_tax": {
          "type": "number",
          "format": "float"
        },
        "outstanding_amount": {
          "type": [
            "number",
            "null"
          ],
          "format": "float"
        },
        "pending_merchant_payment_amount": {
          "type": [
            "number",
            "null"
          ],
          "format": "float"
        },
        "pending_cancellation_amount": {
          "type": [
            "number",
            "null"
          ],
          "format": "float"
        },
        "fee_amount": {
          "type": [
            "number",
            "null"
          ],
          "format": "float"
        },
        "fee_rate": {
          "type": [
            "number",
            "null"
          ],
          "format": "float"
        },
        "due_date": {
          "type": "string",
          "format": "date"
        },
        "created_at": {
          "type": "string",
          "format": "date"
        }
      },
      "type": "object"
    },
    "OrderStateV2": {
      "title": "Order State",
      "type": "string",
      "enum": [
        "pre_waiting",
        "authorized",
        "waiting",
        "created",
        "declined",
        "shipped",
        "partially_shipped",
        "complete",
        "canceled"
      ]
    },
    "PaymentMethod": {
      "title": "Payment Method",
      "properties": {
        "type": {
          "$ref": "#/$defs/PaymentMethodType"
        },
        "data": {
          "description": "Payment method details",
          "properties": {
            "iban": {
              "$ref": "#/$defs/TinyText"
            },
            "bic": {
              "$ref": "#/$defs/TinyText"
            },
            "bank_name": {
              "description": "Name of the Bank entity",
              "type": [
                "string",
                "null"
              ]
            },
            "bank_giro": {
              "description": "Bank giro number (Sweden only)",
              "type": [
                "string",
                "null"
              ]
            },
            "sort_code": {
              "description": "Bank sort code (GB only)",
              "type": [
                "string",
                "null"
              ]
            },
            "account_number": {
              "description": "Bank account number (GB, NL and NO)",
              "type": [
                "string",
                "null"
              ]
            },
            "bank_account_owner": {
              "description": "Bank account owner entity",
              "type": "string",
              "nullable": false
            },
            "mandate_reference": {
              "description": "Direct Debit SEPA Mandate Reference (for Direct Debit only)",
              "type": [
                "string",
                "null"
              ]
            },
            "mandate_execution_date": {
              "$ref": "#/$defs/DateTime"
            },
            "creditor_identification": {
              "description": "Creditor Identification Code (for Direct Debit only)",
              "type": [
                "string",
                "null"
              ]
            }
          },
          "type": "object"
        }
      },
      "type": "object"
    },
    "PaymentMethodCollection": {
      "title": "Eligible Payment Methods",
      "type": "array",
      "items": {
        "$ref": "#/$defs/PaymentMethod"
      }
    },
    "PaymentMethodType": {
      "title": "Payment Method Type",
      "type": "string",
      "enum": [
        "bank_transfer",
        "direct_debit"
      ]
    },
    "TaxedMoney": {
      "title": "Amount with split values for net, gross and tax.",
      "required": [
        "net",
        "gross",
        "tax"
      ],
      "properties": {
        "gross": {
          "description": "Value greater than 0, with max. 2 decimals. It should equal to net + tax.",
          "type": "number",
          "format": "float",
          "minimum": 1
        },
        "net": {
          "description": "Value greater than 0, with max. 2 decimals.",
          "type": "number",
          "format": "float",
          "minimum": 1
        },
        "tax": {
          "description": "Value greater than or equal to 0, with max. 2 decimals.",
          "type": "number",
          "format": "float",
          "minimum": 0
        }
      },
      "type": "object"
    },
    "TinyText": {
      "title": "string",
      "type": "string",
      "maxLength": 255
    },
    "UUID": {
      "type": "string",
      "format": "uuid",
      "maxLength": 36,
      "minLength": 36
    }
  }
}