Skip to main content
Avalara Help Center

Metadata specifications

This article applies to:Connector for Stripe Invoicing

In order to calculate sales tax, Connector for Stripe Invoicing requires invoice details, origin address (ship-from), destination address (ship-to), and other parameters, such as Tax Inclusive/Exclusive preferences, item codes, etc.

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

In Stripe Invoicing, metadata can be stored with various objects, such as charge, invoice items, and customers, in key-value pair format. Connector 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. 
    Different metadata objects work is in this order of decreasing preferences for their values:
    • Price
    • Line item
    • Invoice
    • Customer
    • AvaTax configuration.
      If the invoice has metadata then invoice metadata items override the metadata values of Customer metadata and AvaTax configuration settings. On the other hand, Price metadata and Line item metadata items override the values of Invoice metadata.
  • 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, 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. Price metadata
  2. Invoice Line Item metadata
  3. Invoice metadata
  4. Customer metadata
  5. AvaTax configuration

If Connector 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 Preference 4 Preference 5

TaxCode

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

Invoice Line item Metadata Invoice Metadata Customer Metadata N/A N/A

UPCCode

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

Invoice Line item Metadata Invoice Metadata Customer Metadata N/A N/A

ItemCode

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

Invoice Line item Metadata Invoice Metadata Customer Metadata N/A N/A

IsTaxInclusive

The metadata is used to convey whether the selling price of your product is inclusive of tax.

If True, AvaTax separates the product price and applicable tax to display on the invoice.

If False, AvaTax calculates the sales tax on the product price and displays the same on the invoice.

Price metadata Invoice Line item Metadata Invoice Metadata Customer Metadata AvaTax configuration
Exemption_Code Invoice Metadata Customer Metadata N/A N/A N/A

BIN

Business Identification Number

Customer Metadata N/A N/A N/A N/A

Price metadata

Price level metadata sets price level tax preferences. Price level metadata takes priority over line item metadata, invoice metadata, customer metadata, and AvaTax configuration. To use this metadata, add the metadata fields you want to the metadata of the product price.

  • Example of invoice price metadata
    TaxInclusive Invoice.png

  • Metadata added to the price level:
     

    Invoice metadata

    Metadata key

    Information

    Comment

    IsTaxInclusive Optional

    Information about whether tax is included in the selling price.

    If the tax is not included in the selling price, AvaTax calculates the tax and displays it on the invoice.

Invoice line item metadata

Invoice line level metadata sets line level tax preferences. Invoice line level metadata takes priority over invoice metadata, customer metadata, and AvaTax configuration. To use this metadata, add the metadata fields you want to the metadata of the line item, not to the metadata of the product.

  • Example of setting tax code:
    Invoice metadata

    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.

    IsTaxInclusive Optional

    Information about whether tax is included in the selling price.

    If the tax is not included in the selling price, AvaTax calculates the tax and displays it on the invoice.

  • 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-specific metadata line items for their existing customers. Go to Update customer in Connector 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?