Customer location determination requires the Vertex for e-Commerce feature. It is triggered only for requests with digital lineItems. For more information about digital invoices, see Digital Invoice Generation.

All request fields relevant to location determination are optional, but the following conditions must be met:

At least one lineItems is treated as digital, either based on the lineItems[].product object or the default settings.
At least one object used for location determination is provided: customer.administrativeDestination, customer.taxRegistrations[], customer.locationEvidence.bin, customer.locationEvidence.ipAddress, or customer.locationEvidence.selfDeclaration.

Request

Here are the request fields:

Field	Value	Notes
`customer.administrativeDestination`	The Address object from Vertex O Series Cloud.	Used as the `billingAddress` location evidence when provided.
`customer.destination`	The Address object from Vertex O Series Cloud.	When customer location determination is enabled, you can omit `customer.destination`. If it is not provided in the request, the system populates it based on the location determination result.
`customer.locationEvidence.bin.value`	The bank identification number (BIN), or credit card prefix.	—
`customer.locationEvidence.ipAddress.value`	The IP address.	—
`customer.locationEvidence.selfDeclaration.address`	The Address object from Vertex O Series Cloud.	—
`customer.taxRegistrations[]`	At least one valid entry with `VAT Registration` or no `taxRegistrationType`.	Uses the first valid entry to determine the customer location.
`lineItems[].product.value`	The product taxability driver code from Vertex O Series Cloud.	Required when the default behavior treats all `lineItems` as physical goods and no product class taxability driver code is provided. The service uses this value to treat the `lineItem` as digital for invoicing, liability determination, and other purposes. This does not affect taxation because the result depends on how, or whether, the taxability driver code is mapped in Vertex O Series Cloud.
`lineItems[].product.productClass`	The product class taxability driver code from Vertex O Series Cloud.	See `lineItems[].product.value`. Required if no product taxability driver code is provided.

Response

The following fields are set in the response:

Field	Value	Notes
`data.customer.administrativeDestination`	If `administrativeDestination` is not provided, or if the detected country differs from the provided country, this field is updated with the resolved `country` and `mainDivision`.	—
`data.customer.destination`	If `destination` is not provided, this field is updated with the resolved country and `mainDivision`.	—
`data.customer.detectedLocation`	The detected location object. Uses the same format as the standard response.	—
`data.customer.locationEvidence`	The location evidence with the resolved locations added.	—

The following response fields apply to detectedLocation:

Field	Value	Notes
`resolutionMethod`	Indicates whether the location was determined from matching evidence or selected based on the highest-ranked evidence. Location information obtained from tax registration validation always takes precedence.	—
`resolutionStatus`	The status of the location evidence resolution. `CONFIRMED` indicates that the available evidence satisfies the configured requirements. `UNCONFIRMED` indicates that the available evidence does not satisfy the configured requirements.	—
`resolvedLocation.country`	The country resolved from the evidence.	—
`resolvedLocation.mainDivision`	The state, province, or territory resolved from the evidence.	—

The following response fields apply to locationEvidence:

Field	Value	Notes
`resolutionMethod`	Indicates whether the location was determined from matching evidence or selected based on the highest-ranked evidence. Location information obtained from tax registration validation always takes precedence.	—
`resolutionStatus`	The status of the location evidence resolution. `CONFIRMED` indicates that the available evidence satisfies the configured requirements. `UNCONFIRMED` indicates that the available evidence does not satisfy the configured requirements.	—
`resolvedLocation.country`	The country resolved from the evidence.	—
`resolvedLocation.mainDivision`	The state, province, or territory resolved from the evidence.	—

The same format is used for all provided evidence. In addition, locationEvidence.billingAddress is included when customer.administrativeDestination is provided, and locationEvidence.taxRegistration is included when customer.taxRegistrations[] contains a valid tax registration.

Example

Minimal request triggering customer location determination:

