--- updatedAt: 2026-07-10T20:07:17.000Z agentTools: projectIndex: https://apidocs.ceretax.net/llms.txt --- # Create telco transaction Create a new telecommunications transaction in CereTax. > 📘 Request and response example > > You can find an example of a telco transaction request in various programming languages in the console pane on the right-hand side. Click on "Examples" in the upper right corner of the console pane, select "Wireless Access Charge Example", enter your CERT API Key under "Authentication", and click on the 'Try it' button. > > You can also click on "Examples" in the Response console and select "200 - Wireless Access Charge Example" to view a pre-generated response example. > > **If you are planning on using Node.js for your integration, we recommend using Axios or node-fetch rather than the API library on readme. The samples on this page are for evaluation purposes only.** > 🚧 Required Fields > > All fields and objects noted as required must be passed in your requests. The Create transaction endpoints will return an error when required fields are not passed. We also recommend passing as many non-required fields as possible in each transaction request to take full advantage of CereTax's reporting functionality and rules engine. # OpenAPI definition ```json { "openapi": "3.0.1", "x-stoplight": { "id": "dayb3ify8s0x6" }, "info": { "title": "Transaction API", "description": "CereTax API Documentation for creating and updating telco, sale, and purchase transactions.", "version": "1.0" }, "servers": [ { "url": "https://calc.cert.ceretax.net", "description": "CERT" }, { "description": "Production", "url": "https://calc.prod.ceretax.net" } ], "paths": { "/telco": { "post": { "summary": "Create telco transaction", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/telecom" }, "examples": { "Wireless Access Charge Example": { "value": { "configuration": { "status": "Active", "contentYear": "2024", "contentMonth": "04", "decimals": 2, "calculationType": "S", "profileId": "default" }, "invoice": { "invoiceDate": "2024-04-01", "invoiceNumber": "123", "invoiceTotalAmount": 100, "customerAccount": "123", "businessType": "10", "customerType": "02", "sellerType": "01", "lineItems": [ { "lineId": "1", "dateOfTransaction": "2024-04-01", "psCode": "65010100", "revenue": 100, "units": { "quantity": 1, "type": "03" }, "situs": { "taxSitusRule": "S", "customerAddress": { "billingAddress": { "addressLine1": "3440 Preston Ridge Rd #430", "city": "Alpharetta", "state": "GA", "postalCode": "30005", "country": "US", "validateAddress": true }, "serviceAddress": { "addressLine1": "3440 Preston Ridge Rd #430", "city": "Alpharetta", "state": "GA", "postalCode": "30005", "country": "US", "validateAddress": true } } } } ] } } } } } }, "required": true }, "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoiceResponse" }, "examples": { "Wireless Access Charge Example": { "value": { "invoice": { "discountAmount": 0, "invoiceNumber": "123", "invoiceDate": "2024-04-01", "customerAccount": "123", "totalTaxInvoice": 27.92, "lineItems": [ { "discounted": false, "lineId": "1", "totalTaxLine": 27.92, "taxes": [ { "totalTax": 0.01, "tax": 0.01, "tierId": 0, "description": "FEDERAL COST RECOVERY FEE", "taxAuthorityId": 43843, "taxAuthorityName": "UNITED STATES OF AMERICA", "taxable": true, "taxLevel": "1", "taxLevelDesc": "FEDERAL", "taxType": "102", "taxTypeDesc": "FEDERAL TRS FUND", "taxTypeClass": "123", "taxTypeClassDesc": "TELECOMMUNICATIONS", "reportingCode": "", "percentTaxable": 0.371, "psCode": "65010100", "allocationPercent": 1, "geocode": { "geocode": "US1312101696000", "country": "UNITED STATES OF AMERICA", "county": "FULTON", "local": "ALPHARETTA", "state": "GEORGIA", "district": "" }, "rate": 0.00025, "calculationBaseAmt": 49.89, "originalCalcBase": 37.1, "taxOnTax": 0, "allocationLabels": [], "taxTypeRef": "000", "taxTypeRefDesc": "DEFAULT", "nonTaxableAmount": 62.9, "exemptAmount": 0, "unitType": "01", "unitTypeDesc": "PRICE", "passThroughType": "3", "passThroughTypeDesc": "OPTIONAL", "transactionChargesCalculationBaseAmt": 0, "transactionChargesTax": 0 }, { "totalTax": 1.86, "tax": 1.62, "tierId": 0, "description": "FEDERAL COST RECOVERY FEE", "taxAuthorityId": 43843, "taxAuthorityName": "UNITED STATES OF AMERICA", "taxable": true, "taxLevel": "1", "taxLevelDesc": "FEDERAL", "taxType": "102", "taxTypeDesc": "FEDERAL TRS FUND", "taxTypeClass": "146", "taxTypeClassDesc": "IP CAPTIONED TELEPHONE SERVICE", "reportingCode": "", "percentTaxable": 1, "psCode": "65010100", "allocationPercent": 1, "geocode": { "geocode": "US1312101696000", "country": "UNITED STATES OF AMERICA", "county": "FULTON", "local": "ALPHARETTA", "state": "GEORGIA", "district": "" }, "rate": 0.01615, "calculationBaseAmt": 114.63, "originalCalcBase": 100, "taxOnTax": 0.24, "allocationLabels": [], "taxTypeRef": "000", "taxTypeRefDesc": "DEFAULT", "nonTaxableAmount": 0, "exemptAmount": 0, "unitType": "01", "unitTypeDesc": "PRICE", "passThroughType": "3", "passThroughTypeDesc": "OPTIONAL", "transactionChargesCalculationBaseAmt": 0, "transactionChargesTax": 0 }, { "totalTax": 12.78, "tax": 12.17, "tierId": 0, "description": "FEDERAL UNIVERSAL SERVICE FUND", "taxAuthorityId": 43843, "taxAuthorityName": "UNITED STATES OF AMERICA", "taxable": true, "taxLevel": "1", "taxLevelDesc": "FEDERAL", "taxType": "103", "taxTypeDesc": "FEDERAL UNIVERSAL SERVICE FUND", "taxTypeClass": "123", "taxTypeClassDesc": "TELECOMMUNICATIONS", "reportingCode": "", "percentTaxable": 0.371, "psCode": "65010100", "allocationPercent": 1, "geocode": { "geocode": "US1312101696000", "country": "UNITED STATES OF AMERICA", "county": "FULTON", "local": "ALPHARETTA", "state": "GEORGIA", "district": "" }, "rate": 0.328, "calculationBaseAmt": 38.96, "originalCalcBase": 37.1, "taxOnTax": 0.61, "allocationLabels": [], "taxTypeRef": "000", "taxTypeRefDesc": "DEFAULT", "nonTaxableAmount": 62.9, "exemptAmount": 0, "unitType": "01", "unitTypeDesc": "PRICE", "passThroughType": "3", "passThroughTypeDesc": "OPTIONAL", "transactionChargesCalculationBaseAmt": 0, "transactionChargesTax": 0 }, { "totalTax": 0.01, "tax": 0.01, "tierId": 0, "description": "FEDERAL NANPA FUND", "taxAuthorityId": 43843, "taxAuthorityName": "UNITED STATES OF AMERICA", "taxable": true, "taxLevel": "1", "taxLevelDesc": "FEDERAL", "taxType": "107", "taxTypeDesc": "NANPA FUND", "taxTypeClass": "123", "taxTypeClassDesc": "TELECOMMUNICATIONS", "reportingCode": "", "percentTaxable": 1, "psCode": "65010100", "allocationPercent": 1, "geocode": { "geocode": "US1312101696000", "country": "UNITED STATES OF AMERICA", "county": "FULTON", "local": "ALPHARETTA", "state": "GEORGIA", "district": "" }, "rate": 0.0001047, "calculationBaseAmt": 100, "originalCalcBase": 100, "taxOnTax": 0, "allocationLabels": [], "taxTypeRef": "000", "taxTypeRefDesc": "DEFAULT", "nonTaxableAmount": 0, "exemptAmount": 0, "unitType": "01", "unitTypeDesc": "PRICE", "passThroughType": "3", "passThroughTypeDesc": "OPTIONAL", "transactionChargesCalculationBaseAmt": 0, "transactionChargesTax": 0 }, { "totalTax": 4.22, "tax": 4, "tierId": 0, "description": "STATE SALES TAX", "taxAuthorityId": 162, "taxAuthorityName": "STATE OF GEORGIA", "taxable": true, "taxLevel": "2", "taxLevelDesc": "STATE/PROVINCE", "taxType": "130", "taxTypeDesc": "SALES TAX", "taxTypeClass": "101", "taxTypeClassDesc": "GENERAL MERCHANDISE", "reportingCode": "", "percentTaxable": 1, "psCode": "65010100", "allocationPercent": 1, "geocode": { "geocode": "US1312101696000", "country": "UNITED STATES OF AMERICA", "county": "FULTON", "local": "ALPHARETTA", "state": "GEORGIA", "district": "" }, "rate": 0.04, "calculationBaseAmt": 105.45, "originalCalcBase": 100, "taxOnTax": 0.22, "allocationLabels": [], "taxTypeRef": "000", "taxTypeRefDesc": "DEFAULT", "nonTaxableAmount": 0, "exemptAmount": 0, "unitType": "01", "unitTypeDesc": "PRICE", "passThroughType": "1", "passThroughTypeDesc": "REQUIRED", "transactionChargesCalculationBaseAmt": 0, "transactionChargesTax": 0 }, { "totalTax": 3.59, "tax": 3.3, "tierId": 0, "description": "GA UAF SURCHARGE", "taxAuthorityId": 162, "taxAuthorityName": "STATE OF GEORGIA", "taxable": true, "taxLevel": "2", "taxLevelDesc": "STATE/PROVINCE", "taxType": "168", "taxTypeDesc": "UNIVERSAL SERVICE FUND (RATE)", "taxTypeClass": "123", "taxTypeClassDesc": "TELECOMMUNICATIONS", "reportingCode": "", "percentTaxable": 0.629, "psCode": "65010100", "allocationPercent": 1, "geocode": { "geocode": "US1312101696000", "country": "UNITED STATES OF AMERICA", "county": "FULTON", "local": "ALPHARETTA", "state": "GEORGIA", "district": "" }, "rate": 0.0525, "calculationBaseAmt": 68.34, "originalCalcBase": 62.9, "taxOnTax": 0.29, "allocationLabels": [], "taxTypeRef": "000", "taxTypeRefDesc": "DEFAULT", "nonTaxableAmount": 37.1, "exemptAmount": 0, "unitType": "01", "unitTypeDesc": "PRICE", "passThroughType": "3", "passThroughTypeDesc": "OPTIONAL", "transactionChargesCalculationBaseAmt": 0, "transactionChargesTax": 0 }, { "totalTax": 0.79, "tax": 0.75, "tierId": 0, "description": "DISTRICT SALES TAX", "taxAuthorityId": 9023, "taxAuthorityName": "FULTON COUNTY", "taxable": true, "taxLevel": "3", "taxLevelDesc": "COUNTY", "taxType": "130", "taxTypeDesc": "SALES TAX", "taxTypeClass": "101", "taxTypeClassDesc": "GENERAL MERCHANDISE", "reportingCode": "", "percentTaxable": 1, "psCode": "65010100", "allocationPercent": 1, "geocode": { "geocode": "US1312101696000", "country": "UNITED STATES OF AMERICA", "county": "FULTON", "local": "ALPHARETTA", "state": "GEORGIA", "district": "" }, "rate": 0.0075, "calculationBaseAmt": 105.45, "originalCalcBase": 100, "taxOnTax": 0.04, "allocationLabels": [], "taxTypeRef": "119", "taxTypeRefDesc": "TRANSIT AUTHORITY", "nonTaxableAmount": 0, "exemptAmount": 0, "unitType": "01", "unitTypeDesc": "PRICE", "passThroughType": "1", "passThroughTypeDesc": "REQUIRED", "transactionChargesCalculationBaseAmt": 0, "transactionChargesTax": 0 }, { "totalTax": 3.16, "tax": 3, "tierId": 0, "description": "COUNTY SALES TAX", "taxAuthorityId": 9023, "taxAuthorityName": "FULTON COUNTY", "taxable": true, "taxLevel": "3", "taxLevelDesc": "COUNTY", "taxType": "130", "taxTypeDesc": "SALES TAX", "taxTypeClass": "101", "taxTypeClassDesc": "GENERAL MERCHANDISE", "reportingCode": "", "percentTaxable": 1, "psCode": "65010100", "allocationPercent": 1, "geocode": { "geocode": "US1312101696000", "country": "UNITED STATES OF AMERICA", "county": "FULTON", "local": "ALPHARETTA", "state": "GEORGIA", "district": "" }, "rate": 0.03, "calculationBaseAmt": 105.45, "originalCalcBase": 100, "taxOnTax": 0.16, "allocationLabels": [], "taxTypeRef": "000", "taxTypeRefDesc": "DEFAULT", "nonTaxableAmount": 0, "exemptAmount": 0, "unitType": "01", "unitTypeDesc": "PRICE", "passThroughType": "1", "passThroughTypeDesc": "REQUIRED", "transactionChargesCalculationBaseAmt": 0, "transactionChargesTax": 0 }, { "totalTax": 1.5, "tax": 1.5, "tierId": 0, "description": "ENHANCED 911 FUND", "taxAuthorityId": 38827, "taxAuthorityName": "ALPHARETTA", "taxable": true, "taxLevel": "4", "taxLevelDesc": "CITY/TOWN/VILLAGE", "taxType": "136", "taxTypeDesc": "E911 FEE", "taxTypeClass": "123", "taxTypeClassDesc": "TELECOMMUNICATIONS", "reportingCode": "", "percentTaxable": 1, "psCode": "65010100", "allocationPercent": 1, "geocode": { "geocode": "US1312101696000", "country": "UNITED STATES OF AMERICA", "county": "FULTON", "local": "ALPHARETTA", "state": "GEORGIA", "district": "" }, "rate": 1.5, "calculationBaseAmt": 1, "originalCalcBase": 1, "taxOnTax": 0, "allocationLabels": [], "taxTypeRef": "000", "taxTypeRefDesc": "DEFAULT", "nonTaxableAmount": 0, "exemptAmount": 0, "unitType": "03", "unitTypeDesc": "ACCESS LINE", "passThroughType": "1", "passThroughTypeDesc": "REQUIRED", "transactionChargesCalculationBaseAmt": 0, "transactionChargesTax": 0 } ], "validateAddresses": [ { "addressLine1": "3440 Preston Ridge Rd #430", "addressLine2": "", "addressLine3": "", "addressLine4": "", "city": "Alpharetta", "country": "US", "county": "", "plus4": "3817", "postalCode": "30005", "state": "GA", "validateAddress": true, "geocode": 0, "locationCode": "", "latitude": 34.0723, "longitude": -84.263344, "plusCode": "866Q3PCP+WM", "phoneNumber": "", "addressType": "ServiceAddress", "isShipFromPlaceOfBusiness": false } ], "valid": true, "errorMessages": [], "itemNumber": "", "itemDescription": "", "revenue": 100, "adjustedRevenue": 0, "totalLineDiscount": 0 } ] }, "status": { "currentStatus": "Active" }, "ksuid": "2fqI4Px3PA3cFGuP9IJdrf2xOVr", "systemTraceAuditNumber": "2fqI4Px3PA3cFGuP9IJdrf2xOVr" } } } } } } }, "security": [ { "api_key": [] } ], "operationId": "post-telco", "description": "Create a new telecommunications transaction in CereTax.", "tags": [ "Telecommunications" ] } } }, "components": { "schemas": { "allocation": { "type": "object", "x-examples": { "psCodeAllocation": { "psCodeAllocation": [ { "allocationLabel": "Wireless service", "psCode": "60010100", "businessType": "", "customerType": "", "sellerType": "", "allocationPercent": 0.7 }, { "allocationLabel": "Text messaging", "psCode": "60010200", "businessType": "", "customerType": "", "sellerType": "", "allocationPercent": 0.2 }, { "allocationLabel": "Data service", "allocationValue": "60010300", "businessType": "", "customerType": "", "sellerType": "", "allocationPercent": 0.1 } ] }, "geoCodeAllocation": { "geoCodeAllocation": [ { "allocationLabel": "GA", "postalCode": "30005", "allocationPercent": 0.5 }, { "allocationLabel": "NC", "postalCode": "27278", "allocationPercent": 0.5 } ] } }, "title": "allocationModel", "description": "Product/Bundle (psCodeAllocation) and Location (geocodeAllocation) allocations can be passed directly in transaction requests using the allocation object. \n\nTo allocate a single lineItem across multiple product and service types, use the **psCodeAllocation** object. This allocation type is typically used when a business has grouped (or bundled) multiple products or services into a single price.\n\nTo allocate a single lineItem across multiple locations, use the **geocodeAllocation** object. This allocation type is typically used when a business wants to allocate the sale or use of a product across multiple locations, ex. allocating the use of software licenses across all corporate locations. \n\nExamples are available in our [Transaction Allocations Guide](https://apidocs.ceretax.net/docs/transaction-allocations-guide).", "properties": { "psCodeAllocation": { "type": "array", "description": "Allocates a single lineItem across multiple product and service codes. ", "items": { "type": "object", "properties": { "allocationLabel": { "type": "string", "description": "The custom label that will be assigned to this allocation row. The allocationLabel is usually used to describe the product or service the allocation row represents.", "example": "Wireless service" }, "psCode": { "type": "string", "description": "The psCode that will be used for this allocation row. \n\nValid values for PS codes can be retrieved from the [List PS codes](https://apidocs.ceretax.net/reference/get-pscodes) endpoint of our Data API.", "example": "60010100" }, "businessType": { "type": "string", "description": "The businessType that should be used for this allocation. This is an optional field and will override the businessType passed at the invoice-level in the API request.\n\nValid values for this field and businessType descriptions can be retrieved from the [List business types](https://apidocs.ceretax.net/reference/get-businesstypes) endpoint." }, "customerType": { "type": "string", "description": "The customerType that should be used for this allocation. This is an optional field and will override the customerType passed at the invoice-level in the API request.\n\nValid values for this field and customerType descriptions can be retrieved from the [List customer types](https://apidocs.ceretax.net/reference/get-customertypes) endpoint." }, "sellerType": { "type": "string", "description": "The sellerType that should be used for this allocation. This is an optional field and will override the sellerType passed at the invoice-level in the API request.\n\nValid values for this field and sellerType descriptions can be retrieved from the [List seller types](https://apidocs.ceretax.net/reference/get-sellertypes) endpoint." }, "allocationPercent": { "type": "number", "example": 0.7, "exclusiveMinimum": false, "description": "The percent of the lineItem you want allocated for this allocation row. \n\nThis value must be > 0 and <= 1 and passed as a decimal. For example, to allocate 70% of the line to the specified product or service, use 0.7 as the allocationPercent.\n\nThe total allocation percent across all rows in an allocation must equal 1 (100%)." } }, "required": [ "allocationLabel", "psCode", "allocationPercent" ] } }, "geoCodeAllocation": { "type": "array", "description": "Allocates a single lineItem across multiple locations based on postalCode.", "items": { "type": "object", "properties": { "allocationLabel": { "type": "string", "description": "The custom label that will be assigned to this allocation row. The allocationLabel is usually used to describe the location the allocation row represents.", "example": "Georgia" }, "postalCode": { "type": "string", "description": "The postalCode that will be used for this allocation row.", "example": "30005" }, "allocationPercent": { "type": "number", "description": "The percent of the lineItem you want allocated for this allocation row.\n\nThis value must be > 0 and <= 1 and passed as a decimal. For example, to allocate 70% of the line to the specified location, use 0.7 as the allocationPercent.\n\nThe total allocation percent across all rows in an allocation must equal 1 (100%).", "example": 0.5 } }, "required": [ "allocationLabel", "postalCode", "allocationPercent" ] } } } }, "telecom": { "title": "telecomModel", "type": "object", "description": "", "x-examples": { "example-1": { "systemTraceAuditNumber": "string", "configuration": { "status": "Active", "contentYear": "2023", "contentMonth": "03", "complianceYear": "2023", "complianceMonth": "03", "decimals": 2, "calculationType": "S", "profileId": "default", "responseOptions": { "passThroughType": { "includePassThroughTypes": [ "string" ], "excludeOptionalTaxesInTaxOnTax": false } } }, "invoice": { "invoiceDate": "2023-03-24", "invoiceNumber": "89991", "invoiceTotalAmount": 100.5, "customerAccount": "100001", "businessType": "01", "customerType": "01", "sellerType": "01", "transactionCharges": [ { "shipping": 0, "handling": 0, "shippingAndHandling": 0, "insurance": 0, "miscCharge": 0, "freightOnBoard": "O", "deliveryType": "C", "isMandatory": true } ], "lineItems": [ { "lineId": "1", "itemNumber": "string", "itemDescription": "string", "dateOfTransaction": "2022-10-01", "psCode": "66030100", "revenue": 100.5, "revenueIncludesTax": false, "lineTaxes": 0, "transactionCharges": [ { "shipping": 0, "handling": 0, "shippingAndHandling": 0, "insurance": 0, "miscCharge": 0, "freightOnBoard": "O", "deliveryType": "C", "isMandatory": true } ], "units": { "quantity": 1, "type": "03" }, "taxExemptionCodes": [ { "state": "GA", "taxAuthorityId": "162", "taxLevel": "2,3,4,5", "taxType": "130", "taxTypeClass": "101", "reason": "Resale", "taxExemptionPercentage": 1, "code": "string" } ], "situs": { "taxSitusRule": "C", "tollCalling": { "originationAddress": { "addressLine1": "string", "addressLine2": "string", "addressLine3": "string", "addressLine4": "string", "county": "string", "city": "string", "state": "string", "postalCode": "string", "plus4": "string", "country": "string", "locationCode": "string", "latitude": 0, "longitude": 0, "plusCode": "string", "validateAddress": true, "phoneNumber": "string" }, "terminationAddress": { "addressLine1": "string", "addressLine2": "string", "addressLine3": "string", "addressLine4": "string", "county": "string", "city": "string", "state": "string", "postalCode": "string", "plus4": "string", "country": "string", "locationCode": "string", "latitude": 0, "longitude": 0, "plusCode": "string", "validateAddress": true, "phoneNumber": "string" } }, "privateLine": { "addressPointA": { "addressLine1": "string", "addressLine2": "string", "addressLine3": "string", "addressLine4": "string", "county": "string", "city": "string", "state": "string", "postalCode": "string", "plus4": "string", "country": "string", "locationCode": "string", "latitude": 0, "longitude": 0, "plusCode": "string", "validateAddress": true }, "addressPointZ": { "addressLine1": "string", "addressLine2": "string", "addressLine3": "string", "addressLine4": "string", "county": "string", "city": "string", "state": "string", "postalCode": "string", "plus4": "string", "country": "string", "locationCode": "string", "latitude": 0, "longitude": 0, "plusCode": "string", "validateAddress": true } }, "customerAddress": { "serviceAddress": { "addressLine1": "3440 Preston Ridge Rd #430", "addressLine2": "string", "addressLine3": "string", "addressLine4": "string", "county": "string", "city": "Alpharetta", "state": "GA", "postalCode": "30005", "plus4": "string", "country": "string", "locationCode": "string", "latitude": 0, "longitude": 0, "plusCode": "string", "validateAddress": true }, "billingAddress": { "addressLine1": "string", "addressLine2": "string", "addressLine3": "string", "addressLine4": "string", "county": "string", "city": "string", "state": "string", "postalCode": "string", "plus4": "string", "country": "string", "locationCode": "string", "latitude": 0, "longitude": 0, "plusCode": "string", "validateAddress": true, "phoneNumber": "string" } } }, "attributes": [ { "key": "string", "value": "string" } ], "allocation": { "psCodeAllocation": [ { "allocationLabel": "Wireless service", "psCode": "60010100", "businessType": "string", "customerType": "string", "sellerType": "string", "allocationPercent": 0.7 } ], "geoCodeAllocation": [ { "allocationLabel": "Georgia", "postalCode": "30005", "allocationPercent": 0.5 } ] } } ] } } }, "properties": { "systemTraceAuditNumber": { "type": "string", "description": "A unique customer-provided reference value for this transaction. If a value is not provided, a unique system generated value is assigned. This feature is limited to Active, Posted, and Suspended transaction statuses.\n\nCustomer-provided values cannot include spaces and can only contain the following characters:\n- 0-9\n- a-z\n- A-Z\n- Exclamation point ( **!** )\n- Hyphen ( **-** ) \n- Underscore ( **_** ) \n- Period ( **.** ) \n- Single quote ( **'** )\n- Open parenthesis ( **(** )\n- Close parenthesis ( **)** )\n- Asterisk ( * )", "maxLength": 50 }, "configuration": { "type": "object", "required": [ "contentYear", "contentMonth", "calculationType", "profileId" ], "properties": { "status": { "type": "string", "enum": [ "Active", "Quote", "Posted" ], "description": "The status of this transaction. If a status is not provided, the transaction will be set to Active.", "example": "Active", "default": "Active" }, "contentYear": { "type": "string", "example": "2023", "maxLength": 4, "description": "The content year and month fields determine the rules/rates CereTax uses to calculate tax. For example, if an invoice is dated 2024-04-01, set content year and month to 2024-04 so that CereTax calculates taxes using the rules and rates that are applicable to the year/month of the invoice or bill. \n\ncontentYear must be sent using the **YYYY** format, ex. 2023." }, "contentMonth": { "type": "string", "example": "03", "maxLength": 2, "description": "The content year and month fields determine the rules/rates CereTax uses to calculate tax. For example, if an invoice is dated 2024-04-01, set content year and month to 2024-04 so that CereTax calculates taxes using the rules and rates that are applicable to the year/month of the invoice or bill. \n\ncontentMonth must be sent using the **MM** format, ex. January should be sent as 01, February should be sent as 02, etc." }, "complianceYear": { "type": "string", "description": "The compliance year/month fields are optional. If passed, the fields can be used by CereTax users to filter transaction data for reporting purposes. For example, if a CereTax user needs to run a report to file their April taxes, they can filter on compliance year/month 2024-04. Similar to content year/month, these values will generally follow the invoice or bill date.\n\ncomplianceYear must be sent using the **YYYY** format, ex. 2023.", "example": "2023", "maxLength": 4 }, "complianceMonth": { "type": "string", "description": "The compliance year/month fields are optional. If passed, the fields can be used by CereTax users to filter transaction data for reporting purposes. For example, if a CereTax user needs to run a report to file their April taxes, they can filter on compliance year/month 2024-04. Similar to content year/month, these values will generally follow the invoice or bill date. C\n\ncomplianceMonth must be sent using the **MM** format, ex. January should be sent as 01, February should be sent as 02, etc.", "example": "03", "maxLength": 2 }, "decimals": { "type": "number", "description": "The number of decimals used for tax responses. \n\nA minimum of 2 decimals is required. If no value is provided in the API request or a value less than 2 is provided, the decimal setting will be set to 2.", "example": 2, "maximum": 10, "minimum": 2 }, "calculationType": { "type": "string", "description": "The type of calculation. \n- S-sales **(Default)**\n- P-purchases\n", "enum": [ "S", "P" ], "example": "S" }, "profileId": { "type": "string", "description": "The calculation Profile ID to be used for this transaction. \n\nCereTax will provide this value. Valid values for this field for your account can also be retrieved from the [List profiles](https://apidocs.ceretax.net/reference/get-profiles) endpoint.", "example": "default" }, "responseOptions": { "$ref": "#/components/schemas/responseOptions" } } }, "invoice": { "type": "object", "required": [ "invoiceDate", "businessType", "customerType", "sellerType", "lineItems" ], "properties": { "invoiceDate": { "type": "string", "description": "The invoice date for this transaction. Preferred format is YYYY-MM-DD. MM/DD/YYYY can also be used and will be converted to YYYY-MM-DD when saved. If no value is passed, the current date will be used.", "example": "2023-03-24", "maxLength": 10 }, "invoiceNumber": { "type": "string", "description": "The invoice number for this transaction. This can be a value from your accounting system representing the specific quote, order, or invoice number that is associated with this transaction.", "example": "89991", "maxLength": 250 }, "invoiceTotalAmount": { "type": "number", "description": "The total revenue amount associated with this transaction. This will generally be the sum of all lines.", "example": 100.5 }, "customerAccount": { "type": "string", "description": "The customer reference code from your billing, accounting, and/or ecommerce system for the customer associated with the transaction.", "example": "100001", "maxLength": 250 }, "businessType": { "type": "string", "description": "The type of telecom business for this request. \n- 01-Retail **(Default)**\n- 10-CLEC \n- 11-IXC\n- 12-CMRS/Wireless\n- 13-ILEC\n- 14-Prepaid Wireless\n- 15-VoIP\n- 16-TV Provider \n", "enum": [ "01", "10", "11", "12", "13", "14", "15", "16" ], "example": "14" }, "customerType": { "type": "string", "description": "The type of customer for this invoice. \n- 01-Residential\n- 02-Business/Commercial **(Default)**\n- 04-Senior Citizen\n- 05-Tribal Government\n- 06-Federal Government\n- 07-State Government\n- 08-Local Government\n- 10-Lifeline\n- 12-Retail\n- 13-Tribal Member\n", "enum": [ "01", "02", "04", "05", "06", "07", "08", "10", "12", "13" ], "example": "12", "default": "02" }, "sellerType": { "type": "string", "description": "The type of seller for this invoice.\n- 01-Nexus **(Default)**\n", "enum": [ "01" ], "default": "01", "example": "01" }, "discountAmount": { "type": "number", "example": 0, "description": "The discount amount that should be applied to the transaction. This discount amount will be applied to any lines that have the discounted field set to true. If no lines have the discounted field set to true, the discountAmount will not be applied to any lines. The discountAmount cannot be greater than the sum of all lines subject to the discount." }, "transactionCharges": { "$ref": "#/components/schemas/transactionCharges" }, "lineItems": { "type": "array", "description": "A list of line items associated with this transaction.", "items": { "type": "object", "properties": { "lineId": { "type": "string", "description": "The ID of this line. This can be a numeric line number, alphabetic line number, or any other text that is useful. ", "example": "1", "maxLength": 200 }, "itemNumber": { "type": "string", "description": "The item number, code, SKU, UPC, etc. for the line item.", "maxLength": 250 }, "itemDescription": { "type": "string", "description": "The description of the line item.", "maxLength": 4000 }, "dateOfTransaction": { "type": "string", "description": "Date of transaction. Preferred format is YYYY-MM-DD. MM/DD/YYYY can also be used and will be converted to YYYY-MM-DD when saved. If no value is passed, the current date will be used.", "example": "2022-10-01", "maxLength": 10 }, "psCode": { "type": "string", "description": "Defines the product or service for this line item. If rules are set-up in your profile to apply a valid PS Code, a PS Code does not need to be passed in the API request. \n\nValid values for this field and PS Code descriptions can be retrieved from the [List PS codes](https://apidocs.ceretax.net/reference/get-pscodes) endpoint.", "example": "66030100", "maxLength": 50 }, "revenue": { "type": "number", "description": "The total revenue amount for this line. For negative charges, place a minus sign in the first position.", "example": 100.5 }, "revenueIncludesTax": { "type": "boolean", "description": "Indicates whether the revenue amount for this lineItem already includes tax.\n- False: No tax in revenue **(Default)**\n- True: Revenue includes tax. An adjustedRevenue amount will be returned in the response indicating the tax exclusive portion of the revenue. ", "default": false }, "lineTaxes": { "type": "string", "description": "Determines the type of tax response. **The default is to compute and return all revenue and line based taxes.** However, options are provided to only compute line-based taxes and fees (e.g. E911 fees) where revenue based taxes and fees are suppressed. As well as an option to only compute revenue-based taxes.\n- 0-Compute all revenue and line based taxes and fees **(Default)**\n- 1-Compute only line-based taxes and fees\n- 2-Compute only revenue based taxes and fees\n", "enum": [ "0", "1", "2" ], "default": "0", "example": "0" }, "discounted": { "type": "string", "enum": [ "true", "false" ], "description": "Indicates if the lineItem should be discounted when a discountAmount is specified at the invoice-level. Invoice discounts will only apply to lines where discounted = true. When a discountAmount is specified in the request, the discounted field defaults to true.", "example": "false" }, "transactionCharges": { "$ref": "#/components/schemas/transactionCharges" }, "units": { "type": "object", "required": [ "quantity", "type" ], "properties": { "quantity": { "type": "number", "description": "Quantity of units for line-based calculations. Default is '1' unit.", "example": 1, "default": 1 }, "type": { "type": "string", "description": "Type of units. \n- 03-Access Line **(Default)**\n", "example": "03", "default": "03" } } }, "taxExemptionCodes": { "$ref": "#/components/schemas/taxExemptionCodes" }, "situs": { "$ref": "#/components/schemas/situsTelco" }, "attributes": { "type": "array", "description": "User defined attributes. Must be supplied in an array format of {key:value). Attribues can be used for rule evaluation in CereTax web portal. No limit on the number of attributes that be submitted. Please refrain from using spaces, special characters, or double quotes. Attribute values must be initially set up by the development team in order to reflect in any rules or reporting.", "items": { "type": "object", "properties": { "key": { "type": "string", "maxLength": 250 }, "value": { "type": "string", "maxLength": 250 } } } }, "allocation": { "$ref": "#/components/schemas/allocation" }, "shippable": { "type": "boolean", "description": "Designates if an item should be used for calculating shipping taxes", "default": true } }, "required": [ "dateOfTransaction", "psCode", "revenue", "units", "situs" ] } } } } }, "required": [ "configuration", "invoice" ] }, "invoiceResponse": { "type": "object", "x-examples": { "example-1": { "invoice": { "invoiceNumber": "123-6", "invoiceDate": "2022-08-24", "customerAccount": "NewNumber1Customer", "totalTaxInvoice": 650, "lineItems": [ { "lineId": "1", "totalTaxLine": 650, "taxes": [ { "tax": 600, "tierId": 0, "description": "STATE SALES TAX", "taxAuthorityId": 357, "taxAuthorityName": "STATE OF FLORIDA", "taxable": true, "taxLevel": "2", "taxLevelDesc": "STATE/PROVINCE", "taxType": "130", "taxTypeDesc": "SALES TAX", "taxTypeClass": "101", "taxTypeClassDesc": "GENERAL MERCHANDISE", "reportingCode": "", "percentTaxable": 1, "psCode": "10010100", "allocationPercent": 0, "geocode": { "geocode": "US1208645000000", "country": "USA", "county": "MIAMI-DADE", "local": "MIAMI", "state": "FLORIDA", "district": "" }, "rate": 0.06, "calculationBaseAmt": 10000, "originalCalcBase": 10000, "taxOnTax": 0, "allocationLabels": [], "taxTypeRef": "000", "taxTypeRefDesc": "DEFAULT", "nonTaxableAmount": 0, "exemptAmount": 0, "unitType": "01", "unitTypeDesc": "PRICE" }, { "tax": 50, "tierId": 0, "description": "COUNTY SALES TAX - SINGLE ARTICLE", "taxAuthorityId": 2488, "taxAuthorityName": "MIAMI-DADE COUNTY", "taxable": true, "taxLevel": "3", "taxLevelDesc": "COUNTY", "taxType": "130", "taxTypeDesc": "SALES TAX", "taxTypeClass": "227", "taxTypeClassDesc": "SINGLE ARTICLE", "reportingCode": "", "percentTaxable": 1, "psCode": "10010100", "allocationPercent": 0, "geocode": { "geocode": "US1208645000000", "country": "USA", "county": "MIAMI-DADE", "local": "MIAMI", "state": "FLORIDA", "district": "" }, "rate": 0.01, "calculationBaseAmt": 5000, "originalCalcBase": 5000, "taxOnTax": 0, "allocationLabels": [], "taxTypeRef": "000", "taxTypeRefDesc": "DEFAULT", "nonTaxableAmount": 5000, "exemptAmount": 0, "unitType": "01", "unitTypeDesc": "PRICE" } ], "validateAddresses": [ { "addressLine1": "485 Brickell Ave", "addressLine2": "", "addressLine3": "", "addressLine4": "", "city": "Miami", "country": "", "county": "", "plus4": "2717", "postalCode": "33131", "state": "FL", "validateAddress": true, "geocode": 17150, "locationCode": "", "latitude": 25.768659, "longitude": -80.18913, "plusCode": "76QXQR96+F5" } ], "valid": true, "errorMessages": [] } ] }, "status": { "currentStatus": "Active" }, "ksuid": "2FiXwzClfsdg2pSEjgYan1s8Mfy", "systemTraceAuditNumber": "2FiXwzClfsdg2pSEjgYan1s8Mfy" } }, "description": "", "properties": { "invoice": { "type": "object", "properties": { "discountAmount": { "type": "number", "example": 0, "description": "The discount amount that should be applied to the transaction. This discount amount will be applied to any lines that have the discounted field set to true. If no lines have the discounted field set to true, the discountAmount will not be applied to any lines. The discountAmount cannot be greater than the sum of all lines subject to the discount." }, "invoiceNumber": { "type": "string", "description": "The invoice number for this transaction.", "example": "89991" }, "invoiceDate": { "type": "string", "description": "The invoice date for this transaction.", "example": "2022-10-01" }, "customerAccount": { "type": "string", "description": "The customer reference code from your billing, accounting, and/or ecommerce system for the customer associated with the transaction.", "example": "100001" }, "totalTaxInvoice": { "type": "number", "description": "The total tax for all lines within this transaction", "example": 4.02 }, "lineItems": { "type": "array", "description": "The list of line items associated with this transaction.", "items": { "type": "object", "properties": { "discounted": { "type": "boolean", "description": "Indicates if the lineItem should be discounted when a discountAmount is specified at the invoice-level. Invoice discounts will only apply to lines where discounted = true. When a discountAmount is specified in the request, the discounted field defaults to true." }, "lineId": { "type": "string", "description": "The ID of this line. ", "example": "1" }, "totalTaxLine": { "type": "number", "description": "The total tax calculated for this line", "example": 4.02 }, "itemNumber": { "type": "string", "description": "The item number for this line" }, "itemDescription": { "type": "string", "description": "The item description for this line" }, "revenue": { "type": "number", "description": "The total revenue amount provided for this line." }, "adjustedRevenue": { "type": "number", "description": "When revenueIncludesTax is set to true on a lineItem, an adjustedRevenue amount will be returned in the API response that represents the tax exclusive revenue amount." }, "taxes": { "type": "array", "description": "The list of taxes for this line item.", "items": { "type": "object", "properties": { "totalTax": { "type": "number", "description": "The total amount of tax calculated for this specific tax.", "example": 0 }, "tax": { "type": "number", "description": "The amount of tax calculated for this specific tax, exclusive of tax calculated due to tax on tax. The total tax for this tax is the sum of the tax and taxOnTax fields.", "example": 0 }, "tierId": { "type": "integer" }, "description": { "type": "string", "description": "The name of this tax", "example": "STATE SALES TAX" }, "taxAuthorityId": { "type": "integer", "description": "The ID of the tax authority for this tax", "example": 162 }, "taxAuthorityName": { "type": "string", "description": "The name of the tax authority for this tax", "example": "STATE OF GEORGIA" }, "taxAuthorityTaxId": { "type": "integer", "description": "The tax ID of the tax authority for this tax", "example": 108477 }, "taxable": { "type": "boolean", "description": "Indicates if the specific tax was taxable or not" }, "taxLevel": { "type": "string", "description": "The tax level code for this tax", "example": "2" }, "taxLevelDesc": { "type": "string", "description": "The tax level description for this tax", "example": "STATE/PROVINCE" }, "taxType": { "type": "string", "description": "The tax type code for this tax", "example": "130" }, "taxTypeDesc": { "type": "string", "description": "The tax type description for this tax", "example": "SALES TAX" }, "taxTypeClass": { "type": "string", "example": "101", "description": "The tax type class code for this tax" }, "taxTypeClassDesc": { "type": "string", "example": "GENERAL MERCHANDISE", "description": "The tax type class description for this tax tax" }, "reportingCode": { "type": "string", "description": "The reporting code for this tax." }, "percentTaxable": { "type": "number", "description": "The total percentage of this line's revenue or units considered taxable for this tax", "example": 1 }, "psCode": { "type": "string", "description": "The PS Code associated with the line", "example": "10010100" }, "allocationPercent": { "type": "number", "description": "The allocation percent for this tax. Used when allocations are applied to a line item." }, "geocode": { "type": "object", "description": "The geocode (location) associated with this tax.", "properties": { "geocode": { "type": "string", "example": "US1312101696000", "description": "The geocode (location) associated with this tax." }, "country": { "type": "string", "example": "USA", "description": "The country associated with this geocode (location)" }, "county": { "type": "string", "example": "FULTON", "description": "The county associated with this geocode (location)" }, "local": { "type": "string", "example": "ALPHARETTA", "description": "The local jurisdiction associated with this geocode (location)" }, "state": { "type": "string", "example": "GEORGIA", "description": "The state associated with this geocode (location)" }, "district": { "type": "string", "description": "The district associated with this geocode (location)" } } }, "rate": { "type": "number", "description": "The rate at which this tax was applied", "example": 0.04 }, "calculationBaseAmt": { "type": "number", "example": 100.42, "description": "The adjusted total revenue or units considered for tax. Considers any adjustments to the calculation base, like tax on tax or transaction charges." }, "originalCalcBase": { "type": "number", "example": 100.42, "description": "The unadjusted total amount of revenue or units considered for tax." }, "taxOnTax": { "type": "number", "example": 0, "description": "The tax amount calculated as a result of tax on tax." }, "allocationLabels": { "type": "array", "description": "The allocation label. Used when allocations are applied to a line item.", "items": { "type": "string" } }, "taxTypeRef": { "type": "string", "example": "000", "description": "The tax type ref code for this tax." }, "taxTypeRefDesc": { "type": "string", "example": "DEFAULT", "description": "The tax type ref description for this tax." }, "nonTaxableAmount": { "type": "number", "description": "The amount of revenue or units considered nontaxable for this tax.", "example": 0 }, "exemptAmount": { "type": "number", "description": "The amount of this line's revenue or units considered exempt for this tax", "example": 0 }, "unitType": { "type": "string", "example": "01", "description": "The unit type code for this tax" }, "unitTypeDesc": { "type": "string", "example": "PRICE", "description": "The unit type description for this tax" }, "passThroughType": { "type": "string", "description": "The pass through type code for this tax.", "example": "1" }, "passThroughTypeDesc": { "type": "string", "description": "The pass through type description for this tax.", "example": "REQUIRED" }, "transactionChargesCalculationBaseAmt": { "type": "number", "description": "The amount of the calculation base attributable to transaction charges.", "example": 0 }, "transactionChargesTax": { "type": "number", "description": "The amount of tax calculated for this tax that is attributable to transaction charges.", "example": 0 } } } }, "validateAddresses": { "type": "array", "description": "The validated address details for any addresses where validateAddress was set to true in the transaction request.", "items": { "type": "object", "properties": { "addressLine1": { "type": "string", "description": "Address line 1", "example": "3440 Preston Ridge Road #430" }, "addressLine2": { "type": "string", "description": "Address line 2" }, "addressLine3": { "type": "string", "description": "Address line 3" }, "addressLine4": { "type": "string", "description": "Address line 4" }, "city": { "type": "string", "description": "Address city", "example": "Alpharetta" }, "country": { "type": "string", "description": "Address country" }, "county": { "type": "string", "description": "Address county" }, "plus4": { "type": "string", "description": "Address plus 4" }, "postalCode": { "type": "string", "description": "Address postal code", "example": "30005" }, "state": { "type": "string", "description": "Address state", "example": "GA" }, "validateAddress": { "type": "boolean", "default": true, "description": "Indicates if address validation was requested" }, "geocode": { "type": "integer", "description": "The geocode assigned to the address", "example": 24888 }, "locationCode": { "type": "string", "description": "The location code of the address" }, "latitude": { "type": "number", "description": "The latitude coordinate of the address", "example": 34.090544 }, "longitude": { "type": "number", "description": "The longitude coordinate of the address", "example": -84.218282 }, "plusCode": { "type": "string", "description": "The Google Plus Code assigned to the addresses", "example": "866Q3PCP+GH" } } } }, "valid": { "type": "boolean", "description": "Indicates if the line is valid" }, "errorMessages": { "type": "array", "description": "The error(s) associated with this line. See [Status and Error Codes](https://apidocs.ceretax.net/reference/status-and-error-codes) for a complete list of possible errors.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "4-digit numerical error code" }, "type": { "type": "string", "description": "Specifies the type of error, ex. input, authentication, situs" }, "message": { "type": "string", "description": "A short description of the error" }, "summary": { "type": "string", "description": "A more detailed description of the error" }, "errors": { "type": "object", "description": "The specific fields or values that triggered the error (when applicable)" } } } }, "totalLineDiscount": { "type": "number", "example": 0, "description": "The total discount applied to the line item." } } } } } }, "status": { "type": "object", "properties": { "currentStatus": { "type": "string", "description": "The current status of the transaction", "example": "Active" } } }, "ksuid": { "type": "string", "description": "A unique Ceretax-generated ID for this transaction.", "example": "2Ga0JxOI46vUat44y4L8HKLkVSn" }, "systemTraceAuditNumber": { "type": "string", "description": "A unique customer-provided reference value for this transaction. If a value is not provided, a unique system generated value is assigned.", "example": "2Ga0JxOI46vUat44y4L8HKLkVSn" } } }, "transactionCharges": { "type": "array", "x-examples": {}, "title": "transactionCharges", "description": "The transactionCharges object is for adding invoice or line-level charges, like shipping, handling, insurance, and other misc. charges to a transaction. Transaction charges specified at the invoice-level will be allocated to applicable lines. Transaction charges specified at the line-level are assumed to be already appropriately allocated to the line.", "items": { "type": "object", "properties": { "shipping": { "type": "number", "description": "The amount of the shipping charge." }, "handling": { "type": "number", "description": "The amount of the handling charge." }, "shippingAndHandling": { "type": "number", "description": "The amount of the combined shipping and handling charge." }, "insurance": { "type": "number", "description": "The amount of the insurance charge." }, "miscCharge": { "type": "number", "description": "The amount of the misc. charge." }, "freightOnBoard": { "type": "string", "description": "Indicates the FOB terms of the shipment. FOB terms define when the transfer of ownership occurs for the shipment. \n- O: FOB Origination (buyer takes ownership when the shipment leaves the seller's location)\n- D: FOB Destination (buyer takes ownership when the shipment arrives at the buyer's location)\n- U: FOB Unknown (the FOB terms are unknown)", "enum": [ "O", "D", "U" ] }, "deliveryType": { "type": "string", "description": "Indicates how the shipment is being delivered.\n- C - Common Carrier\n- V - Vendor Vehicle ", "enum": [ "C", "V" ] }, "isMandatory": { "type": "boolean", "description": "Indicates if the transaction charge is mandatory or not." } } } }, "responseOptions": { "type": "object", "x-examples": { "example-1": { "passThroughType": { "includePassThroughTypes": [ "2", "3" ], "includeOptionalTaxesInTaxOnTax ": true } } }, "properties": { "passThroughType": { "type": "object", "properties": { "includePassThroughTypes": { "type": "array", "description": "By default, taxes with a Pass Through Type of 1 (REQUIRED) and 3 (OPTIONAL) are included in transaction responses. Taxes that are prohibited from being passed on to the buyer can also be included in transaction responses by passing a value of \"2\" in the includePassThroughTypes array.", "items": { "type": "string" } }, "excludeOptionalTaxesInTaxOnTax": { "type": "boolean", "description": "By default, taxes with a Pass Through Type of 3 (OPTIONAL) are included in the base of applicable taxes for tax on tax purposes. To exclude optional taxes from tax on tax set excludeOptionalTaxesInTaxOnTax to true.", "default": false } } }, "optionalFields": { "type": "object", "properties": { "taxAuthorityTaxId": { "type": "boolean", "description": "Includes Tax Authority Tax ID in tax results", "default": true }, "attributes": { "type": "boolean", "description": "Returns attributes provided in the API call. This is an optional field, defaults to false", "default": false } } } } }, "taxExemptionCodes": { "type": "array", "x-examples": {}, "description": "Exemptions can be applied to lineItem taxes using the state, taxLevel, taxType, and/or taxTypeClass parameters. Any lineItem taxes matching the state, tax authority, taxLevel, taxType, and/or taxTypeClass included in the taxExemptionCodes object will be treated as exempt. A value for at least one of these fields must be passed for an exemption to be applied. Examples are available in our [Exemptions Guide](https://apidocs.ceretax.net/docs/exemptions-guide).", "items": { "type": "object", "properties": { "state": { "type": "string", "description": "The two character abbreviation the state the exemption applies to.\n\nValid values for this field and state descriptions can be retrieved from the [List states](https://apidocs.ceretax.net/reference/get-states) endpoint.", "example": "GA" }, "taxAuthorityId": { "type": "string", "description": "Defines the the tax authority id that will be used to determine which taxes are candidates for exemption. If multiple tax authorities need to be exempted, they should be passed in a comma separated list.\n\nValid values for this field and tax authority descriptions can be retrieved from the [List tax authorities](https://apidocs.ceretax.net/reference/get-taxauthorities) endpoint.", "example": "162" }, "taxLevel": { "type": "string", "description": "Defines the the tax level that will be used to determine which taxes are candidates for exemption. If multiple tax levels need to be exempted, they should be passed in a comma separated list.\n\nValid values for this field and taxLevel descriptions can be retrieved from the [List tax levels](https://apidocs.ceretax.net/reference/get-taxlevels) endpoint.", "example": "2,3,4,5" }, "taxType": { "type": "string", "description": "Defines the the tax type that will be used to determine which taxes are candidates for exemption. If multiple tax types need to be exempted, they should be passed in a comma separated list.\n\nValid values for this field and taxType descriptions can be retrieved from the [List tax types](https://apidocs.ceretax.net/reference/get-taxtypes) endpoint.", "example": "130" }, "taxTypeClass": { "type": "string", "description": "Defines the the tax type class that will be used to determine which taxes are candidates for exemption. If multiple tax type classes need to be exempted, they should be passed in a comma separated list.\n\nValid values for this field and taxTypeClass descriptions can be retrieved from the [List tax type classes](https://apidocs.ceretax.net/reference/get-taxtypeclasses) endpoint.", "example": "101" }, "reason": { "type": "string", "description": "Tax exemption reason.", "example": "Resale" }, "taxExemptionPercentage": { "type": "number", "example": 1, "description": "Tax exemption percentage for partial exemptions. If no value is provided, 1 (100%) is used." }, "code": { "type": "string", "description": "Tax exemption code for line item. This field can be used to pass a custom exemption code that can be referenced in rules to apply an exemption." } } } }, "situsTelco": { "type": "object", "x-examples": { "example-1": { "customerAddress": { "serviceAddress": { "addressLine1": "", "addressLine2": "", "addressLine3": "", "addressLine4": "", "county": "", "city": "", "state": "", "postalCode": "", "plus4": "", "country": "", "locationCode": "", "latitude": 0, "longitude": 0, "plusCode": "", "validateAddress": false, "phoneNumber": "" }, "billingAddress": { "addressLine1": "", "addressLine2": "", "addressLine3": "", "addressLine4": "", "county": "", "city": "", "state": "", "postalCode": "", "plus4": "", "country": "", "locationCode": "", "latitude": 0, "longitude": 0, "plusCode": "", "validateAddress": false, "phoneNumber": "" } }, "taxSitusRule": "L", "tollCalling": { "originationAddress": { "addressLine1": "", "addressLine2": "", "addressLine3": "", "addressLine4": "", "county": "", "city": "", "state": "", "postalCode": "", "plus4": "", "country": "", "locationCode": "", "latitude": 0, "longitude": 0, "plusCode": "", "validateAddress": false, "phoneNumber": "" }, "terminationAddress": { "addressLine1": "", "addressLine2": "", "addressLine3": "", "addressLine4": "", "county": "", "city": "", "state": "", "postalCode": "", "plus4": "", "country": "", "locationCode": "", "latitude": 0, "longitude": 0, "plusCode": "", "validateAddress": false, "phoneNumber": "" } }, "privateLine": { "addressPointA": { "addressLine1": "", "addressLine2": "", "addressLine3": "", "addressLine4": "", "county": "", "city": "", "state": "", "postalCode": "", "plus4": "", "country": "", "locationCode": "", "latitude": 0, "longitude": 0, "plusCode": "", "validateAddress": false, "phoneNumber": "" }, "addressPointZ": { "addressLine1": "", "addressLine2": "", "addressLine3": "", "addressLine4": "", "county": "", "city": "", "state": "", "postalCode": "", "plus4": "", "country": "", "locationCode": "", "latitude": 0, "longitude": 0, "plusCode": "", "validateAddress": false, "phoneNumber": "" } } } }, "description": "The situs object defines the address types and address details that will be used to determine the tax situs for the line item. At least one of the following address types must be included in the API request:\n\n- customerAddress - Customer service and billing addresses.\n- tollCalling - Used for toll calling using the 2-out-of-3 rule. Either an address and/or a phone number value is required for sections originationAddress, terminationAddress and billingAddress.\n- privateLine - This address block is used for a point-to-point private line transaction. Both point A and point Z are required. Both points of the private line will be evaulated for tax calculation.\n\nCereTax can calculate tax using partial and complete address data. A fully validated address will return the most precise tax calculation. At a minimum, one of the following fields or combination of fields must be populated in order for CereTax to calculate tax for an address:\n- postalCode\n- latitude, longitude\n- plusCode\n- phoneNumber\n- country + state (Canada only)\n\nIf validateAddress is set to true, one of the following field combinations must be passed:\n- addressLine1 + city + state\n- addressLine1 + postalCode", "properties": { "taxSitusRule": { "type": "string", "description": "Defines the address type that will be used to calculate tax on the line.\n- **C** - Toll Calling - Uses tollCalling block (originationAddress, terminationAddress) and billingAddress.\n- **L** - Private Line - Uses privateLine block (addressPointA, addressPointZ).\n- **S** - Customer Address - Uses the customer's serviceAddress or billingAddress with serviceAddress as the priority if values for both are provided." }, "customerAddress": { "type": "object", "description": "Customer service and billing addresses.", "properties": { "serviceAddress": { "$ref": "#/components/schemas/addressModel" }, "billingAddress": { "$ref": "#/components/schemas/addressModel" } } }, "tollCalling": { "type": "object", "description": "Used for toll calling using the 2-out-of-3 rule. Either an address and/or a phone number value is required for sections originationAddress, terminationAddress and billingAddress.", "properties": { "originationAddress": { "$ref": "#/components/schemas/addressModel" }, "terminationAddress": { "$ref": "#/components/schemas/addressModel" } } }, "privateLine": { "type": "object", "description": "This address block is used for a point-to-point private line transaction. Both point A and point Z are required. Both points of the private line will be evaulated for tax calculation.", "properties": { "addressPointA": { "$ref": "#/components/schemas/addressModel" }, "addressPointZ": { "$ref": "#/components/schemas/addressModel" } } } } }, "addressModel": { "type": "object", "x-examples": { "example-1": { "addressLine1": "", "addressLine2": "", "addressLine3": "", "addressLine4": "", "addressType": "", "city": "", "country": "", "county": "", "geocode": 0, "isShipFromPlaceOfBusiness": false, "latitude": 0, "locationCode": "", "longitude": 0, "phoneNumber": "", "plus4": "", "plusCode": "", "postalCode": "", "state": "", "validateAddress": false } }, "properties": { "addressLine1": { "type": "string", "description": "Address line 1.", "example": "3440 Preston Ridge Road" }, "addressLine2": { "type": "string", "description": "Address line 2." }, "addressLine3": { "type": "string", "description": "Address line 3." }, "addressLine4": { "type": "string", "description": "Address line 4." }, "county": { "type": "string", "description": "Address county, if known." }, "city": { "type": "string", "description": "Address city.", "example": "Alpharetta" }, "state": { "type": "string", "description": "Address state.", "example": "GA" }, "postalCode": { "type": "string", "description": "Address postal code. Can be US or Canadian postal code values. \n\nFor US postal codes, the first 5 digits should be passed in this field. If you have a full 9-digit postal code, CereTax expects the first 5 digits to be passed in the postalCode field and the last 4 digits to be passed in the plus4 field. If a full 9-digit postal code is passed in the postalCode field in one of the following formats, CereTax will parse it into its respective fields:\n- **#########** (ex. 300053817)\n- **#####-####** (ex. 30005-3817)\n- **##### ####** (ex. 30005 3817)\n\nCanadian postal codes should be passed in one of the following formats, all uppercase: \n- **A#A #A#** (ex. H1A 0A2 )\n- **A#A#A#** (ex. H1A0A2)", "example": "30005" }, "plus4": { "type": "string", "description": "For US addresses, the last four digits of a 9-digit postal code (ZIP9). For example, if the ZIP9 is 30005-3817, **8266** should be passed in the plus4 field." }, "country": { "type": "string", "description": "The valid 2 or 3-character country abbreviation for the country associated with the address. Valid country abbreviations can be fetched from the [List countries](https://apidocs.ceretax.net/reference/get-countries) endpoint." }, "locationCode": { "type": "string", "description": "Location code value. May be used as an alternate to an address value. These values must be defined in the CereTax web portal." }, "latitude": { "type": "number", "description": "Latitude of address location." }, "longitude": { "type": "number", "description": "Longitude of address location." }, "plusCode": { "type": "string", "description": "PlusCode of address location.\n" }, "validateAddress": { "type": "boolean", "description": "Determines if the address should be validated before the tax calculation. When set to **false**, the address will not be validated before the tax calculation. When set to **true**, the address will be validated before the tax calculation. If set to true, one of the following field combinations must be included in the address object:\n- addressLine1 + city + state\n- addressLine1 + postalCode" }, "phoneNumber": { "type": "string", "description": "Phone number for this address, if known. Number should be formatted as NPANXXNNNN. Place a zero (0) in first position if outside of North America." } } } }, "securitySchemes": { "api_key": { "type": "apiKey", "name": "x-api-key", "in": "header" } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true, "samples-enabled": true } } ```