Below you'll find some of our best practices regarding the use of our APIs
| Task | Type | Description |
|---|---|---|
| API Key | Required | The API key should be passed in the header of every API request you make. |
| Transactions per second (TPS) | Required | TPS limits are set at the account level. Ensure you load test in CERT (Sandbox) to ensure you are within your limits. |
| Validate Address | Optional | By using the address validation URL upon intake of an address or edit of an address, you can maintain your addresses and react to any changes outside of the tax calculation. |
| Service Availability | Optional | You can monitor CereTax services at https://ceretax.betteruptime.com/ |
| Status and Error Codes | Optional | Ensure you are receiving error codes and taking time to determine how to handle and are monitoring your logs. |
| API Functions | Required | There are different endpoints for the following, ensure you have implemented them:
|
| Transaction Status | Required | Quote - The transaction was created in CereTax, but only for the purpose of estimating tax. Quote transactions are temporary and cannot be updated. Active - The transaction has been created in CereTax, but the details of the transaction have not been finalized. When the details of the transaction are finalized, the status should be updated to Posted. Posted - The transaction has been created in CereTax and the details of this transaction have been finalized. Suspended - The transaction is suspended in CereTax. Transactions that should not be in CereTax or do not match your business application should be set to Suspended. Pending - This transaction has been created in CereTax, but it contains one or more line item issues that must be resolved before the transaction can be reprocessed and set to Active. |
| KSUID | Required | Recommendation is to store the KSUID in your logs for troubleshooting. |
| Invoice Number | Required | Invoice number is an important unique identifier that can be used to help identify the invoice and associated line items. |
| Customer Account | Optional | If not sending tax exemption codes as part of the API Request, this is usually the field that drives tax exemption configuration within the CereTax UI. This is also a recommended field for reconciliation purposes. |
| PS Codes | Required | PS Codes are required to determine taxes. Item codes (with associated descriptions) are mapped to PS Codes. Validation of the PS Code Mappings and tax results is important to ensure variances are within your set range. |
| Tax Exemptions | Optional | Testing exemptions and levels for accurate results. |
| Bundles | Optional | Bundle testing for accurate tax results is recommended where applicable. |
| Reports | Optional | Running reports after a data set has been passed through to the CERT (Sandbox) environment is critical to ensure the results align. Reports Highly Recommended: Partner Compliance Reports. |
| Profile | Required | Used to delineate accounts in a global reseller embedded billing partner. Limitation is no UI access for end user. API Guidance: https://apidocs.ceretax.net/reference/post-profiles |
| Attribute | Optional | Additional fields can be optionally sent as custom attributes in the API request to CereTax. If used, these attributes can also be used to define tax Rules in the CereTax UI. API Guidance: https://apidocs.ceretax.net/reference/naming-conventions |
| Item Number | Optional | This is for clients who want to see what item they are sending to CereTax in addition to the submitted psCode on the given transaction |
Handling Refunds in CereTax
Refunds are a common scenario in a tax calculation workflow. This guide describes the available options for processing full or partial refunds. As refund handling can carry tax implications; consult a Trusted Tax Advisor before implementing a solution. Note: This is for custom API integration refund guidance. Please see documentation for integrations for refund guidance within each integration.
Option A: Reverse or Suspend the Original Invoice
Option A: Reverse or Suspend the Original Invoice
This option applies when the original invoice was processed in the current period and a full refund is needed.
Note: This option only applies if the original invoice is in the current period, and not a prior period where it has already been accounted for on a filed tax return. Reversing or suspending the transaction fully cancels out the original invoice by changing its transaction status, which excludes it from CereTax reporting, provided reports are generated based on finalized transaction status only.
- If the finalized transaction status is Active, the transaction status can be updated to Suspended using the Update Transaction Status API.
- If the finalized transaction status is Posted, the transaction can be reversed (which "un-posts" the original invoice) using the Reverse Transactions API.
Option B: Submit a Refund Invoice (Credit Memo)
This option applies when the original invoice was processed in a prior period and has already been accounted for on a filed tax return. A new invoice is submitted with negative revenue values that either partially or fully offset the original invoice.
Note: If the original invoice contains multiple line items, the refund invoice should follow the same line-item structure as the original invoice. Different lines may map to different psCodes, which can carry different tax rates and taxability rules.
Date-Handling Options for the Refund Invoice
When submitting a refund invoice, two fields play a key role: Content Year/Month, which determines which tax rates and taxability rules apply, and Invoice Date, which determines which period the refund invoice is reported
in. Three options are available for setting these fields:
Option 1: Original Content Year/Month + Original Invoice Date
The refund invoice uses the same tax rates and taxability rules as the original invoice, and the refund invoice's date matches the original Invoice Date. For a full refund, the amount of tax credited matches the amount of tax
billed on the original invoice.
- Consideration: this approach may result in filing amended returns.
Option 2: Current Content Year/Month +Current Invoice Date
The refund invoice uses current tax rates and taxability rules.
- Consideration: if a tax rate or taxability change occurred between the original invoice's period and the current period, this can result in a tax calculation difference between the original invoice and the refund invoice.
Option 3: Original Content Year/Month + Current Invoice Date
The refund invoice uses the same tax rates and taxability rules as the original invoice (based on the original Content Year/Month), while the Invoice Date reflects the current period.
- Consideration: this allows the refund invoice to be processed in the current period while keeping the tax treatment aligned with the original invoice period.
Telecom-Specific Considerations
The two sections below apply only to telecom transactions, where line-based taxes and fees are calculated separately from revenue-based taxes. They do not apply to non-telecom transactions, where taxes and fees are calculated on revenue alone.
Telecom: Submitting Refund Amounts for Revenue and Line-Based Taxes and Fees
The following applies to scenarios where line-based taxes and fees are calculated separately from revenue-based taxes, such as telecom transactions.
- To refund revenue: submit the revenue as a negative amount.
Example: -100 - To refund line-based taxes and fees: submit the quantity as a negative
value. Example: -1 - To refund revenue and line-based taxes and fees at the same time:
submit the revenue as a negative amount and the quantity as a
negative value. Example: -100, -1
Telecom: Partial Refunds and Line-Based Taxes and Fees
Consideration: the appropriate approach for partial refunds involving line-based taxes and fees can vary based on business requirements. Consult a Trusted Tax Advisor when determining how to handle these scenarios.
If line-based taxes and fees applied on the original invoice and only a partial refund is being submitted, an option is to credit only the revenue portion and not the line-based taxes and fees. CereTax provides the lineTaxes field, located in the lineItems object of the API request, for this purpose.
- Default value (0): calculates all revenue-based and line-based taxes and fees.
- Value 2: refunds revenue-based taxes only.