Skip to main content
Avalara Help Center

Metadata Specifications

This article applies to:Avalara AvaTax for Stripe Invoicing

In order to calculate sales tax, AvaTax Update for Stripe Invoicing requires the invoice details, origin address, destination address (ship-to), and other parameters e.g. Tax Inclusive/Exclusive preferences, item codes, etc.

The origin address is retrieved from your merchant AvaTax Update configuration. For the destination address, AvaTax Update for Stripe Invoicing relies on the invoice metadata.

In Stripe Invoicing, metadata can be stored with various objects, e.g. charge, invoice items, customers etc., in key value pair format. AvaTax Update for Stripe Invoicing identifies invoice metadata from specific key value pairs. If it doesn’t find the required metadata information, no tax calculation happens and an error is logged for that invoice. 

Metadata specifications

The following metadata is associated with each invoice type:

  • Normal/Standard (non-recurring) invoice
  • Recurring invoices: The metadata is not expected in the recurring invoice and the customer's ship-to address is used. However, if the invoice ship-to address is different from the customer metadata address, then the invoice ship-to address is used. If the invoice has metadata, then invoice metadata items override any other metadata values (e.g. Customer metadata, configuration settings)
  • The information sent in these invoices:
    • Mandatory information: The invoice ship-to address or the customer address
    • Optional information: 
      • Tax inclusive / exclusive
      • Tax Code
      • UPC Code
      • Item Code

If a Stripe Invoicing-generated recurring invoice,does not have metadata, then the customer metadata is used (instead of the invoice metadata). In the case of normal invoices, if the metadata values are set on the invoice metadata then the customer metadata is ignored.

Availability and preferences of metadata values

Higher level metadata always takes precedence over lower level metadata. Metadata will be prioritized in this order: 
1. Invoice Line Item metadata
2. Invoice metadata and
3. Customer metadata

If AvaTax Update for Stripe Invoicing does not find the metadata, it will consider the account level settings on the AvaTax Setup page and the preference is:

Metadata Key Preference 1 Preference 2 Preference 3

TaxCode

Tax is calculated as defined by the rules associated with this tax code in the AvaTax Update.

Invoice Line item Metadata Invoice Metadata Customer Metadata

UPCCode

Tax is calculated as defined by the UPC code for the item in the AvaTax Update.

Invoice Line item Metadata Invoice Metadata Customer Metadata

ItemCode

Mapping items to tax codes in AvaTax Update informs AvaTax Update about the tax rules to use when processing transactions that include the mapped items.

Invoice Line item Metadata Invoice Metadata Customer Metadata

IsTaxInclusive

Information about whether tax is included in the invoice amount.

If the tax is excluded from the invoice amount, then the tax is calculated and added in the invoice amount.

Invoice Metadata Customer Metadata AvaTax for Stripe configuration
Exemption_Code Invoice Metadata Customer Metadata N/A

BIN

Business Identification Number

Customer Metadata N/A N/A

Invoice line item metadata

Invoice line level metadata sets line level tax preferences. Invoice line level metadata takes priority over invoice and customer metadata.

  • Example of setting tax code:

    Metadata key

    Information

    Comment

    TaxCode

    Optional

    This metadata value is used as setting for tax code value.

    UPCCode

    Optional

    This metadata value is used as setting for UPC code value.

    ItemCode

    Optional

    This metadata value is used as setting for item code value.

  • Example of invoice tax code metadata json object:

    Stripe 3 Invoice line item metadata 1.png

Invoice metadata

Invoice metadata is used to set invoice level tax preferences and takes priority over customer metadata. Metadata added here is applicable for all items available in that invoice.

  • Example of invoice metadata:
    Stripe 2 Invoice metadata 1.png
  • Metadata added at the invoice level:
    Invoice metadata

    Metadata key

    Information

    Comment

    Address_Line1

    Optional

    If Line1 has details, the address is validated. 

    Address_Line2

    Optional

    <information>

    Address_Line3

    Optional

    <information>

    Address_City

    Optional

    <information>

    Address_State

    Optional

    <information>

    Address_PostalCode

    Mandatory

    <information>

    Address_Country

    Mandatory

    <information>

    IsTaxInclusive

    Optional

    This metadata value is used as setting for tax inclusive behavior and in case of recurring invoice processing where the metadata value may not be present.

    TaxCode

    Optional

    This metadata value is used as setting for tax code value.

    UPCCode Optional

    This metadata value is used as setting for UPC code value.

    ItemCode

    Optional

    This metadata value is used as setting for item code value.

  • Example of IsTaxInclusive is TRUE:

    Stripe 2 Invoice metadata 2.png

  • Example of IsTaxInclusive is FALSE:

    Stripe 2 Invoice metadata 3.png

Customer metadata

To calculate tax for normal and recurring invoices, key-value pairs from the customer metadata is used only if higher-level metadata is not available.

  • Example of a key-value pair:
    • Key: Address_Line1 
    • Value: <information>
  • Example of customer metadata:
    Stripe 1 Customer metadata 1.png
  • Metadata added at the customer level:
    Customer Metadata
    Metadata key Information Comment

    Address_Line1

    Optional

    If Line1 is has details, the address is validated. 

    Address_Line2

    Optional

    <information>

    Address_Line3

    Optional

    <information>

    Address_City

    Optional

    <information>

    Address_State

    Optional

    <information>

    Address_PostalCode

    Mandatory

    <information>

    Address_Country

    Mandatory

    <information>

    IsTaxInclusive

    Optional

    This metadata value is used as setting for tax inclusive behavior, and in case of recurring invoice processing where the metadata value may not be present.

    TaxCode

    Optional

    This metadata value is used as setting for tax code value and in case of recurring invoice processing where the metadata value may not be present.

    UPCCode Optional

    This metadata value is used as setting for UPC code value and in case of recurring invoice processing where the metadata value may not be present.

    ItemCode

    Optional

    This metadata value is used as setting for item tax code value and is used in case of recurring invoice processing where metadata value might not be present.

    Exemption_Code

    Optional

    If this value is available in the metadata, then the customer will be exempted. If you do not have an exemption code defined, you can choose to send EXEMPT.

    BIN

    Optional

    This metadata value is used only in case of Input VAT transactions for European countries.
  • Example of IsTaxInclusive:

    Stripe 1 Customer metadata 2.png

Customer metadata update

Existing customers can update AvaTax Update specific metadata line items for their existing customers. Go to Update customer in AvaTax Update for Stripe Invoicing and update the customer details. Only if Line1 is has details, the address is validated. 

Stripe 4 Customer metadata update.png

Charge metadata

A charge is a payment, billable either to a customer or a credit card or a debit card. 

A Charge (Payment) can be created for Considerations for calculating sales tax
An Invoice
  • The invoice metadata is considered.
  • If the invoice metadata is not available then the customer metadata is considered.
  • If both, the invoice metadata and the customer metadata, are not available then the charge metadata is considered. 
  • If the invoice metadata, customer metadata, and the charge metadata are not available, then the payment source information is considered.
A Customer
  • The customer metadata is considered.
  • If the customer metadata is not available then the charge metadata is considered. 
  • If both, the customer metadata and the charge metadata, are not available then the payment source information is considered.
An Independent payment
  • The charge metadata is considered. 
  • If the charge metadata is not available then the payment source information is considered.

Reference

  • Was this article helpful?