--- updatedAt: 2026-07-10T20:07:17.000Z agentTools: projectIndex: https://apidocs.ceretax.net/llms.txt --- # Create sale transaction Create a new general sales transaction in CereTax. > 📘 Request and response example > > You can find an example of a general sale 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 "General Sale 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 - General Sale Response" 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": { "/sale": { "post": { "summary": "Create sale transaction", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sale" }, "examples": { "General Sale Example": { "value": { "configuration": { "status": "Active", "contentYear": "2024", "contentMonth": "04", "decimals": 2, "calculationType": "S", "profileId": "default" }, "invoice": { "invoiceDate": "2024-04-01", "invoiceNumber": "89991", "invoiceTotalAmount": 110.42, "customerAccount": "100001", "businessType": "01", "customerType": "02", "sellerType": "01", "lineItems": [ { "lineId": "1", "dateOfTransaction": "2024-04-01", "psCode": "10010100", "revenue": 100.42, "units": { "quantity": 1, "type": "01" }, "transactionCharges": [ { "shipping": 10, "handling": 0, "isMandatory": true, "freightOnBoard": "D", "deliveryType": "C" } ], "situs": { "taxSitusRule": "T", "shipToAddress": { "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": { "General Sale Example": { "value": { "invoice": { "invoiceNumber": "89991", "invoiceDate": "2024-04-01", "customerAccount": "100001", "totalTaxInvoice": 8.56, "lineItems": [ { "lineId": "1", "totalTaxLine": 8.56, "taxes": [ { "tax": 4.42, "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": "10010100", "allocationPercent": 0, "geocode": { "geocode": "US1312101696000", "country": "USA", "county": "FULTON", "local": "ALPHARETTA", "state": "GEORGIA", "district": "" }, "rate": 0.04, "calculationBaseAmt": 110.42, "originalCalcBase": 110.42, "taxOnTax": 0, "allocationLabels": [], "taxTypeRef": "000", "taxTypeRefDesc": "DEFAULT", "nonTaxableAmount": 0, "exemptAmount": 0, "unitType": "01", "unitTypeDesc": "PRICE" }, { "tax": 0.83, "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": "10010100", "allocationPercent": 0, "geocode": { "geocode": "US1312101696000", "country": "USA", "county": "FULTON", "local": "ALPHARETTA", "state": "GEORGIA", "district": "" }, "rate": 0.0075, "calculationBaseAmt": 110.42, "originalCalcBase": 110.42, "taxOnTax": 0, "allocationLabels": [], "taxTypeRef": "119", "taxTypeRefDesc": "TRANSIT AUTHORITY", "nonTaxableAmount": 0, "exemptAmount": 0, "unitType": "01", "unitTypeDesc": "PRICE" }, { "tax": 3.31, "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": "10010100", "allocationPercent": 0, "geocode": { "geocode": "US1312101696000", "country": "USA", "county": "FULTON", "local": "ALPHARETTA", "state": "GEORGIA", "district": "" }, "rate": 0.03, "calculationBaseAmt": 110.42, "originalCalcBase": 110.42, "taxOnTax": 0, "allocationLabels": [], "taxTypeRef": "000", "taxTypeRefDesc": "DEFAULT", "nonTaxableAmount": 0, "exemptAmount": 0, "unitType": "01", "unitTypeDesc": "PRICE" } ], "validateAddresses": [ { "addressLine1": "3440 Preston Ridge Rd #430", "addressLine2": "", "addressLine3": "", "addressLine4": "", "city": "Alpharetta", "country": "US", "county": "", "plus4": "3817", "postalCode": "30005", "state": "GA", "validateAddress": true, "geocode": 24888, "locationCode": "", "latitude": 34.072309, "longitude": -84.263345, "plusCode": "866Q3PCP+WM" } ], "valid": true, "errorMessages": [], "revenue": 100.42, "adjustedRevenue": 0 } ] }, "status": { "currentStatus": "Active" }, "ksuid": "2GSdgqmHhNhEfzdzfoDkoBzR2N3", "systemTraceAuditNumber": "2GSdgqmHhNhEfzdzfoDkoBzR2N3" } } } } } } }, "security": [ { "api_key": [] } ], "operationId": "post-sale", "description": "Create a new general sales transaction in CereTax.", "tags": [ "General sales" ], "parameters": [] } } }, "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" ] } } } }, "sale": { "title": "saleModel", "type": "object", "x-examples": {}, "description": "", "properties": { "systemTraceAuditNumber": { "type": "string", "example": "50", "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 ( * )" }, "configuration": { "type": "object", "required": [ "contentYear", "contentMonth", "calculationType", "profileId" ], "properties": { "status": { "type": "string", "description": "The status of this transaction. If a status is not provided, the transaction will be set to Active.\n", "enum": [ "Active", "Quote", "Posted" ], "default": "Active", "example": "Active" }, "contentYear": { "type": "string", "example": "2023", "maxLength": 4, "minLength": 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", "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.", "example": "03", "maxLength": 2, "minLength": 2 }, "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, "minLength": 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, "minLength": 2 }, "decimals": { "type": "number", "example": 2, "maximum": 10, "minimum": 2, "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." }, "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": "2022-10-01", "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 plus any delivery charges.", "example": 110.42 }, "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 business for this request. \n- 01-Retail **(Default)**\n\n For Energy use the following:\n- 17-Non-Regulated Reseller\n- 18-Energy Trading\n- 19-Traditional Regulated Utility\n- 20-Regulated Distributor in Deregulated Market\n", "enum": [ "01", "17", "18", "19", "20" ], "example": "01" }, "customerType": { "type": "string", "description": "The type of customer for this invoice. \n- 02-Business/Commercial **(Default)**\n- 12-Retail\n\n For Energy use the following:\n- 01-Residential\n- 02-Commercial\n- 03-Industrial\n- 04-Senior Citizen\n- 05-Tribal Government\n- 06-Federal Government\n- 07-State Government\n- 08-Local Government\n- 10-Lifeline\n- 11-Manufacturing\n- 13-Tribal Member\n- 14-Agriculture\n", "enum": [ "01", "02", "03", "04", "05", "06", "07", "08", "10", "11", "12", "13", "14" ], "example": "02", "default": "02" }, "sellerType": { "type": "string", "description": "The type of seller for this invoice.\n- 01-Physical Nexus in State **(Default)**\n", "enum": [ "01" ], "example": "01" }, "discountAmount": { "type": "number", "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.", "example": 0 }, "transactionCharges": { "$ref": "#/components/schemas/transactionCharges" }, "billingPeriodStartDate": { "type": "string", "description": "The billing period start date 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.", "example": "2022-10-01", "maxLength": 10 }, "billingPeriodEndDate": { "type": "string", "description": "The billing period end date 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.", "example": "2022-10-01", "maxLength": 10 }, "billingDaysInPeriod": { "type": "integer", "description": "The number of billing days in the period in the transaction.", "example": 10, "maxLength": 3 }, "contractValue": { "type": "number", "description": "The value of the contract in the transaction. Field is limited to 10 decimal places.", "example": 100.51, "maxLength": 12 }, "systemOrigin": { "type": "string", "description": "The system of origin.", "maxLength": 25 }, "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": "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": "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": "10010100", "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.42 }, "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 }, "singleArticleGroup": { "type": "string", "description": "User-defined value to identify line items to group for single-atricle calculations. If two or more lines items on the invoice should be evaluated together as a single article, pass a value in this field that matches between the lines.", "maxLength": 50 }, "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." }, "transactionCharges": { "$ref": "#/components/schemas/transactionCharges" }, "units": { "type": "object", "required": [ "quantity", "type" ], "properties": { "quantity": { "type": "number", "description": "Quantity of units. Default is '1' unit.", "example": 1, "default": 1 }, "type": { "type": "string", "description": "Type of units. \n- 01-Price **(Default)**\n\n For Energy use the following:\n- 05-kWh\n- 07-Therm\n- 11-MCF (1000 cubic feet)\n- 12-CCF (100 cubic feet)\n- 13-Meter\n- 14-MMBTU (1 Million British Thermal Units)\n", "enum": [ "01", "05", "07", "11", "12", "13", "14" ], "example": "01", "default": "01" } } }, "taxExemptionCodes": { "$ref": "#/components/schemas/taxExemptionCodes" }, "situs": { "$ref": "#/components/schemas/situsSales" }, "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 can 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" }, "projectNumber": { "type": "string", "description": "Project number for current line item.", "maxLength": 25 }, "jobNumber": { "type": "string", "description": "Job number for current line item.", "maxLength": 25 }, "meter": { "type": "string", "description": "Meter for current line item.", "maxLength": 25 }, "salesOrderNumber": { "type": "string", "description": "Sales Order Number for current line item.", "maxLength": 25 }, "legalEntity": { "type": "string", "description": "Legal Entity for current line item.", "maxLength": 25 }, "divisionCode": { "type": "string", "description": "Division Code for current line item.", "maxLength": 25 }, "costCenter": { "type": "string", "description": "Cost Center for current line item.", "maxLength": 25 }, "glAccount": { "type": "string", "description": "GL Account for current line item.", "maxLength": 25 }, "currencyCode": { "type": "string", "description": "Currency code based on ISO 4217 standard. Must be 3 characters if provided.", "maxLength": 3 }, "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." } } } }, "situsSales": { "type": "object", "x-examples": {}, "title": "situsSales", "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 (please note: for origin-based taxation, both Ship From and Ship To addresses must be included and the Ship From must contain at least the State and postal code): \n- shipFromAddress - The location an order is shipped from.\n- shipToAddress - The location an order is shipped to.\n- orderPlacementAddress - The location an order is placed from.\n- orderApprovalAddress - The location an order is accepted from.\n\nCereTax can calculate tax using partial and complete address data. 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- **T** - Ship To\n- **V** - Ship From\n- **P** - Order Placement\n- **I** - Order Approval", "enum": [ "T", "V", "P", "I" ], "example": "T" }, "shipFromAddress": { "description": "Note: this is not required for Energy transactions", "$ref": "#/components/schemas/addressModel" }, "orderPlacementAddress": { "$ref": "#/components/schemas/addressModel" }, "orderApprovalAddress": { "$ref": "#/components/schemas/addressModel" }, "shipToAddress": { "$ref": "#/components/schemas/addressModel" } }, "required": [ "shipFromAddress", "shipToAddress" ] }, "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 } } ```