Understand the Stripe Invoicing metadata that impacts AvaTax

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.

Higher level metadata always takes precedence over lower level metadata. Metadata will be prioritized in this order: 

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:

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
  

• 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 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:

  

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:
  
• 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:

  

• Example of IsTaxInclusive is FALSE:

  

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:
  
• 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 a 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 a 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 a 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 a 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.
  EntityUseCode	Optional	This metadata value is used as a setting for determining product taxability.
  BIN	Optional	This metadata value is used only in case of Input VAT transactions for European countries.

• Example of IsTaxInclusive:

  

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