{
    "saleMessageType": "INVOICE",
    "deliveryTerm": "SUP",
    "currency": {
        "isoCurrencyCodeAlpha": "EUR"
    },
    "customer": {
        "customerCode": {},
        "taxRegistrations": [
            {
                "isoCountryCode": "CH",
                "taxRegistrationNumber": "CHCHE-154.638.368",
                "validationResult": {
                    "isValid": true
                }
            }
        ],
        "administrativeDestination": {
            "country": "CZ"
        },
        "locationEvidence": {
            "ipAddress": {
                "value": "86.14.99.80"
            },
            "bin": {
                "value": "111216"
            },
            "selfDeclaration": {
                "address": {
                    "country": "PL"
                }
            }
        }
    },
    "lineItems": [
        {
            "extendedPrice": 100,
            "product": {
                "productClass": "_DIGITAL"
            },
            "seller": {
                "administrativeOrigin": {
                    "country": "PL"
                },
                "company": "test-seller",
                "taxRegistrations": [
                    {
                        "isoCountryCode": "PL"
                    }
                ]
            }
        }
    ],
    "transactionType": "SALE",
    "transactionId": "00000000000000000003"
}

Response:

{
    "data": {
        ...
        "customer": {
            // updated by location determination
            "administrativeDestination": {
                "country": "CH",
                "taxAreaId": "807560000"
            },
            ...
            // set by location determination
            "destination": {
                "country": "CH",
                "taxAreaId": "807560000"
            },
            "detectedLocation": {
                "resolutionMethod": "TAX_ID_VALIDATION",
                "resolutionStatus": "CONFIRMED",
                "resolvedLocation": {
                    "country": "CH"
                }
            },
            ...
            // location evidence with results
            "locationEvidence": {
                "billingAddress": {
                    "address": {
                        "city": "Prague",
                        "country": "CZ"
                    },
                    "locationEvidenceRank": 4,
                    "resolvedLocation": {
                        "city": "Prague",
                        "country": "CZ"
                    }
                },
                "bin": {
                    "locationEvidenceRank": 2,
                    "resolvedLocation": {
                        "country": "GB"
                    },
                    "value": "111216"
                },
                "ipAddress": {
                    "locationEvidenceRank": 3,
                    "resolvedLocation": {
                        "country": "GB"
                    },
                    "value": "86.14.99.80"
                },
                "selfDeclaration": {
                    "address": {
                        "country": "PL"
                    },
                    "locationEvidenceRank": 1,
                    "resolvedLocation": {
                        "country": "PL"
                    }
                },
                "taxRegistration": {
                    "address": {
                        "country": "CH"
                    },
                    "locationEvidenceRank": 0,
                    "resolvedLocation": {
                        "country": "CH"
                    }
                }
            },
            "taxRegistrations": [
                {
                    "isoCountryCode": "CH",
                    "taxRegistrationNumber": "CHCHE-154.638.368",
                    "validationResult": {
                        "isValid": true
                    }
                }
            ]
        },
        ...
    },
    ...
}

Insufficient evidence

By default, if detectedLocation is UNCONFIRMED, the service still uses it to populate customer.destination. You can change this behavior using the Don't accept the transaction option in the Conflict resolution for transaction requests settings.

When this option is selected, the service returns an error if detectedLocation is UNCONFIRMED, saleMessageType is INVOICE, and customer.destination is not provided.

Field	Value	Notes
`errors[].code`	`InsufficientLocationEvidence`	—
`errors[].data.detectedLocation`	The detected location object. Uses the same format as the standard response.	—
`errors[].data.locationEvidence`	The location evidence with resolved locations added.	—

Response:

{
    "errors": [
        {
            "code": "InsufficientLocationEvidence",
            "data": {
                "detectedLocation": {
                    "resolutionMethod": "TOP_RANKING",
                    "resolutionStatus": "UNCONFIRMED",
                    "resolvedLocation": {
                        "country": "GB"
                    }
                },
                "locationEvidence": {
                    "bin": {
                        "locationEvidenceRank": 2,
                        "resolvedLocation": {
                            "country": "GB"
                        },
                        "value": "111216"
                    },
                    "ipAddress": {
                        "locationEvidenceRank": 3,
                        "resolvedLocation": {
                            "country": "FR"
                        },
                        "value": "176.31.84.249"
                    }
                }
            },
            "message": "Not enough location evidence provided",
            "target": "customer.locationEvidence"
        }
    ],
    "meta": {
        "extension": "oseries-plus 0.0.0-SNAPSHOT"
    }
}