{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/oyster-hr/json-schema/oyster-hr-invoice-schema.json",
  "title": "invoice",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/oyster-hr-invoices-api-openapi.yml#/components/schemas/invoice",
  "type": "object",
  "required": [
    "id",
    "referenceCode",
    "type",
    "status",
    "payrollMonth",
    "payrollYear",
    "issueDate",
    "dueDate",
    "amount",
    "taxPercentage",
    "taxAmount",
    "files",
    "lineItems",
    "appliedCredit"
  ],
  "allOf": [
    {
      "$ref": "#/$defs/invoiceBase"
    }
  ],
  "anyOf": [
    {
      "$ref": "#/$defs/settlementInvoice"
    },
    {
      "$ref": "#/$defs/globalPayrollInvoice"
    },
    {
      "$ref": "#/$defs/contractorInvoice"
    },
    {
      "$ref": "#/$defs/invoiceBase"
    }
  ],
  "$defs": {
    "amount": {
      "type": "object",
      "properties": {
        "decimal": {
          "type": "string",
          "pattern": "^\\d+([.]\\d+)?$"
        },
        "currencyCode": {
          "type": "string",
          "minLength": 3,
          "maxLength": 3
        }
      },
      "required": [
        "decimal",
        "currencyCode"
      ]
    },
    "chargeCollectionItem": {
      "type": [
        "object",
        "null"
      ],
      "required": [
        "id",
        "status",
        "amount",
        "amountDue"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "NO_PAYMENT",
            "PENDING",
            "WAITING_FOR_WIRE_TRANSFER",
            "OVERDUE",
            "DIRECT_DEBIT_IN_PROGRESS",
            "DIRECT_DEBIT_FAILED",
            "CHARGED_BACK",
            "PAID",
            "PARTIALLY_PAID",
            "VOIDED"
          ]
        },
        "amount": {
          "$ref": "#/$defs/amount"
        },
        "amountDue": {
          "$ref": "#/$defs/amount"
        }
      }
    },
    "contractorInvoice": {
      "type": "object",
      "description": "Additional properties specific to contractor invoices.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "PAYG_CONTRACTOR",
            "EXPENSES",
            "CONTRACTOR_MONTHLY_PAYMENT",
            "CONTRACTOR_FEES",
            "MANUAL_INVOICE_BY_OYSTER"
          ]
        },
        "contractors": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "id",
              "name"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          }
        }
      },
      "required": [
        "contractors"
      ]
    },
    "globalPayrollInvoice": {
      "type": "object",
      "description": "Additional properties specific to global payroll invoices.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "GLOBAL_PAYROLL"
          ]
        },
        "payrollEntity": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "cutoffMonthDay": {
              "type": "number"
            }
          },
          "required": [
            "id",
            "name",
            "cutoffMonthDay"
          ]
        }
      },
      "required": [
        "payrollEntity"
      ]
    },
    "invoiceBase": {
      "type": "object",
      "description": "Base properties for all invoices.",
      "properties": {
        "id": {
          "type": "string"
        },
        "referenceCode": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "DEPOSIT",
            "PREFUNDING",
            "SETTLEMENT",
            "MANUAL",
            "CONTRACTORS_FEE",
            "MONTHLY_PAYMENT",
            "AD_HOC_PAYMENT",
            "EXPENSE_REIMBURSEMENT",
            "GLOBAL_PAYROLL",
            "SCALE",
            "SALARY_INSIGHTS",
            "TRUE_UPS",
            "OYSTER_FEES",
            "MANUAL_PREFUNDING",
            "MANUAL_SETTLEMENT",
            "MANUAL_OYSTER_FEES",
            "MANUAL_INVOICE_BY_OYSTER"
          ]
        },
        "status": {
          "type": "string"
        },
        "payrollMonth": {
          "type": [
            "string",
            "null"
          ]
        },
        "payrollYear": {
          "type": [
            "string",
            "null"
          ]
        },
        "issueDate": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        },
        "charge": {
          "$ref": "#/$defs/chargeCollectionItem"
        },
        "payout": {
          "$ref": "#/$defs/payoutCollectionItem"
        },
        "dueDate": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        },
        "amount": {
          "$ref": "#/$defs/amount"
        },
        "taxPercentage": {
          "type": [
            "string",
            "null"
          ]
        },
        "taxAmount": {
          "$ref": "#/$defs/amount"
        },
        "files": {
          "type": "object",
          "required": [
            "document",
            "breakdown"
          ],
          "properties": {
            "document": {
              "type": "object",
              "required": [
                "title",
                "url",
                "contentType"
              ],
              "properties": {
                "title": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "url": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "contentType": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            },
            "breakdown": {
              "type": "object",
              "properties": {
                "title": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "url": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "contentType": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          }
        },
        "lineItems": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "description",
              "quantity",
              "unitPrice",
              "amount"
            ],
            "properties": {
              "description": {
                "type": "string"
              },
              "quantity": {
                "type": "number"
              },
              "unitPrice": {
                "$ref": "#/$defs/amount"
              },
              "amount": {
                "$ref": "#/$defs/amount"
              }
            }
          }
        },
        "appliedCredit": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "referenceCode",
              "appliedAt",
              "amount"
            ],
            "properties": {
              "referenceCode": {
                "type": "string"
              },
              "appliedAt": {
                "type": "string",
                "format": "date-time"
              },
              "amount": {
                "$ref": "#/$defs/amount"
              }
            }
          }
        },
        "customer": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          },
          "description": "Contains the ID and name of the associated customer. This field is present if the invoice is linked to a customer account."
        }
      }
    },
    "payoutCollectionItem": {
      "type": [
        "object",
        "null"
      ],
      "required": [
        "id",
        "status",
        "amount"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "NOT_INITIATED",
            "INITIATED",
            "IN_PROGRESS",
            "PAID",
            "RETURNED",
            "NO_PAYMENT",
            "SENT"
          ]
        },
        "amount": {
          "$ref": "#/$defs/amount"
        }
      }
    },
    "settlementInvoice": {
      "type": "object",
      "description": "Additional properties specific to settlement invoices.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "SETTLEMENT"
          ]
        },
        "actualTotal": {
          "$ref": "#/$defs/amount"
        },
        "prefundingTotal": {
          "$ref": "#/$defs/amount"
        },
        "settlementTotal": {
          "$ref": "#/$defs/amount"
        }
      },
      "required": [
        "actualTotal",
        "prefundingTotal",
        "settlementTotal"
      ]
    }
  }
}