--- updatedAt: 2026-07-10T20:07:17.000Z agentTools: projectIndex: https://apidocs.ceretax.net/llms.txt --- # Create purchase transaction Create a new purchase transaction in CereTax. > 📘 > > **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": { "/purchase": { "post": { "summary": "Create purchase transaction", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/purchase" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/purchaseResponse" } } } } }, "security": [ { "api_key": [] } ], "operationId": "post-purchase", "description": "Create a new purchase transaction in CereTax.", "tags": [ "Purchases" ] } } }, "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" ] } } } }, "purchase": { "title": "purchaseModel", "type": "object", "description": "", "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 ( * )" }, "configuration": { "type": "object", "required": [ "contentYear", "contentMonth", "calculationType", "profileId" ], "properties": { "status": { "type": "string", "enum": [ "Active", "Posted", "Quote", "Suspended" ], "description": "The status of this transaction. If a status is not provided, the transaction will be set to Active." }, "contentYear": { "type": "string", "example": "2023", "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" }, "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" }, "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" }, "decimals": { "type": "integer", "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.", "minimum": 2, "example": 2, "maximum": 10 }, "calculationType": { "type": "string", "description": "The type of calculation. \n- P-purchases **(Default)**\n- S-sales\n", "enum": [ "P", "S" ], "default": "P" }, "response": { "type": "string", "description": "Response value for custom response layouts." }, "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." }, "responseOptions": { "$ref": "#/components/schemas/responseOptions" } } }, "invoice": { "type": "object", "required": [ "glDate", "lineItems" ], "properties": { "apBatchNumber": { "type": "string", "description": "Companies using a Batch AP filing process will assign a batch number to a group of AP invoices - voucher, muliple AP Vouchers can exist within an AP Batch" }, "apVoucherDate": { "type": "string", "description": "Date associated with an AP Voucher within a Batch. 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." }, "apVoucherNumber": { "type": "string", "description": "Number assigned to an AP Voucher within a Batch" }, "companyName": { "type": "string", "description": "Company Description associated with company number" }, "companyNumber": { "type": "string", "description": "Company Number. Required only for multi-entity. Typically used to identify legal filing entity. Can also be used to establish corporate hierarchical structure" }, "costCenterName": { "type": "string", "description": "Cost Center Description associated with cost center number" }, "costCenterNumber": { "type": "string", "description": "Cost Center Number. Used to define various operation, administrative, manufacturing, or other functional aspects of an organization" }, "divisionName": { "type": "string", "description": "Division Description associated with division number" }, "divisionNumber": { "type": "string", "description": "Division Number. Used to establish corporate hierarchical structure. May be important in establishing operational delineations" }, "glApPaidDate": { "type": "string", "description": "The date when a vendor invoice is due for payment. 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." }, "glApPostingDate": { "type": "string", "description": "Accounting date, or date that a transaction is recognized in the company's financial statement GL accounts. 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." }, "glDate": { "type": "string", "description": "Date when a vendor invoice is received and entered to accounts payable workflow. 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." }, "invoiceTaxFlag": { "type": "string", "description": "This is a Y/N indicator, entered into the AP system that indicates that tax was charged by the vendor at the invoice level" }, "invoiceTotalAmount": { "type": "number", "description": "The total amount of a vendors invoice. Includes all line items, freight/shipping, discounts, and tax" }, "invoiceTotalDiscountAmount": { "type": "number", "description": "Separately recorded discount amount at the invoice level" }, "invoiceTotalFreightAmount": { "type": "number", "description": "Separately recorded freight amount at the invoice level. Freight represents a charge that the vendor paid for bringing product sold into the vendor's warehouse. This is distinct from shipping." }, "invoiceSalesTax": { "type": "number", "description": "Separately recorded vendor charged sales tax amount at the invoice level" }, "invoiceTotalTaxAmount": { "type": "number", "description": "Sum of total use tax and total sales tax. Typically not recorded in ERP." }, "operatingUnitName": { "type": "string", "description": "Operating Unit Number. Similar to a cost center. Could also be used to establish corporate hierarchical structure" }, "operatingUnitNumber": { "type": "string", "description": "Operating unit description associated with operating unit number" }, "poDate": { "type": "string", "description": "Date that purchase order is initiated, or opened. 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." }, "poName": { "type": "string", "description": "General description of the purchase order" }, "poNumber": { "type": "string", "description": "Unique number assigned to a purchase order" }, "totalUseTaxAmount": { "type": "number", "description": "Total Use Tax Accrued. Invoice level use tax amount. This amount would typically come from the use tax accrual in the GL. This amount would need to be associated with a specific invoice for a specific vendor. Only required when performing variance analysis for purposes other than accrual (such as refund and optimization analysis, etc.)" }, "transactionCharges": { "$ref": "#/components/schemas/transactionCharges" }, "vendorInvoiceDate": { "type": "string", "description": "Date of vendor invoice. Preferred format is YYYY-MM-DD. MM/DD/YYYY can also be used and will be converted to YYYY-MM-DD when saved." }, "vendorInvoiceNumber": { "type": "string", "description": "Unique number assigned to an invoice by a vendor" }, "vendorName": { "type": "string", "description": "Vendor Description associated with vendor number" }, "vendorNumber": { "type": "string", "description": "Unique vendor number assigned by the company or ERP" }, "vendorType": { "type": "string", "description": "Vendor Type Number. Examples may include 'Employee', 'Service', 'Material' etc." }, "vendorTypeName": { "type": "string", "description": "Description of vendor type number" }, "workOrderClassName": { "type": "string", "description": "Description of work order class number" }, "workOrderClassNumber": { "type": "string", "description": "Number or alphanumeric indicator that defines a work order class. Work Orders can often times be grouped into separate classes. A work order class can contain multiple unique work orders" }, "workOrderDate": { "type": "string", "description": "Date that a work order is initiated. 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." }, "workOrderName": { "type": "string", "description": "Short description defining what a work order is for. The nature of the work being performed under the work order" }, "workOrderNumber": { "type": "string", "description": "Number assigned to a work order" }, "workOrderTypeName": { "type": "string", "description": "Description associated with work order type" }, "workOrderTypeNumber": { "type": "string", "description": "Number or alphanumeric designation for the type of work order" }, "lineItems": { "type": "array", "description": "A list of line items associated with this transaction.", "items": { "type": "object", "description": "Tax exemption codes for this line item. Please see appendix for list of codes.", "properties": { "apBatchNumber": { "type": "string", "description": "AP Batch number, if different than invoice level value" }, "apVoucherDate": { "type": "string", "description": "Voucher Date in format YYYY-MM-DD, if different than invoice level value" }, "apVoucherNumber": { "type": "string", "description": "Voucher number, if different than invoice level value" }, "companyName": { "type": "string", "description": "Company Description associated with company number" }, "companyNumber": { "type": "string", "description": "Company Number. Typically used to identify legal filing entity. Can also be used to establish corporate hierarchical structure" }, "costCenterName": { "type": "string", "description": "Cost Center Description associated with cost center number" }, "costCenterNumber": { "type": "string", "description": "Cost Center Number. Used to define various operation, administrative, manufacturing, or other functional aspects of an organization" }, "distributionLineAmount": { "type": "number", "description": "The extended amount from the invoice line from vendors invoice" }, "distributionLineDescription": { "type": "string", "description": "Description of invoice/distribution line. From vendors invoice" }, "distributionLineDiscountAmount": { "type": "number", "description": "Separately recorded discount amount at the invoice line level - if only recorded at the invoice level, this will be allocated." }, "distributionLineFreightAmount": { "type": "number", "description": "Separately recorded freight amount at the invoice line level - if only recorded at the invoice level, this will be allocated. Freight represents a charge that the vendor paid for bringing product sold into the the vendor's warehouse. This is distinct from shipping." }, "distributionLineNumber": { "type": "string", "description": "Designation of line number on vendor's invoice or distribution line." }, "distributionLineQuantity": { "type": "integer", "description": "Used to calculate line extended amount (Quantity X Unit Amount)" }, "distributionLineTaxAmount": { "type": "number", "description": "Separately recorded vendor sales tax amount at the invoice line level - if only recorded at the invoice level, this will be allocated." }, "distributionLineTaxFlag": { "type": "string", "description": "This is a flag, or indicator, entered into the AP system that indicates that tax was charged by the vendor at the invoice/ distribution line level" }, "distributionLineTypeDescription": { "type": "string", "description": "Description associated with the invoice/distribution line type number. May not be applicable in most instances" }, "distributionLineTypeNumber": { "type": "string", "description": "Code, or indicator, defining the type of line. Examples may include 'L' for Labor, 'M' for Material, 'C' for Consumables. Etc." }, "distributionLineUnitAmount": { "type": "integer", "description": "Used to calculate line extended amount (Quantity X Unit Amount)" }, "fairMarketValue": { "type": "number", "description": "Fair market value of inventory consumed. Used only for inventory consumption scenarios, and not for standard AP invoices." }, "glAccountName": { "type": "string", "description": "General Ledger Description associated with General Ledger Number." }, "glAccountNumber": { "type": "string", "description": "General Ledger Number. Often the accounting code block may be one field which concatenates into multiples fields to be used as taxability or situsing drivers." }, "glSubAccountName": { "type": "string", "description": "General Ledger Sub-Account Description associated with GL Sub-Account Number" }, "glSubAccountNumber": { "type": "string", "description": "General Ledger Sub-Account Number. A more granular code used to further define a General Ledger Account." }, "inventoryClassName": { "type": "string", "description": "Description associated with Inventory Class Number" }, "inventoryClassNumber": { "type": "string", "description": "Number assigned to a class of inventory. Inventory systems can sometimes have a hierarchical structure. Inventory class would be one of the levels of the hierarchy" }, "inventoryItemCategoryName": { "type": "string", "description": "Description associated with an Inventory Item Category number" }, "inventoryItemCategoryNumber": { "type": "string", "description": "Number assigned to a category of inventory. Inventory systems can sometimes have a hierarchical structure. Inventory category would be one of the levels of the hierarchy" }, "inventoryItemFamilyName": { "type": "string", "description": "Description associated with an Inventory Item family number" }, "inventoryItemFamilyNumber": { "type": "string", "description": "Number assigned to a family of inventory. Inventory systems can sometimes have a hierarchical structure. Inventory family would be one of the levels of the hierarchy" }, "inventoryName": { "type": "string", "description": "Description associated with an Inventory Item" }, "inventoryNumber": { "type": "string", "description": "Number assigned to a inventory item" }, "InvoiceShipToAddress": { "type": "object", "properties": { "addressLine1": { "type": "string", "description": "Address line 1." }, "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." }, "state": { "type": "string", "description": "Address state." }, "postalCode": { "type": "string", "description": "Address postal code. Can be US or Canadian postal code values.\nCanada postal code must be uppercase, ex: S7R 1B7" }, "plus4": { "type": "string", "description": "Plus 4 extention for US addresses, if known." }, "country": { "type": "string", "description": "Address country, if known. Use three character country abbreviation." }, "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. May be used as an alternate to address value." }, "longitude": { "type": "number", "description": "Longitude of address location. May be used as an alternate to address value." }, "plusCode": { "type": "string", "description": "PlusCode of address location. May be used as an alternate to address value." }, "validateAddress": { "type": "boolean", "description": "Perform address validation \n- 0-No address validation is performed\n- 1-Perform address validation and use corrected result \n" } } }, "totalLineAmount": { "type": "number", "description": "Total purchase amount of all line components - line amount, freight/shipping, discounts, and tax" }, "orderPlacementAddress": { "type": "object", "properties": { "addressLine1": { "type": "string", "description": "Address line 1." }, "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." }, "state": { "type": "string", "description": "Address state." }, "postalCode": { "type": "string", "description": "Address postal code. Can be US or Canadian postal code values.\nCanada postal code must be uppercase, ex: S7R 1B7" }, "plus4": { "type": "string", "description": "Plus 4 extention for US addresses, if known." }, "country": { "type": "string", "description": "Address country, if known. Use three character country abbreviation." }, "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. May be used as an alternate to address value." }, "longitude": { "type": "number", "description": "Longitude of address location. May be used as an alternate to address value." }, "plusCode": { "type": "string", "description": "PlusCode of address location. May be used as an alternate to address value." }, "validateAddress": { "type": "boolean", "description": "Perform address validation \n- 0-No address validation is performed\n- 1-Perform address validation and use corrected result\n" } } }, "orderApprovalAddress": { "type": "object", "properties": { "addressLine1": { "type": "string", "description": "Address line 1." }, "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." }, "state": { "type": "string", "description": "Address state." }, "postalCode": { "type": "string", "description": "Address postal code. Can be US or Canadian postal code values.\nCanada postal code must be uppercase, ex: S7R 1B7" }, "plus4": { "type": "string", "description": "Plus 4 extention for US addresses, if known." }, "country": { "type": "string", "description": "Address country, if known. Use three character country abbreviation." }, "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. May be used as an alternate to address value." }, "longitude": { "type": "number", "description": "Longitude of address location. May be used as an alternate to address value." }, "plusCode": { "type": "string", "description": "PlusCode of address location. May be used as an alternate to address value." }, "validateAddress": { "type": "boolean", "description": "Perform address validation \n- 0-No address validation is performed\n- 1-Perform address validation and use corrected result\n" } } }, "poLineCategoryName": { "type": "string", "description": "Description associated with PO Line Category Number" }, "poLineCategoryNumber": { "type": "string", "description": "Number assigned to a PO Line Category. Purchase Order systems can sometimes have a hierarchical structure. PO Line Category would be one of the levels of the hierarchy" }, "poLineDescription": { "type": "string", "description": "Description of specific items or services being ordered on each line" }, "poLineNumber": { "type": "string", "description": "Number assigned to the PO line" }, "poLineTypeNumber": { "type": "string", "description": "Number or alphanumeric value assigned to a PO Type" }, "poShipToAddress": { "type": "object", "properties": { "addressLine1": { "type": "string", "description": "Address line 1." }, "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." }, "state": { "type": "string", "description": "Address state." }, "postalCode": { "type": "string", "description": "Address postal code. Can be US or Canadian postal code values.\nCanada postal code must be uppercase, ex: S7R 1B7" }, "plus4": { "type": "string", "description": "Plus 4 extention for US addresses, if known." }, "country": { "type": "string", "description": "Address country, if known. Use three character country abbreviation." }, "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. May be used as an alternate to address value." }, "longitude": { "type": "number", "description": "Longitude of address location. May be used as an alternate to address value." }, "plusCode": { "type": "string", "description": "PlusCode of address location. May be used as an alternate to address value." }, "validateAddress": { "type": "boolean", "description": "Perform address validation \n- 0-No address validation is performed\n- 1-Perform address validation and use corrected result\n" } } }, "shipFromAddress": { "type": "object", "properties": { "addressLine1": { "type": "string", "description": "Address line 1." }, "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." }, "state": { "type": "string", "description": "Address state." }, "postalCode": { "type": "string", "description": "Address postal code. Can be US or Canadian postal code values.\nCanada postal code must be uppercase, ex: S7R 1B7" }, "plus4": { "type": "string", "description": "Plus 4 extention for US addresses, if known." }, "country": { "type": "string", "description": "Address country, if known. Use three character country abbreviation." }, "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. May be used as an alternate to address value." }, "longitude": { "type": "number", "description": "Longitude of address location. May be used as an alternate to address value." }, "plusCode": { "type": "string", "description": "PlusCode of address location. May be used as an alternate to address value." }, "validateAddress": { "type": "boolean", "description": "Perform address validation \n- 0-No address validation is performed\n- 1-Perform address validation and use corrected result\n" } } }, "shipToAddress": { "type": "object", "properties": { "addressLine1": { "type": "string", "description": "Address line 1." }, "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." }, "state": { "type": "string", "description": "Address state." }, "postalCode": { "type": "string", "description": "Address postal code. Can be US or Canadian postal code values.\nCanada postal code must be uppercase, ex: S7R 1B7" }, "plus4": { "type": "string", "description": "Plus 4 extention for US addresses, if known." }, "country": { "type": "string", "description": "Address country, if known. Use three character country abbreviation." }, "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. May be used as an alternate to address value." }, "longitude": { "type": "number", "description": "Longitude of address location. May be used as an alternate to address value." }, "plusCode": { "type": "string", "description": "PlusCode of address location. May be used as an alternate to address value." }, "validateAddress": { "type": "boolean", "description": "Perform address validation \n- 0-No address validation is performed\n- 1-Perform address validation and use corrected result \n" } } }, "pSCode": { "type": "string", "description": "Defines the product or service for this transaction. If rules are set-up in your profile to apply a valid pSCode, one 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." }, "sellerType": { "type": "string", "description": "The type of seller for this invoice.\n- 01-Nexus **(Default)**\n" }, "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." }, "taxExemptionCodes": { "$ref": "#/components/schemas/taxExemptionCodes" }, "taxSitusRule": { "type": "string", "description": "Defines the address type to be used for tax situs.\n- T-Ship To\n- V-Ship From\n- P-Order Placement\n- I-Order Approval\n" }, "transactionCharges": { "$ref": "#/components/schemas/transactionCharges" }, "vendorAddress": { "type": "object", "description": "Invoice level Vendor Address. However Ship From Address should be used for situsing because this is typically a HQ address", "properties": { "addressLine1": { "type": "string", "description": "Address line 1." }, "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." }, "state": { "type": "string", "description": "Address state." }, "postalCode": { "type": "string", "description": "Address postal code. Can be US or Canadian postal code values.\nCanada postal code must be uppercase, ex: S7R 1B7" }, "plus4": { "type": "string", "description": "Plus 4 extention for US addresses, if known." }, "country": { "type": "string", "description": "Address country, if known. Use three character country abbreviation." }, "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. May be used as an alternate to address value." }, "longitude": { "type": "number", "description": "Longitude of address location. May be used as an alternate to address value." }, "plusCode": { "type": "string", "description": "PlusCode of address location. May be used as an alternate to address value." }, "validateAddress": { "type": "boolean", "description": "Perform address validation \n- 0-No address validation is performed\n- 1-Perform address validation and use corrected result\n" } } }, "workOrderLineDescription": { "type": "string", "description": "Description of specific Work Order line" }, "workOrderLineNumber": { "type": "string", "description": "Description of specific Work Order line number" }, "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" }, "value": { "type": "string" } } } }, "allocation": { "$ref": "#/components/schemas/allocation" }, "shippable": { "type": "boolean", "description": "Designates if an item should be used for calculating shipping taxes", "default": true } }, "required": [ "distributionLineAmount", "pSCode", "taxSitusRule" ] } } } } }, "required": [ "configuration", "invoice" ] }, "purchaseResponse": { "type": "object", "x-examples": { "example-1": { "invoice": { "calculatedInvoiceTotalTax": 0.14, "deliveryCharges": { "shipping": 0, "handling": 0, "shippingAndHandling": 0, "insurance": 0, "isMandatory": "", "freightOnBoard": "", "deliveryType": "" }, "invoiceTotalAmount": 1, "invoiceTotalDiscountAmount": 0, "invoiceTotalFreightAmount": 0, "invoiceSalesTax": 0, "invoiceTotalTaxable": 1.99, "invoiceTotalTaxAmount": 0, "invoiceTotalTaxResponse": 0, "lineItems": [ { "calculateAmt": 1.99, "calculatedEffectiveVarianceBase": -278.133333, "dateOfTransaction": "1970-01-01", "deliveryCharges": { "shipping": 0, "handling": 0, "shippingAndHandling": 0, "insurance": 0, "isMandatory": "", "freightOnBoard": "", "deliveryType": "" }, "distributionLineAmount": 1.99, "distributionLineDiscountAmount": 0, "distributionLineFreightAmount": 0, "distributionLineNumber": "1.0", "distributionLineQuantity": 0, "distributionLineTaxAmount": 10, "distributionLineUnitAmount": 0, "lineId": "1", "lineUseTaxAmount": 11, "lineItemTaxAmount": 21, "lineFreight": 0, "lineDiscount": 0, "taxes": [ { "tax": 0.09, "tierId": 0, "description": "STATE CONSUMERS USE TAX", "taxAuthorityId": 395, "taxAuthorityName": "STATE OF NORTH CAROLINA", "taxable": true, "taxLevel": "2", "taxLevelDesc": "STATE/PROVINCE", "taxType": "134", "taxTypeDesc": "CONSUMERS USE TAX", "taxTypeClass": "101", "taxTypeClassDesc": "GENERAL MERCHANDISE", "reportingCode": "", "percentTaxable": 1, "psCode": "10010100", "allocationPercent": 0, "geocode": { "geocode": "US3713500000002", "country": "USA", "county": "ORANGE", "local": "", "state": "NORTH CAROLINA", "district": "" }, "rate": 0.0475, "calculationBaseAmt": 1.99, "originalCalcBase": 1.99, "taxOnTax": 0, "allocationLabels": [], "taxTypeRef": "000", "taxTypeRefDesc": "DEFAULT", "nonTaxableAmount": 0, "exemptAmount": 0, "unitType": "01", "unitTypeDesc": "PRICE", "passThroughType": "1", "passThroughTypeDesc": "REQUIRED" }, { "tax": 0.04, "tierId": 0, "description": "COUNTY CONSUMERS USE TAX", "taxAuthorityId": 10321, "taxAuthorityName": "ORANGE COUNTY", "taxable": true, "taxLevel": "3", "taxLevelDesc": "COUNTY", "taxType": "134", "taxTypeDesc": "CONSUMERS USE TAX", "taxTypeClass": "101", "taxTypeClassDesc": "GENERAL MERCHANDISE", "reportingCode": "", "percentTaxable": 1, "psCode": "10010100", "allocationPercent": 0, "geocode": { "geocode": "US3713500000002", "country": "USA", "county": "ORANGE", "local": "", "state": "NORTH CAROLINA", "district": "" }, "rate": 0.0225, "calculationBaseAmt": 1.99, "originalCalcBase": 1.99, "taxOnTax": 0, "allocationLabels": [], "taxTypeRef": "000", "taxTypeRefDesc": "DEFAULT", "nonTaxableAmount": 0, "exemptAmount": 0, "unitType": "01", "unitTypeDesc": "PRICE", "passThroughType": "1", "passThroughTypeDesc": "REQUIRED" }, { "tax": 0.01, "tierId": 0, "description": "DISTRICT CONSUMERS USE TAX", "taxAuthorityId": 16313, "taxAuthorityName": "MECKLENBURG COUNTY TRANSIT DISTRICT", "taxable": true, "taxLevel": "5", "taxLevelDesc": "DISTRICT", "taxType": "134", "taxTypeDesc": "CONSUMERS USE TAX", "taxTypeClass": "101", "taxTypeClassDesc": "GENERAL MERCHANDISE", "reportingCode": "", "percentTaxable": 1, "psCode": "10010100", "allocationPercent": 0, "geocode": { "geocode": "US3713500000002", "country": "USA", "county": "ORANGE", "local": "", "state": "NORTH CAROLINA", "district": "" }, "rate": 0.005, "calculationBaseAmt": 1.99, "originalCalcBase": 1.99, "taxOnTax": 0, "allocationLabels": [], "taxTypeRef": "119", "taxTypeRefDesc": "TRANSIT AUTHORITY", "nonTaxableAmount": 0, "exemptAmount": 0, "unitType": "01", "unitTypeDesc": "PRICE", "passThroughType": "1", "passThroughTypeDesc": "REQUIRED" } ], "totalLineAmount": 11.99, "overUnder": -20.86, "psCode": "10010100", "quantity": 0, "lineTotalTax": 0.14, "lineTotalTaxResponse": 0, "lineTotalTaxable": 0, "validateAddresses": [], "valid": true, "errorMessages": [] } ], "totalInvoiceVariance": -20.86, "totalUseTaxAmount": 0, "vendorInvoiceDate": "2022-12-12", "vendorInvoiceNumber": "1111420880", "vendorName": "INVENTORYISSUE", "vendorNumber": "INVENTORYISSUE" }, "status": { "currentStatus": "Posted" }, "ksuid": "2KmIPIvgISFcBx1kRPObOhlORmO", "systemTraceAuditNumber": "sdfghdhgdhdhfhfgh" } }, "properties": { "invoice": { "type": "object", "properties": { "calculatedInvoiceTotalTax": { "type": "number", "description": "The total tax for all lines within this transaction" }, "transactionCharges": { "type": "object", "properties": { "shipping": { "type": "number" }, "handling": { "type": "number" }, "shippingAndHandling": { "type": "number" }, "insurance": { "type": "number" }, "miscCharge": { "type": "number" }, "isMandatory": { "type": "string" }, "freightOnBoard": { "type": "string" }, "deliveryType": { "type": "string" } } }, "invoiceTotalAmount": { "type": "number" }, "invoiceTotalDiscountAmount": { "type": "number" }, "invoiceTotalFreightAmount": { "type": "number" }, "invoiceSalesTax": { "type": "number" }, "invoiceTotalTaxable": { "type": "number" }, "invoiceTotalTaxAmount": { "type": "number" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "calculateAmt": { "type": "number" }, "calculatedEffectiveVarianceBase": { "type": "number" }, "dateOfTransaction": { "type": "string" }, "transactionCharges": { "type": "object", "properties": { "shipping": { "type": "number" }, "handling": { "type": "number" }, "shippingAndHandling": { "type": "number" }, "insurance": { "type": "number" }, "miscCharge": { "type": "number" }, "isMandatory": { "type": "string" }, "freightOnBoard": { "type": "string" }, "deliveryType": { "type": "string" } } }, "distributionLineAmount": { "type": "number" }, "distributionLineDiscountAmount": { "type": "number" }, "distributionLineFreightAmount": { "type": "number" }, "distributionLineNumber": { "type": "string" }, "distributionLineQuantity": { "type": "integer" }, "distributionLineTaxAmount": { "type": "number" }, "distributionLineUnitAmount": { "type": "integer" }, "lineId": { "type": "string", "description": "The ID of this line." }, "lineUseTaxAmount": { "type": "number" }, "lineItemTaxAmount": { "type": "number" }, "lineFreight": { "type": "number" }, "lineDiscount": { "type": "number" }, "taxes": { "type": "array", "items": { "type": "object", "properties": { "totalTax": { "type": "number", "description": "The total amount of tax calculated for this specific tax." }, "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." }, "tierId": { "type": "integer" }, "description": { "type": "string", "description": "The name of this tax" }, "taxAuthorityId": { "type": "integer", "description": "The ID of the tax authority for this tax" }, "taxAuthorityName": { "type": "string", "description": "The name of the tax authority for this tax" }, "taxAuthorityTaxId": { "type": "integer", "description": "The tax ID of the tax authority for this tax" }, "taxable": { "type": "boolean", "description": "Indicates if the specific tax was taxable or not" }, "taxLevel": { "type": "string", "description": "The tax level code for this tax" }, "taxLevelDesc": { "type": "string", "description": "The tax level description for this tax" }, "taxType": { "type": "string", "description": "The tax type code for this tax" }, "taxTypeDesc": { "type": "string", "description": "The tax type description for this tax" }, "taxTypeClass": { "type": "string", "description": "The tax type class code for this tax" }, "taxTypeClassDesc": { "type": "string", "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" }, "psCode": { "type": "string", "description": "The PS Code associated with the line" }, "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", "description": "The geocode (location) associated with this tax." }, "country": { "type": "string", "description": "The country associated with this geocode (location)" }, "county": { "type": "string", "description": "The county associated with this geocode (location)" }, "local": { "type": "string", "description": "The local jurisdiction associated with this geocode (location)" }, "state": { "type": "string", "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" }, "calculationBaseAmt": { "type": "number", "description": "The adjusted total line amount or units considered for tax. Considers any adjustments to the calculation base, like tax on tax or transaction charges." }, "originalCalcBase": { "type": "number", "description": "The unadjusted total line amount or units considered for tax." }, "taxOnTax": { "type": "number", "description": "The tax amount calculated as a result of tax on tax." }, "allocationLabels": { "type": "array", "items": { "type": "object" } }, "taxTypeRef": { "type": "string", "description": "The tax type ref code for this tax." }, "taxTypeRefDesc": { "type": "string", "description": "The tax type ref description for this tax." }, "nonTaxableAmount": { "type": "number", "description": "The line amount or units considered nontaxable for this tax." }, "exemptAmount": { "type": "number", "description": "The line amount or units considered exempt for this tax" }, "unitType": { "type": "string", "description": "The unit type code for this tax" }, "unitTypeDesc": { "type": "string", "description": "The unit type description for this tax" }, "passThroughType": { "type": "string", "description": "The pass through type code for this tax." }, "passThroughTypeDesc": { "type": "string", "description": "The pass through type description for this tax." }, "transactionChargesCalculationBaseAmtType": { "type": "number", "description": "The amount of the calculation base attributable to transaction charges." }, "transactionChargesTax": { "type": "number", "description": "The amount of tax calculated for this tax that is attributable to transaction charges." }, "taxVariance": { "type": "number", "description": "The amount of tax variance." }, "taxVarianceBase": { "type": "number", "description": "The base amount of tax variance." } } } }, "totalLineAmount": { "type": "number" }, "overUnder": { "type": "number" }, "psCode": { "type": "string" }, "quantity": { "type": "integer" }, "lineTotalTax": { "type": "number", "description": "The total tax for this line" }, "lineTotalTaxable": { "type": "number" }, "validateAddresses": { "type": "array", "items": { "type": "object" } }, "valid": { "type": "boolean" }, "errorMessages": { "type": "array", "items": { "type": "object" } } } } }, "totalInvoiceVariance": { "type": "number" }, "totalUseTaxAmount": { "type": "number" }, "vendorInvoiceDate": { "type": "string" }, "vendorInvoiceNumber": { "type": "string" }, "vendorName": { "type": "string" }, "vendorNumber": { "type": "string" } } }, "status": { "type": "object", "properties": { "currentStatus": { "type": "string", "description": "The current status of the transaction" } } }, "ksuid": { "type": "string", "description": "A unique Ceretax-generated ID for this transaction." }, "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." } } }, "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." } } } } }, "securitySchemes": { "api_key": { "type": "apiKey", "name": "x-api-key", "in": "header" } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true, "samples-enabled": true } } ```