Avalara AVS Service

Arvato’s address verification service integrates with Avalara to validate addresses. A typical use case is to validate shipping and billing addresses during checkout. Verifying an address not only reduces risk of fraud, it may also be required for tax calculation.

Setup

Avalara Setup

In order to use this service you must have an Avalara account. More specifically you will need the following information on hand:

  1. Your Avalara account ID
  2. Your Avalara license key
  3. The URL to the Avalara API

Site Settings Setup

Before you can use the service, you need to update your site settings with the Avalara credentials. This setup guide assumes that you have already created a site for your tenant. For more information about sites and the site settings service, please refer to the YaaS documentation.

This service expects the configuration under /{site}/mixins/avs. The following is an example how to POST a new configuration to the default site. To run this example, you need to subscribe to the hybris Commerce as a Service package and request an oAuth2 access token with the following scope: hybris.site_manage.

Then you must modify the values for serviceUrl, license and account according to the information you've received from Avalara.

Request

  • Method: POST
  • URL: https://api.yaas.io/hybris/site/b1/{tenant}/sites/{site}/mixins
  • Path Parameters:
    • tenant: your-tenant
    • site: default
  • Body:
{
   "avs": {
      "metadata": {
         "schema": "https://api.yaas.io/hybris/schema/b2/arvato/site-settings-service-provider-config.v1.json"
      },
      "id": "avalara",
      "serviceUrl": "https://development.avalara.net/1.0",
      "active": true,
      "configuration": {
         "public": {},
         "restricted": {
            "license": "YOUR_LICENSE",
            "account": "YOUR_ACCOUNT"
         }
      },
      "serviceType": "urn:x-yaas:service:avs"
   }
}
Example

First retrieve an access token with permission to modify restricted site settings. You must replace the values for client_id and client_secret with the values you've received from YaaS.

curl -X POST -H "Accept: application/json" -H "Cache-Control: no-cache" -H "Content-Type: application/x-www-form-urlencoded" -d 'grant_type=client_credentials&scope=hybris.site_manage&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET' 'https://api.yaas.io/hybris/oauth2/b1/token'

After you've successfully retrieved a token, you can use it to create a new AVS configuration (replace YOUR_TOKEN with the actual token). You also need to replace YOUR_LICENSE, YOUR_ACCOUNT and YOUR_TENANT.

curl -X POST -H "Content-Type: application/json; charset=utf-8" -H "Accept: application/json" -H "Authorization: Bearer YOUR_TOKEN" -H "Cache-Control: no-cache" -d '{
   "avs": {
      "metadata": {
         "schema": "https://api.yaas.io/hybris/schema/b2/arvato/site-settings-service-provider-config.v1.json"
      },
      "id": "avalara",
      "serviceUrl": "https://development.avalara.net/1.0",
      "active": true,
      "configuration": {
         "public": {},
         "restricted": {
            "license": "YOUR_LICENSE",
            "account": "YOUR_ACCOUNT"
         }
      },
      "serviceType": "urn:x-yaas:service:avs"
   }
}' 'https://api.yaas.io/hybris/site/b1/YOUR_TENANT/sites/default/mixins'

If the call was successful, you should see a 201 CREATED response similar to this:

{
  "id": "avs",
  "link": "https://api.yaas.io/hybris/site/b1/your-tenant/sites/default/mixins/avs"
}

Not that the arvato AVS service caches these credentials per site. The test system reloads the settings every hour, the live service refreshes the settings every 24 hours. In urgent cases where you require an immediate refresh, please contact our support team.

Accessing the API

Endpoint

The following endpoint is the base for all requests:

Base URL for this endpoint is: https://api.yaas.io/arvato/avalara-avs/v1/tenants/{tenant}

RAML specification: https://api.yaas.io/arvato/avalara-avs/v1/public/api/api.raml

Authentication and Authorization

All API calls are secured by access tokens. Please refer to the general guide about how to retrieve access tokens.

Required subscriptions and scopes

A subscription to the hybris Commerce as a Service package is required in order to retrieve the Avalara credentials from your site configuration. The required scope for this subscription is: hybris.site_manage.

Scopes of this service

At the moment no specific scope is required when requesting access tokens for using this service; a subscription is enough.

API Examples

Validating an address using the default site (/address/validate)

The following example shows how to validate an address.

Request

  • Method: GET
  • URL: https://api.yaas.io/arvato/avalara-avs/v1/tenants/{tenant}/address/validate
  • Path Parameters:
    • tenant: Your tenant identifier
  • Query Parameters:
    • street: N Clark St
    • streetNumber: 118
    • city: Chicago
    • state: IL
    • country: US
    • zipCode: 60602
Example
curl -X GET -H "Authorization: Bearer {token}" -H "Accept: application/json" -H "Cache-Control: no-cache" 'https://api.yaas.io/arvato/avalara-avs/v1/tenants/{tenant}/address/validate?street=N+Clark+St&streetNumber=118&city=Chicago&state=IL&country=US&zipCode=60602'

Response examples

  • Status Code: 200
    {
    "street": "N Clark St",
    "streetNumber": "118",
    "zipCode": "60602-1304",
    "city": "Chicago",
    "country": "US",
    "state": "IL"
    }
    
  • Status Code: 400
    {
    "status": 400,
    "type": "provider_error",
    "message": "The request to the AVS provider resulted in an error.",
    "details":[
      {
        "type": "Error",
        "message": "The address was found but the street number in the input address was not between the low and high range of the post office database."
      }
    ]
    }
    
  • Status Code: 400
    {
    "status": 400,
    "type": "validation_violation",
    "message": "Constraint violation",
    "details": [
      {
        "field": "zipCode",
        "type": "Length",
        "message": "zipCode can have a maximum length of 11 characters"
      }
    ]
    }
    

Validating an address using a specific site (/{site}/address/validate)

The following example shows how to validate an address using site settings of a specific site.

Request

  • Method: GET
  • URL: https://api.yaas.io/arvato/avalara-avs/v1/tenants/{tenant}/{site}/address/validate
  • Path Parameters:
    • site: The id of the site
    • tenant: Your tenant identifier
  • Query Parameters (same as above)

Response

  • same as above