Include all mandatory fields in your API requests to ensure the service can process them successfully.

The service defines four types of fields:

• Mandatory fields—You must provide these fields to create a valid request. Some fields apply only to specific requests. You can also configure custom mandatory fields. Certain countries require specific invoice fields.
• Service-generated fields—The service automatically generates these fields. Don't include their values.
• Deprecated fields—Newer fields replace these fields. Although the service still supports them, use the replacement fields for new integrations.
• Inactive fields—These fields are no longer active. Don't use them.

Mandatory fields

We sort mandatory fields into the following categories:

• Schema mandatory fields—Some fields, such as custom_id and refund_reason, must be included in the request schema. These fields can be empty, but they must be present.
• Business-required fields—Some fields are required to meet business or regulatory requirements. For example, specific fields are required when generating invoices for certain countries, such as Canada.
• Settings-based mandatory fields—Some fields become mandatory based on service configuration. Users can configure certain requirements through settings, while Vertex can enforce additional mandatory fields during deployment.

Schema mandatory fields

The following fields must be present in the request schema, even if they don't contain a value:

• custom_id (required for transaction lines, but not for transactions)
• refund_reason
• country_code
• currency_code
• product_class
• seller_code

Mandatory fields per request

The following fields are required for a successful Calculate Tax request:

• country_code
• amount or total_amount
• currency_code
• product_class

The following fields are required for a valid Store Transaction request:

• buyer_name
• amount or total_amount
• country_code
• currency_code
• product_class
• seller_code

If any required field is missing, the request will fail, or the service may be unable to calculate tax or create a valid transaction record.

Mandatory fields per country

The following fields are required to calculate tax and generate a valid invoice for the specified country.

Custom mandatory fields

Some fields may be configured as mandatory during service deployment. To determine which fields are required for your deployment, visit the Support section of Vertex Community or contact Customer Support.

When a required field is missing, the API returns a response similar to the following:

"required_fields": {
        "tax_required_fields": [
          {
            "field_name": "billing_address.country_subdivision_code"
          }
        ],
        "storage_required_fields": [
          {
            "field_name": "buyer_name"
          },
          {
            "field_name": "billing_address.city"
          },
          {
            "field_name": "billing_address.postal_code"
          }
        ]
      },

Service-generated fields

The service automatically generates the following fields. Don't provide values for these fields in your requests.

Deprecated fields

The following fields are deprecated. Use the recommended alternative where applicable:

Inactive fields

The following field is inactive and shouldn't be used:

• reverse_charge

The following fields aren't supported in the Calculate Tax request:

• invoice_timestamp
• external_unique_id