{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/qualpay/json-schema/qualpay-create-invoice-request-schema.json",
  "title": "CreateInvoiceRequest",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/qualpay-invoicing-api-openapi.yml#/components/schemas/CreateInvoiceRequest",
  "required": [
    "customer_id",
    "invoice_number"
  ],
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong>The customer ID associated with this invoice. If the customer does not exist in the system, set the `save_customer` flag to `true`, and a new customer record will be created. "
    },
    "send_invoice": {
      "type": "boolean",
      "description": "<strong>Description: </strong>If set to `true`, the system will send the invoice to the customer as specified in the request body.<br><strong>Default: </strong>false"
    },
    "create_invoice_link": {
      "type": "boolean",
      "description": "<strong>Description: </strong>If set to `true`, this invoice request will return an `invoice_link` and will not send an invoice to the customer, even if `send_invoice` is `true`.<br><strong>Default: </strong>false"
    },
    "invoice_number": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 25 AN<br><strong>Description: </strong>The invoice number (also referred to as the purchase identifier) generated by the merchant. "
    },
    "from_contact": {
      "description": "The contact sending the invoice.",
      "allOf": [
        {
          "$ref": "#/$defs/Contact"
        }
      ]
    },
    "billing_contact": {
      "description": "The contact to send the bill to.",
      "allOf": [
        {
          "$ref": "#/$defs/Contact"
        }
      ]
    },
    "profile_id": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 20 AN<br><strong>Description: </strong>The unique Payment Gateway profile ID to be used when making an invoice payment. If `profile_id` is not provided, the system uses the currency specified in `tran_currency`. If both `profile_id` and `tran_currency` are sent, the system uses the currency and settings associated with the `profile_id`."
    },
    "tran_currency": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 3 AN<br><strong>Description: </strong>The ISO numeric currency code. This must be a currency code associated with one of your payment profiles; contact Qualpay to add currencies. Refer to <a href=\"/docs/references#currency-codes\" target=\"_blank\">Currency Codes</a> for a list of currency codes. If both `profile_id` and `tran_currency` fields are provided, the currency associated with the `profile_id` is used and `tran_currency` is updated to match `profile_id`’s currency.<br><strong>Default: </strong>840"
    },
    "footer_note": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 750 AN<br><strong>Description: </strong>The note displayed in the footer of the invoice.  By default, the system uses the footer note from the invoice settings page in the Merchant Manager portal."
    },
    "payment_terms_note": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 500 AN<br><strong>Description: </strong>The invoice payment terms description. By default, the system uses the payment terms note information from the invoice settings page in the Merchant Manager portal."
    },
    "checkout_settings": {
      "$ref": "#/$defs/CheckoutSettings"
    },
    "sales_tax": {
      "$ref": "#/$defs/SalesTax"
    },
    "payment_terms": {
      "$ref": "#/$defs/PaymentTerm"
    },
    "date_invoice": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 10 AN,in YYYY-MM-DD format<br><strong>Description: </strong>The invoice date."
    },
    "line_items": {
      "type": "array",
      "description": "The invoice line item details. ",
      "items": {
        "$ref": "#/$defs/LineItem"
      }
    },
    "save_customer": {
      "type": "boolean",
      "description": "<strong>Description: </strong>Set this value to `true` to create a customer profile. When this is set to `true`, `customer_id` and `billing_contact` fields are required.<br><strong>Default: </strong>false"
    },
    "auto_generate_invoice_number": {
      "type": "boolean",
      "description": "<strong>Description: </strong>If set to `true`, the system will automatically generate an invoice number.<br><strong>Default: </strong>false"
    }
  },
  "$defs": {
    "CheckoutSettings": {
      "type": "object",
      "properties": {
        "allow_partial_payments": {
          "type": "boolean",
          "description": "<strong>Description: </strong>If set to `true`, the customer can edit the transaction amount when making a payment on the invoice’s Checkout page. This allows the customer to make partial payments."
        },
        "email_receipt": {
          "type": "boolean",
          "description": "<strong>Description: </strong>If set to `true` and the customer email address is provided, we generate and send a receipt to the customer once a payment is made on the invoice's Checkout page. "
        },
        "allow_ach_payment": {
          "type": "boolean",
          "description": "<strong>Description: </strong>If set to `true`, the Checkout page will present ACH as a possible payment mode. Applicable only if your merchant account is configured to take ACH payments. <br><strong>Default: </strong>false"
        },
        "show_saved_payment_methods": {
          "type": "boolean",
          "description": "<strong>Description: </strong> If `show_saved_payment_methods` is set to `true`, the Checkout page will display the stored payments methods.<br><strong>Default: </strong>false"
        }
      },
      "x-display-fields": [
        "allow_partial_payments",
        "email_receipt",
        "allow_ach_payment"
      ]
    },
    "Contact": {
      "required": [
        "email_address"
      ],
      "type": "object",
      "properties": {
        "first_name": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong>First name of the contact.<br><strong>Conditional Requirement: </strong>Required for the `billing_contact` object."
        },
        "last_name": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong>Last name of the contact.<br><strong>Conditional Requirement: </strong>Required for the `billing_contact` object."
        },
        "firm_name": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 64 AN<br><strong>Description: </strong>Contact business name, if applicable.<br><strong>Conditional Requirement: </strong>Required for the `from_contact` object."
        },
        "address1": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 128 AN<br><strong>Description: </strong>Contact address line 1."
        },
        "address2": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 128 AN<br><strong>Description: </strong>Contact address line 2."
        },
        "city": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 64 AN<br><strong>Description: </strong>Contact city."
        },
        "state": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 64 AN<br><strong>Description: </strong>Contact state."
        },
        "zip": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 10 AN<br><strong>Description: </strong>Contact zip code."
        },
        "zip4": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 4 N<br><strong>Description: </strong>Contact zip+4 code, if applicable."
        },
        "phone": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 32 AN<br><strong>Description: </strong>Contact phone number.<br><strong>Conditional Requirement: </strong>Required for the `from_contact` object."
        },
        "email_address": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 64 AN<br><strong>Description: </strong>Contact email address."
        },
        "country_code": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 3 AN<br><strong>Description: </strong>ISO numeric country code for the contact. Refer to <a href=\"/docs/references\" target=\"_blank\">Country Codes</a> for a list of country codes.<br>"
        },
        "country": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 128 AN<br><strong>Description: </strong>Country name."
        }
      },
      "x-display-fields": [
        "first_name",
        "last_name",
        "firm_name",
        "address1",
        "address2",
        "city",
        "state",
        "zip",
        "zip4",
        "phone",
        "email_address",
        "country_code",
        "country"
      ]
    },
    "LineItem": {
      "required": [
        "description",
        "quantity",
        "unit_cost"
      ],
      "type": "object",
      "properties": {
        "quantity": {
          "type": "integer",
          "description": "<strong>Format: </strong>Variable length, up to 3 N<br><strong>Description: </strong>The count of items.",
          "format": "int32"
        },
        "description": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length AN<br><strong>Description: </strong>Description of the item."
        },
        "unit_cost": {
          "type": "number",
          "description": "<strong>Format: </strong>Variable length, up to 8,2 AN<br><strong>Description: </strong>The cost per unit, up to 2 decimal places.",
          "format": "double"
        }
      },
      "x-display-fields": [
        "description",
        "quantity",
        "unit_cost"
      ]
    },
    "PaymentTerm": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "<strong>Format: </strong>Fixed length, 4 A<br><strong>Description: </strong>The payment term type, which determines how the `invoice_due_date` is calculated. By default, this field is set to `DAYS`. Possible values: <ul> <li>`DATE` - The `value` field in this object contains the date that payment is due.</li> <li>`DAYS`- The `value` field in this object contains the number of days from the invoice date (`invoice_date`) that payment is due.</li></ul>",
          "enum": [
            "DAYS",
            "DATE"
          ]
        },
        "value": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 25 AN<br><strong>Description: </strong>The payment term. The `invoice_due_date` will be automatically updated based on this value. If the `type` field in this object is `DATE`, this field should contain the `invoice_due_date` in 'YYYY-MM-DD' format. If `type` is `DAYS`, this field should contain the number of days from the invoice date (`date_invoice`) that payment is due."
        }
      }
    },
    "SalesTax": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "<strong>Format: </strong>Variable length, up to 10 AN<br><strong>Description: </strong>The sales tax type. Possible values: <ul><li>`RATE` - The `value` field in this object contains the tax rate. The system will automatically calculate the tax amount based on that rate. </li><li>`AMOUNT` - The `value` field in this object contains the tax amount.</li></ul>",
          "enum": [
            "RATE",
            "AMOUNT"
          ]
        },
        "value": {
          "type": "number",
          "description": "<strong>Format: </strong>Variable length, up to 7,5 N<br><strong>Description: </strong>The sales tax value. If the `type` field in this object is `RATE`, this field should contain the sales tax rate, and the system will automatically calculate the sales tax amount (`amt_tax`) based on this rate. If `type` is `AMOUNT`, this field should contain the sales tax amount.",
          "format": "double"
        }
      }
    }
  }
}