The service generates an invoice for a request with saleMessageType set to INVOICE.

Invoice generation requires Vertex Invoice IQ. Vertex for e-Commerce and Vertex for Marketplaces also enable customer location determination, which can be useful for invoices.

Request

See Mandatory Fields for more information about required fields, additional requirements, and restrictions.

Field	Value	Notes
`customer.customerEmail`	The customer's email address.	If provided and invoice delivery is enabled, the service uses this value to send the invoice.
`customer.customerName`	The customer's name displayed on the invoice.	—
`lineItems[].lineItemDescription`	The line item's name or description displayed on the invoice.	—
`saleMessageType`	`INVOICE`	Required to trigger invoice generation.
`seller.businessName`	The seller's business name displayed on the invoice.	—

Response

The following fields are added to the response when invoice generation is triggered:

Field	Value	Notes
`lineItems[].documentImageUrl`	The URL to the invoice document containing this `lineItem`.	If provided and invoice delivery is enabled, the service uses this value to send the invoice.
`lineItems[].documentImageUrlSecret`	The secret used to access the invoice image URL. Provided by the service; you can ignore it.	—

Invoice customization

Invoice customization—including the invoice number format, logo, footer, and email subject when email delivery is enabled—can be configured through settings or the user interface. You can also override or define these settings on a per-request basis.

The following request fields can affect the invoice format and output:

Field	Value	Notes
`seller.invoicing.invoiceCustomization`	Invoice customization.	Can be used to override configured settings.
`seller.invoicing.invoiceNumberFormat`	The format string used to generate the invoice number.	Can be used to override the default numbering format or the format configured in settings.
`seller.invoicing.invoiceSignatureUrl`	The URL to an image of a signature that appears on invoices in some regions, such as India.	Ignored in most countries but may be required for invoices issued in India.
`seller.marketplace.invoicing.invoiceCustomization.invoiceCustomizationCode`	The identifier for the invoice customization configured in settings.	Used for marketplace-derived invoice details in a three-party sale.
`seller.taxRegistrations[].fiscalRepresentative`	The details about the appointed fiscal representative.	Used when an invoice is generated, and the invoice country matches the registration.

The following request fields apply to seller.invoicing.invoiceCustomization:

Field	Value	Notes
`invoiceCustomizationCode`	The identifier for the invoice customization configured in settings.	—
`invoiceDeliveryEmailAddress`	The email address used in the From field when sending an invoice or credit note to the buyer.	—
`invoiceDeliveryReplyToAddress`	The email address used in the Reply-To field when sending an invoice or credit note to the buyer.	—
`invoiceEmailSubject`	The format string used to generate the email subject for an invoice.	—
`refundEmailSubject`	The format string used to generate the email subject for a credit note.	—
`invoiceLogoUrl`	The URL to the image file containing the logo used when generating an invoice.	—
`invoiceFooterText`	The custom text placed in the footer of the generated invoice.	—

The following request fields apply to seller.taxRegistrations[].fiscalRepresentative:

Field	Value	Notes
`businessName`	The fiscal representative's name.	—
`address`	The Address object from Vertex O Series Cloud.	—
`taxRegistrationNumber`	The fiscal representative's tax number.	—

Example

Example request:

{
  "transactionId": "64266d5fc26241b8b8b60b01ccb67b",
  "saleMessageType": "INVOICE",
  "deliveryTerm": "SUP",
  "customer": {
    // name to display and email for invoice delivery
    "customerName": "Jan Kowalski",
    "customerEmail": "[email protected]",
    "customerCode": {
      "value": "customer1"
    },
    "destination": {
      "country": "PL",
      "city": "Wroclaw",
      "postalCode": "00-010",
      "streetAddress1": "Dworcowa 4"
    }
  },
  "lineItems": [
    {
      "extendedPrice": 200,
      // line item description, to be displayed on invoice
      "lineItemDescription": "Big Expensive Book",
      "product": {
        "productClass": "book"
      }
    }
  ],
  "currency": {
    "isoCurrencyCodeAlpha": "EUR"
  },
  "transactionType": "SALE",
  "seller": {
    "administrativeOrigin": {
      "country": "PL",
      "city": "Warszawa",
      "streetAddress1": "Pocztowa 2",
      "postalCode": "00-003"
    },
    // seller name to display on the invoice
    "businessName": "ACME S.A.",
    "company": "ROOT",
    "division": "seller_1",
    // additional invoicing customization, on request
    "invoicing": {
      "invoiceCustomization": {
        "invoiceLogoUrl": "https://upload.wikimedia.org/wikipedia/commons/8/85/Logo-Test.png?20171228163613",
        "invoiceFooterText": "Customer Invoice Footer"
      },
      "invoiceNumberFormat": "CUSTOM-INVOICE-{{year}}"
    },
    "physicalOrigin": {
      "country": "PL",
      "city": "Warszawa",
      "postalCode": "00-002",
      "streetAddress1": "Kolejowa 1"
    },
    "taxRegistrations": [
      {
        // additional seller fiscal representative in the invoice country 
        "fiscalRepresentative": {
          "businessName": "Ignacy Rzecki",
          "address": {
            "country": "PL",
            "city": "Warszawa",
            "postalCode": "01-234",
            "streetAddress1": "Krakowskie Przedmiescie 7"
          },
          "taxRegistrationNumber": "PL0002"
        },
        "isoCountryCode": "PL",
        "taxRegistrationNumber": "PL00001"
      }
    ]
  }
}

Example response:

{
  "data": {
    ...
    "lineItems": [
      {
        ...
        // added invoice URL 
        "documentImageUrl": "http://localhost:3008/html/v3/invoices/PNjQyNgAAAAY2ZDVmAAAAAGMyNjIAAAgfNDFiODY0MjY2ZDVmYzI2MjQxYjhiOGI2MGIwMWNjYjY3Yg/0/aXgR4PTdWFWXY8Do",
        "documentImageUrlSecret": "aXgR4PTdWFWXY8Do",
         ...
    },
    ...
  },
  ...
}