{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/asendia/main/json-schema/asendia-external-invoice-schema.json",
  "title": "ExternalInvoice",
  "x-generated": "2026-10-13",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/asendia-a1-externalinvoiceimport-openapi.yml#/components/schemas/ExternalInvoice",
  "required": [
    "customerAccountNumber",
    "invoiceCurrencyIso3",
    "invoiceDate",
    "invoiceLines",
    "invoiceNumber",
    "invoiceType"
  ],
  "type": "object",
  "properties": {
    "customerAccountNumber": {
      "type": "string",
      "description": "The Asendia customer account number of the customer that this invoice applies to."
    },
    "invoiceType": {
      "allOf": [
        {
          "$ref": "#/$defs/InvoiceType"
        }
      ],
      "description": "The type of invoice.  Possible values are \"Credit\" or \"Debit\"."
    },
    "invoiceNumber": {
      "type": "string",
      "description": "Unique invoice number.  This is the number that will appear on the customer invoice for reference."
    },
    "invoiceDate": {
      "type": "string",
      "description": "Date of the invoice. This is the date that will appear on the invoice.  Format should be standard date in the MM/dd/yyyy format.",
      "format": "date-time"
    },
    "invoiceCurrencyIso3": {
      "type": "string",
      "description": "Currency Iso3 of the invoice.  All charged will be assumed to be in this currency.  Invoice will also be generated in this currency."
    },
    "invoiceLines": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ExternalInvoiceLines"
      },
      "description": "Individual line items that will appear on the invoice.  Tax charges will be broken out as sub line items."
    },
    "attachments": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/ExternalAttachment"
      },
      "description": "File attachments that will be added to the invoice.  Attachments will also be delivered to the customer."
    }
  },
  "additionalProperties": false,
  "$defs": {
    "ExternalAttachment": {
      "required": [
        "fileContents",
        "name"
      ],
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Friendly name of the attachment.  Will display internally."
        },
        "fileContents": {
          "type": "string",
          "description": "Base 64 encoded contents of the file. If not base 64 encoded the contents will not display properly internally or when sending to customer."
        },
        "fileName": {
          "type": [
            "string",
            "null"
          ],
          "description": "Name of the file that will be attached to the file.  Name must include extension such as \".csv\" or \".pdf\" or it will not display properly internally or when sending to customer."
        }
      },
      "additionalProperties": false
    },
    "ExternalInvoiceLines": {
      "required": [
        "asendiaProductCode",
        "description",
        "jobNumber",
        "postageMaterialCode",
        "postageTotal"
      ],
      "type": "object",
      "properties": {
        "location": {
          "type": [
            "string",
            "null"
          ],
          "description": "Three character location code of the Asendia facility tied to the charges. Valid locations provided by Asendia."
        },
        "jobNumber": {
          "type": "string",
          "description": "Job number associated with the charges.  Charges will be grouped by job number on the invoice."
        },
        "description": {
          "type": "string",
          "description": "Description of charges that will appear on the invoice."
        },
        "province": {
          "type": [
            "string",
            "null"
          ],
          "description": "Province/State that the charges apply to."
        },
        "postageMaterialCode": {
          "type": "string",
          "description": "Material code associated with postage charges.  Must be a valid material code provided by Asendia"
        },
        "pieces": {
          "maximum": 2147483647,
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ],
          "description": "Number of pieces/parcels associated with the line item if applicable.",
          "format": "int32"
        },
        "weight": {
          "maximum": 79228162514264337593543950335,
          "minimum": 0,
          "type": [
            "number",
            "null"
          ],
          "description": "Weight of pieces/parcels associated with the line item if applicable.",
          "format": "double"
        },
        "weightCode": {
          "allOf": [
            {
              "$ref": "#/$defs/WeightType"
            }
          ],
          "description": "Weight code of line item weight. Possible values are \"Lbs\" and \"Kgs\". Defaulted to \"Lbs\" if not provided.",
          "nullable": true
        },
        "asendiaProductCode": {
          "type": "string",
          "description": "Asendia product code associated with the charges.  Must be a valid product code provided by Asendia."
        },
        "postageTotal": {
          "maximum": 79228162514264337593543950335,
          "minimum": 0,
          "type": "number",
          "description": "All charges associated with the line item excluding Canadian tax amounts. Canadian charges must be broken out separately.",
          "format": "double"
        },
        "taxMaterialCode": {
          "type": [
            "string",
            "null"
          ],
          "description": "Material code associated with Canadian tax charges.  Must be a valid material code provided by Asendia.\r\n**Conditionally required if tax amounts are provided**"
        },
        "gstTotal": {
          "maximum": 79228162514264337593543950335,
          "minimum": 0,
          "type": [
            "number",
            "null"
          ],
          "description": "GST Tax charge associated with the line. If not provided will be excluded from the invoice line on the invoice.",
          "format": "double"
        },
        "hstTotal": {
          "maximum": 79228162514264337593543950335,
          "minimum": 0,
          "type": [
            "number",
            "null"
          ],
          "description": "HST Tax charge associated with the line. If not provided will be excluded from the invoice line on the invoice.",
          "format": "double"
        },
        "pstTotal": {
          "maximum": 79228162514264337593543950335,
          "minimum": 0,
          "type": [
            "number",
            "null"
          ],
          "description": "PST Tax charge associated with the line. If not provided will be excluded from the invoice line on the invoice.",
          "format": "double"
        },
        "qstTotal": {
          "maximum": 79228162514264337593543950335,
          "minimum": 0,
          "type": [
            "number",
            "null"
          ],
          "description": "QST Tax charge associated with the line. If not provided will be excluded from the invoice line on the invoice.",
          "format": "double"
        }
      },
      "additionalProperties": false
    },
    "InvoiceType": {
      "enum": [
        "Credit",
        "Debit"
      ],
      "type": "string"
    },
    "WeightType": {
      "enum": [
        "Lbs",
        "Kgs"
      ],
      "type": "string"
    }
  }
}