US Tax Events, Notifications, and Queries

When US taxation is enabled, Event Detail Records (EDRs) and notifications are generated during US taxation of purchase offer, cancel offer, estimated recurring charge, and refund.

Use the tax query SubMan APIs to return additional details from the US tax database. For more information about the tax query SubMan APIs, see the discussion about tax APIs in MATRIXX Subscriber Management API.

Event Detail Records

EDRs generated during US taxation report the total tax amount or tax fee charged, and tax-related information. An MtxEventAppliedTax records tax related information:

Tax rate or tax fee
Tax type
Tax category
Tax authority ID
Tax description
Percentage of net charge taxable
CCH tax data pass type
Exemption code (only when tax is exempt)

When US taxes are refunded, the usage refund of one-time events—Immediate Event Charging (IECs)—is either a full refund or the requested amount. The EDR includes a breakdown of refunding the base charge and refunding each tax applied to the charge.

An MtxAggregationAppliedTax is recorded for aggregated events.

For more information about US taxation fields returned in the EDR, see the discussion about MtxEventAppliedTax, MtxAggregationAppliedTax, and MtxTaxChargeInfo in MATRIXX Integration. For more information about refunds, see the discussion about US tax refunds.

EDRs also include the geocode, customer type, and a record of seller-paid taxes.

Note: If seller-paid tax is not passed on to the consumer, MATRIXX Engine calculates the tax and records the tax as a separate charge list in the EDR with no impact on balances in the consumer's wallet.

If a geocode is used to calculate taxes in a SubMan API PurchaseOffer request, it overrides the geocode provisioned for the subscriber or group object, and the value included in the request is included in the MtxEvent. For more information about CCH tax calculation in purchase offers, see the discussion about product offer REST APIs in MATRIXX Subscriber Management API.

When tiered taxes are applied, the EDR includes details for each tier and the consolidated tax charge to which the tiers apply.

For more information about events generated during US taxation of purchase offer, cancel offer, and estimated recurring charge, see the discussions about MtxEvent, MtxEventAppliedTax, and MtxEventAppliedOffer in MATRIXX Integration.

When there is tax-on-tax, the MtxEvent EDR includes a list of tax-on-tax charges. For more information about the tax-on-tax charges list, see the discussion about MtxEvent in MATRIXX Subscriber Management API.

Notifications

For more information about notifications generated during US taxation of purchase offer, cancel offer, and estimated recurring charge, see the discussions about MtxTaxChargeInfo in MATRIXX Subscriber Management API and MtxBalanceImpactUpdateInfo in MATRIXX Integration.

Queries

Use the request tax queries to return details from the US tax database:

Return tax database status and details specific to the database using the SubMan API MtxRequestTaxQueryStatus. If US taxation is not enabled, the query returns the following error:
```
msg = Tax Database is not open.
status = 33
```
Return valid product group codes and their descriptions using the SubMan API MtxRequestTaxQueryProductGroupList.
Return valid product item codes and their descriptions for a given product group code using the SubMan API MtxRequestTaxQueryProductItemList.
Return valid customer types using the SubMan API MtxRequestTaxQueryCustomerTypeList.
Return the geocode for a given zip+4 or NPA-NXX value using the SubMan API MtxRequestTaxQueryGeoCode.
Return valid exemption codes from the US tax database using the SubMan API MtxRequestTaxQueryExemptionCodeList.

For more information, see the discussions about MtxRequestTaxQueryStatus, MtxRequestTaxQueryProductGroupList, MtxRequestTaxQueryProductItemList, MtxRequestTaxQueryCustomerTypeList, MtxRequestTaxQueryGeoCode, and MtxRequestTaxQueryExemptionCodeList in MATRIXX Subscriber Management API.

Use the SubMan APIs MtxRequestSubscriberPurchaseOffer, MtxRequestGroupPurchaseOffer, MtxRequestSubscriberCancelOffer, MtxRequestGroupCancelOffer, MtxRequestSubscriberEstimateRecurringCharge, and MtxRequestGroupEstimateRecurringCharge to return information about impacted balances.

Use the SubMan APIs MtxResponseSubscription, MtxResponseSubscriber, and MtxResponseGroup to query the list of exemption codes for a customer to determine taxes and tax fees the customer is exempt from paying.