Avalara Shipping Verification API

openapi: 3.2.0
info:
  description: 'API for evaluating transactions against direct-to-consumer Beverage Alcohol shipping regulations.


    This API is currently in beta.'
  title: Avalara Shipping Verification API
  version: 3.1.0
servers:
- url: /
security:
- BasicAuth: []
- Bearer: []
tags:
- name: Shipping Verification
paths:
  /api/v2/companies/{companyCode}/transactions/{transactionCode}/shipment/registration:
    delete:
      operationId: deregisterShipment
      parameters:
      - description: The company code of the company that recorded the transaction
        explode: false
        in: path
        name: companyCode
        required: true
        schema:
          type: string
        style: simple
      - description: The transaction code to retrieve
        explode: false
        in: path
        name: transactionCode
        required: true
        schema:
          type: string
        style: simple
      - description: '(Optional): The document type of the transaction to operate on. If omitted, defaults to "SalesInvoice"'
        explode: true
        in: query
        name: documentType
        required: false
        schema:
          enum:
          - SalesInvoice
          - ReturnInvoice
          type: string
        style: form
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
          description: Invalid Transaction
      summary: Removes the transaction from consideration when evaluating regulations that…
      tags:
      - Shipping Verification
      x-accepts: application/json
    put:
      operationId: registerShipment
      parameters:
      - description: The company code of the company that recorded the transaction
        explode: false
        in: path
        name: companyCode
        required: true
        schema:
          type: string
        style: simple
      - description: The transaction code to retrieve
        explode: false
        in: path
        name: transactionCode
        required: true
        schema:
          type: string
        style: simple
      - description: '(Optional): The document type of the transaction to operate on. If omitted, defaults to "SalesInvoice"'
        explode: true
        in: query
        name: documentType
        required: false
        schema:
          enum:
          - SalesInvoice
          - ReturnInvoice
          type: string
        style: form
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
          description: Invalid Transaction
      summary: Registers the transaction so that it may be included when evaluating…
      tags:
      - Shipping Verification
      x-accepts: application/json
  /api/v2/companies/{companyCode}/transactions/{transactionCode}/shipment/registerIfCompliant:
    put:
      operationId: registerShipmentIfCompliant
      parameters:
      - description: The company code of the company that recorded the transaction
        explode: false
        in: path
        name: companyCode
        required: true
        schema:
          type: string
        style: simple
      - description: The transaction code to retrieve
        explode: false
        in: path
        name: transactionCode
        required: true
        schema:
          type: string
        style: simple
      - description: '(Optional): The document type of the transaction to operate on. If omitted, defaults to "SalesInvoice"'
        explode: true
        in: query
        name: documentType
        required: false
        schema:
          enum:
          - SalesInvoice
          - ReturnInvoice
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingVerifyResult'
          description: A ShippingVerifyResult object.
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
          description: Invalid Transaction
      summary: Evaluates a transaction against a set of direct-to-consumer shipping…
      tags:
      - Shipping Verification
      x-accepts: application/json
  /api/v2/companies/{companyCode}/transactions/{transactionCode}/shipment/verify:
    get:
      description: 'The transaction and its lines must meet the following criteria in order to be evaluated:

        * The transaction must be recorded. Using a type of *SalesInvoice* is recommended.

        * A parameter with the name *AlcoholRouteType* must be specified and the value must be one of the following: ''*DTC*'', ''*Retailer DTC*''

        * A parameter with the name *RecipientName* must be specified and the value must be the name of the recipient.

        * Each alcohol line must include a *ContainerSize* parameter that describes the volume of a single container. Use the *unit* field to specify one of the following units: ''*Litre*'', ''*Millilitre*'', ''*gallon (US fluid)*'', ''*quart (US fluid)*'', ''*ounce (fluid US customary)*''

        * Each alcohol line must include a *PackSize* parameter that describes the number of containers in a pack. Specify *Count* in the *unit* field.


        Optionally, the transaction and its lines may use the following parameters:

        * The *ShipDate* parameter may be used if the date of shipment is different than the date of the transaction. The value should be ISO-8601 compliant (e.g. 2020-07-21).

        * The *RecipientDOB* parameter may be used to evaluate age restrictions. The value should be ISO-8601 compliant (e.g. 2020-07-21).

        * The *PurchaserDOB* parameter may be used to evaluate age restrictions. The value should be ISO-8601 compliant (e.g. 2020-07-21).

        * The *SalesLocation* parameter may be used to describe whether the sale was made *OnSite* or *OffSite*. *OffSite* is the default value.

        * The *AlcoholContent* parameter may be used to describe the alcohol percentage by volume of the item. Specify *Percentage* in the *unit* field.


        **Security Policies**

        This API depends on all of the following active subscriptions: *AvaAlcohol, AutoAddress, AvaTaxPro*'
      operationId: verifyShipment
      parameters:
      - description: The company code of the company that recorded the transaction
        explode: false
        in: path
        name: companyCode
        required: true
        schema:
          type: string
        style: simple
      - description: The transaction code to retrieve
        explode: false
        in: path
        name: transactionCode
        required: true
        schema:
          type: string
        style: simple
      - description: '(Optional): The document type of the transaction to operate on. If omitted, defaults to "SalesInvoice"'
        explode: true
        in: query
        name: documentType
        required: false
        schema:
          enum:
          - SalesInvoice
          - ReturnInvoice
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingVerifyResult'
          description: A ShippingVerifyResult object.
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
          description: Invalid Transaction
      summary: Evaluates a transaction against a set of direct-to-consumer shipping regulations
      tags:
      - Shipping Verification
      x-accepts: application/json
