Mandatory Fields

Two fields are always required for a successful request to Vertex O Series Cloud and, by extension, any Vertex O Series Online Commerce request.

Here are the required fields:

Field	Value	Notes
`saleMessageType`	`QUOTATION` or `INVOICE`	The service does not support `DISTRIBUTE_TAX`.
`transactionType`	`SALE`	The service does not support `RENTAL` or `LEASE`.

This means that the minimal valid request looks like this:

{
  "saleMessageType": "QUOTATION",
  "transactionType": "SALE"
}

This request results in the following response:

{
    "data": {
        "documentDate": "2026-02-18",
        "lineItems": [],
        "returnAssistedParametersIndicator": true,
        "roundAtLineLevel": false,
        "saleMessageType": "QUOTATION",
        "subTotal": 0.0,
        "total": 0.0,
        "totalTax": 0.0,
        "transactionType": "SALE"
    },
    "meta": {
        "app": "vertex-ws.war v9.0.22.0.208",
        "extension": "oseries-plus 0.0.0-SNAPSHOT",
        "timeElapsed(ms)": 2,
        "timeReceived": "2026-02-18T14:22:54.125Z"
    }
}

Quotation requirements

The QUOTATION message type does not introduce additional required fields.

Invoice requirements

The required fields can vary depending on the features available to the user. Vertex Validator does not introduce additional required fields.

When the user has Vertex for e-Commerce, Vertex for Marketplaces, or Vertex Invoice IQ, the following fields are required to create the minimal valid request:

Field	Value	Notes
`currency.isoCurrencyCodeAlpha`	The three-letter ISO currency code, for example, `USD` or `EUR`.	The transaction currency. Required for invoicing and reporting.
`customer.destination.country`	The two-letter ISO country code.	Required by default. Not required if the transaction is for digital goods.
`deliveryTerm`	`SUP`	Other delivery terms are not supported.
`lineItems[].customer.destination.country`	—	Required if the top-level customer is not specified.
`lineItems[].extendedPrice`	The value must be greater than or equal to 0.	At least one line item is required, and it must specify the `extendedPrice`.
`lineItems[].seller.company`	—	Required if the top-level customer is not specified.
`lineItems[].seller.physicalOrigin.country`	—	Required if the top-level customer is not specified.
`lineItems[].unitPrice`	—	Required if the `extendedPrice` is not specified.
`seller.company`	The `company` value.	Does not have to point to an existing taxpayer in O Series. We can manage
`seller.physicalOrigin.country`	—	Required by default. Not required if the transaction is for digital goods.
`transactionId`	The value must be at least 20 characters and unique to the tenant.	Required to support refunds.

This means that the minimal valid request looks like this:

{
    "customer": {
        "destination": {
            "country": "IE"
        }
    },
    "currency": {
        "isoCurrencyCodeAlpha": "EUR"
    },
    "deliveryTerm": "SUP",
    "lineItems": [
        {
            "extendedPrice": 100
        }
    ],
    "saleMessageType": "INVOICE",
    "seller": {
        "company": "test_seller",
        "physicalOrigin": {
            "country": "FR"
        }
    },
    "transactionId": "00000000000000000001",
    "transactionType": "SALE"
}

Invoice restrictions

When the user has Vertex for e-Commerce, Vertex for Marketplaces, or Vertex Invoice IQ, the following additional restrictions apply:

Field	Notes
`customer` `lineItems[].customer`	Only one `customer` is allowed per request. You can specify the `customer` multiple times in a request, such as at the top level and on individual `lineItems`, but all instances must be identical.
`lineItems[].extendedPrice` `lineItems[].fairMarketValue` `lineItems[].unitPrice`	If present, the value must be greater than or equal to `0`. Negative values are reserved for refunds.
`lineItems[].lineItems[]…`	Nested `lineItems` are not allowed.
`lineItems[].consignmentId`	If `consignmentId` is specified, all lines with the same seller—identified by `company`, `division`, and `department`—and the `consignmentIdvalue` must have the `samephysicalOrigin`. The `consignmentId` groups lines for liability determination when per-consignment goods-value checks are used.
`transactionId`	Must be unique. Submitting subsequent `INVOICE` requests with the same `transactionId` value results in an error.

If these restrictions are violated, the request fails, and the response contains information about the violation.

Country restrictions

Some countries, determined using customer.destination.country, have additional restrictions that are enforced for INVOICE requests:

Field	Value	Notes
`customer.customerName`	`CA`, `JP`, `NO`	—
`customer.destination.city`	`CA`, `NO`	—
`customer.destination.mainDivision`	`AE`, `IN`	—
`customer.destination.postalCode`	`CA`	—
`paymentDue`	`OM`	The date on which the purchaser paid for the product.
`paymentDueDate`	`NO`	The date on which payment is due.
`supplyDate`	`CH`, `KR`, `OM`, `TR`	The date on which the product or service is supplied.

If these restrictions are violated, the request fails, and the response contains information about the violation.

Restrictions example

The following request returns several restriction violations:

{
    "currency": {
        "isoCurrencyCodeAlpha": "EUR"
    },
    "deliveryTerm": "SUP",
    "lineItems": [
        {
            "customer": {
                "destination": {
                    "country": "IE"
                }
            },
            "consignmentId": "1",
            "extendedPrice": 100,
            // nested lineItems, not allowed
            "lineItems": [
                {
                    "extendedPrice": 10
                }
            ],
            "seller": {
                "company": "test_seller",
                "physicalOrigin": {
                    "country": "FR"
                }
            }
        },
        {
            // another customer, with different destination
            "customer": {
                "destination": {
                    "country": "PL"
                }
            },
            // consignmentId is present, but seller.physicalOrigin is different than on the first line
            "consignmentId": "1",
            "extendedPrice": 100,
            "seller": {
                "company": "test_seller",
                "physicalOrigin": {
                    "country": "DE"
                }
            }
        }
    ],
    "saleMessageType": "INVOICE",
    // duplicated transactionId (was used before)
    "transactionId": "00000000000000000001",
    "transactionType": "SALE"
}

This request results in the following response:

{
    "errors": [
        {
            "code": "Bad Request",
            "message": "Transaction for the provided transactionId already exists.",
            "target": "/vertex-ws/v2/supplies"
        },
        {
            "code": "Bad Request",
            "message": "Nested lineItems are not supported.",
            "target": "/vertex-ws/v2/supplies"
        },
        {
            "code": "Bad Request",
            "message": "There should be only one distinct customer per transaction.",
            "target": "/vertex-ws/v2/supplies"
        },
        {
            "code": "Bad Request",
            "message": "Please ensure that all lineItems within a single consignment have the same seller (company/division/department) and physicalOrigin address",
            "target": "/vertex-ws/v2/supplies"
        }
    ],
    "meta": {
        "extension": "oseries-plus 0.0.0-SNAPSHOT"
    }
}