components:
  schemas:
    ErrorDetails:
      description: Message Object
      example:
        error:
          code: InvalidAddress
          message: The address is not deliverable.
          details:
          - code: InvalidAddress
            number: 309
            message: The address is not deliverable.
            description: The physical location exists but there are no homes on this street. One reason might be railroad tracks or rivers running alongside this street, as they would prevent construction of homes in this location.
            faultCode: Client
            helpLink: http://developer.avalara.com/avatax/errors/InvalidAddress
            severity: Error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetails_error'
      type: object
    ShippingVerifyResult:
      description: The Response of the /shippingverify endpoint. Describes the result of checking all applicable shipping rules against each line in the transaction.
      example:
        compliant: true,
        message: Transaction is Compliant
        successMessages: 'Line "0001": The recipient is older than 21 years of age. A current license exists for Washington. Line "0002": The recipient is older than 21 years of age. A current license exists for Maui County, HI.'
        failureMessages: ''
        failureCodes: []
        warningCodes: []
        lines:
        - resultCode: Compliant
          lineNumber: '0001'
          message: Item is Compliant
          successMessages: The recipient is older than 21 years of age. A current license exists for Washington
          failureMessages: ''
          failureCodes: []
        - resultCode: Compliant
          lineNumber: '0002'
          message: Item is Compliant
          successMessages: The recipient is older than 21 years of age. A current license exists for Maui County, HI.
          failureMessages: ''
          failureCodes: []
      properties:
        compliant:
          description: Whether every line in the transaction is compliant.
          type: boolean
        message:
          description: A short description of the result of the compliance check.
          type: string
        successMessages:
          description: A detailed description of the result of each of the passed checks made against this transaction, separated by line.
          type: string
        failureMessages:
          description: A detailed description of the result of each of the failed checks made against this transaction, separated by line.
          type: string
        failureCodes:
          description: An enumeration of all the failure codes received across all lines.
          items:
            enum:
            - BelowLegalDrinkingAge
            - ShippingProhibitedToAddress
            - MissingRequiredLicense
            - VolumeLimitExceeded
            - InvalidFieldValue
            - MissingRequiredField
            - InvalidFieldType
            - InvalidFormat
            - InvalidDate
            type: string
          type: array
        warningCodes:
          description: An enumeration of all the warning codes received across all lines that a determination could not be made for.
          items:
            enum:
            - UnsupportedTaxCode
            - UnsupportedAddress
            type: string
          type: array
        lines:
          description: Describes the results of the checks made for each line in the transaction.
          items:
            $ref: '#/components/schemas/ShippingVerifyResult_lines'
          type: array
      type: object
    ErrorDetails_error_details:
      description: Message Details Object
      properties:
        code:
          description: Name of the error or message.
          enum:
          - AuthenticationException
          - SubscriptionRequired
          - UnhandledException
          - InvalidAddress
          - EntityNotFoundError
          example: InvalidAddress
          type: string
        message:
          description: Concise summary of the message, suitable for display in the caption of an alert box.
          example: The address is not deliverable.
          type: string
        number:
          description: Unique ID number referring to this error or message.
          example: 309
          type: integer
        description:
          description: A more detailed description of the problem referenced by this error message, suitable for display in the contents area of an alert box.
          example: The physical location exists but there are no homes on this street. One reason might be railroad tracks or rivers running alongside this street, as they would prevent construction of homes in this location.
          type: string
        faultCode:
          description: Indicates the SOAP Fault code, if this was related to an error that corresponded to AvaTax SOAP v1 behavior.
          example: Client
          type: string
        helpLink:
          description: URL to help for this message
          example: http://developer.avalara.com/avatax/errors/InvalidAddress
          type: string
        severity:
          description: Severity of the message
          enum:
          - Error
          example: Error
          type: string
      type: object
    ErrorDetails_error:
      description: An object holding details about the error.
      properties:
        code:
          description: Name of the error or message.
          enum:
          - AuthenticationException
          - SubscriptionRequired
          - ServerConfiguration
          - InvalidAddress
          - EntityNotFoundError
          example: InvalidAddress
          type: string
        message:
          description: Concise summary of the message, suitable for display in the caption of an alert box.
          example: The address is not deliverable.
          type: string
        details:
          $ref: '#/components/schemas/ErrorDetails_error_details'
      type: object
    ShippingVerifyResult_lines:
      properties:
        resultCode:
          description: Describes whether the line is compliant or not. In cases where a determination could not be made, resultCode will provide the reason why.
          enum:
          - Compliant
          - NotCompliant
          - UnsupportedTaxCode
          - UnsupportedAddress
          - InvalidLine
          type: string
        lineNumber:
          description: The lineNumber of the line evaluated.
          type: string
        message:
          description: A short description of the result of the checks made against this line.
          type: string
        successMessages:
          description: A detailed description of the result of each of the passed checks made against this line.
          type: string
        failureMessages:
          description: A detailed description of the result of each of the failed checks made against this line.
          type: string
        failureCodes:
          description: An enumeration of all the failure codes received for this line.
          items:
            enum:
            - BelowLegalDrinkingAge
            - ShippingProhibitedToAddress
            - MissingRequiredLicense
            - VolumeLimitExceeded
            - InvalidFieldValue
            - MissingRequiredField
            - InvalidFieldType
            - InvalidFormat
            - InvalidDate
            type: string
          type: array
      type: object
  securitySchemes:
    BasicAuth:
      scheme: basic
      type: http
    Bearer:
      description: A Bearer token generated by Avalara Identity. Prefix your token with the string \'Bearer \'.
      in: header
      name: Authorization
      type: apiKey
x-provenance:
  first_party: true
  method: harvested
  provider_published: true
  source: https://raw.githubusercontent.com/avadev/Avalara-SDK-Java/HEAD/api/openapi.yaml
  harvested: '2026-08-05'
  note: Published by Avalara in its own Java SDK repository under the avadev GitHub organization. Not offered as a downloadable definition on developer.avalara.com.