> ## Documentation Index > Fetch the complete documentation index at: https://docs.commenda.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a transaction > Submit a completed transaction for processing and filing ## OpenAPI ````yaml POST /transactions openapi: 3.0.1 info: title: Commenda Public APIs description: >- APIs for Commenda entity management, partner incorporation, indirect tax, compliance, and corporate operations. license: name: NONE url: NONE version: 1.0.0 servers: - url: https://api.prod.commenda.io/api/v1 description: Commenda platform APIs, including Partner Incorporation and Commenda OS. - url: https://transaction-tax.api.in.commenda.io/api/v1 description: Global Indirect Tax API. security: - bearerAuth: [] paths: /transactions: post: summary: Create a transaction description: Submit a completed transaction for processing and filing operationId: submitTransaction requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateTaxTransactionRequest' responses: '200': description: Transaction creation response content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/TaxTransactionResponse' message: type: string example: Successfully created transaction. '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: CreateTaxTransactionRequest: type: object required: - corporation_id - transacted_at - invoice_currency - transaction_type - customer_details - line_items properties: corporation_id: type: string description: >- The unique identifier for the corporation associated with this transaction. example: b6d009b0-d174-463f-b030-94643c28e209 transacted_at: type: string format: date description: >- ISO 8601 formatted date string indicating date on which the transaction took place. tax_date_override: type: string format: date description: >- ISO 8601 formatted date string indicating the date on which the tax liability should be recognized for filings and for nexus tracking, if different from the `transacted_at` date. calculation_date_override: type: string format: date description: >- ISO 8601 formatted date string indicating the date to use for tax rate lookups, useful for ensuring returns use the same rates as the original sale. reporting_date_override: type: string format: date description: >- ISO 8601 formatted date string indicating when this transaction should appear in reports, if different from transacted_at. invoice_currency: $ref: '#/components/schemas/Currency' invoice_number: type: string description: Invoice or receipt number for this transaction. subtotal: type: number format: float minimum: 0 description: Total amount before tax, shipping, handling, and discounts. discount: type: number format: float minimum: 0 example: 0.99 description: Total discount amount applied to the transaction. shipping_and_handling: type: number format: float minimum: 0 description: Total shipping and handling charges. total: type: number format: float minimum: 0 description: >- This is the total amount charged to the customer, which includes the subtotal, shipping and handling fees, tax, and reflects any applied discounts. tax_collected: type: number format: float minimum: 0 description: >- Numeric value representing the amount of sales tax paid by the customer for this transaction. transaction_type: $ref: '#/components/schemas/transaction_type' description: >- Type of the transaction. Accepted values for creation: `SALE` or `PURCHASE`. - `SALE`: Standard sales transaction. - `PURCHASE`: Purchase transaction for input tax credit tracking. `RETURN`, `REFUND`, and `PURCHASE_REFUND` types are created via the refund endpoint. calculation_id: type: string description: Optional ID of a previous calculation used for this transaction. parent_invoice_id: type: string description: >- Required for RETURN transactions. The ID of the original sale transaction being returned. This links the return to the original sale for proper tax accounting. refund_type: type: string enum: - FULL - PARTIAL description: >- Required for RETURN transactions. Specifies whether this is a full or partial return. - FULL: The entire transaction amount is refunded - PARTIAL: Only specific items or amounts are refunded customer_details: type: object required: - customer_id properties: shipping_address: $ref: '#/components/schemas/Address' customer_id: type: string description: Unique identifier for the customer for this transaction. customer_external_id: type: string description: External identifier for the customer. line_items: type: object required: - items properties: items: type: array items: type: object required: - amount - quantity properties: amount: type: number format: float description: >- Total price for the line item. For SALE transactions: Typically positive, but can be negative for corrections within an invoice. For RETURN transactions: Must be negative (can be achieved through negative quantity or negative price). For PURCHASE transactions: Must be negative (same sign rules as RETURN). line_number: type: string description: >- Identifier for this line item. For RETURN transactions with line-level returns, this should match the line_number from the original invoice. quantity: type: integer description: >- Quantity of units purchased/returned. For RETURN transactions: Can be negative if used with positive price_per_unit to achieve a negative amount. price_per_unit: type: number format: float description: >- Price per unit of the product. For RETURN transactions: Can be negative if used with positive quantity to achieve a negative amount. discount_amount: type: number format: float minimum: 0 description: Discount amount applied to this line item. tax_collected: type: number format: float description: Amount of tax collected for this line item. tax_code: type: string description: The product taxability code for this line item. product_id: type: string description: >- Unique id in Commenda's system for the product being sold. Must match the `id` of a product in Commenda. No more than one of `product_id` and `product_sku` should be set. product_sku: type: string description: >- The SKU (Stock Keeping Unit) for the product. Must match the `sku` of a product in Commenda. No more than one of `product_id` and `product_sku` should be set. exemption_type: $ref: '#/components/schemas/ExemptionType' description: >- If this field is present, this line item will be considered exempt. exemption_reason: type: string description: Reason for tax exemption, if applicable. exemption_certificate_id: type: string description: ID of exemption certificate, if applicable. marketplace: type: string description: Marketplace name if the transaction originates from a marketplace. tax_remitter_type: type: string enum: - SELLER - MARKETPLACE_FACILITATOR - BUYER description: >- Indicates which party is responsible for remitting tax on the transaction. - SELLER: The seller collects and remits tax (default). - MARKETPLACE_FACILITATOR: A marketplace facilitator collects and remits tax on behalf of the seller. - BUYER: The buyer is responsible for remitting tax (reverse-charge mechanism, common in B2B VAT transactions). tax_included: type: boolean description: Whether tax is included in the line item prices. exemption_type: $ref: '#/components/schemas/ExemptionType' description: >- If this field is present, this transaction will be considered exempt. TaxTransactionResponse: type: object properties: id: type: string description: The unique identifier for a transaction. example: 9753a999-6d64-4a4f-ad9b-345890d32722 corporation_id: type: string description: >- The unique identifier for the corporation associated with this transaction. example: 74df772f-9260-42cf-9c20-3b613b60fecd transacted_at: type: string format: date description: >- ISO 8601 formatted date string indicating the date on which the transaction took place. example: '2025-11-30' created_at: type: integer format: int64 description: >- Unix timestamp in microseconds indicating when the transaction was created. example: 1765177896736899 reporting_date_override: type: string format: date description: >- ISO 8601 formatted date string indicating when this transaction should appear in reports, if different from transacted_at. example: '2025-11-30' invoice_currency: $ref: '#/components/schemas/Currency' subtotal: type: number format: float description: Total amount before tax, shipping, handling, and discounts. example: 46.15 discount: type: number format: float description: Total discount amount applied to the transaction. example: 0 shipping_and_handling: type: number format: float description: Total shipping and handling charges. example: 0 total: type: number format: float description: >- The total amount charged to the customer, which includes the subtotal, shipping and handling fees, tax, and reflects any applied discounts. example: 48.09 tax_collected: type: number format: float description: >- Numeric value representing the amount of sales tax paid by the customer for this transaction. example: 1.94 invoice_status: type: string enum: - LOCKED - UNCOMMITTED - IGNORED description: Status of the invoice/transaction. example: LOCKED invoice_type: type: string enum: - SALE - RETURN - REFUND - PURCHASE - PURCHASE_REFUND description: Type of the invoice/transaction. example: SALE invoice_number: type: string description: Invoice or receipt number for this transaction. example: c85100ab-7c61-4aa6-b207-c4dae0d40d13 creation_method: type: string description: Method used to create this transaction. example: TRANSACTIONS_API_BULK marketplace: type: string nullable: true description: Marketplace name if the transaction originates from a marketplace. tax_remitter_type: type: string nullable: true enum: - SELLER - MARKETPLACE_FACILITATOR - BUYER description: >- Indicates which party is responsible for remitting tax on the transaction. - SELLER: The seller collects and remits tax (default). - MARKETPLACE_FACILITATOR: A marketplace facilitator collects and remits tax on behalf of the seller. - BUYER: The buyer is responsible for remitting tax (reverse-charge mechanism, common in B2B VAT transactions). metadata: type: object nullable: true description: Additional metadata associated with the transaction. customer_details: type: object properties: shipping_address: $ref: '#/components/schemas/Address' customer_id: type: string description: Unique identifier for the customer for this transaction. line_items: type: object properties: items: type: array items: type: object properties: id: type: string description: Unique identifier for the line item. example: aec197ca-a1fa-4669-8496-f52c82da5d3c amount: type: number format: float description: Total price for the line item. example: 46.15 quantity: type: integer description: Quantity of units purchased. example: 1 shipping: type: number format: float description: Shipping cost for this line item. example: 0 handling: type: number format: float description: Handling cost for this line item. example: 0 discount: type: number format: float description: Discount amount applied to this line item. example: 0 price_per_unit: type: number format: float description: Price per unit of the product. example: 46.15 tax_collected: type: number format: float description: Amount of tax collected for this line item. example: 1.94 tax_code: type: string description: The product taxability code for this line item. product_id: type: string description: Unique id in Commenda's system for the product being sold. exemption_certificate_id: type: string description: ID of the exemption certificate applied to this line item. example: 00000000-0000-0000-0000-000000000000 Error: type: object required: - error properties: error: type: object properties: type: type: string description: 'Specific Error type. Example: CLIENT_INVALID_REQUEST_BODY.' example: CLIENT_INVALID_REQUEST_BODY doc_url: type: string description: >- A link to the docs with details about this error. Example: https://sales-tax-docs.commenda.io/ example: https://sales-tax-docs.commenda.io/ title: type: string description: >- A short title describing the error. Example: Missing query parameters. example: Failed to validate the request body detail: type: string description: >- A json string with a description on how to fix the error. Example {"description":"Please pass in a valid corporation_id"} status: type: number description: >- The status code. It should be the same as the HTTP protocol status code. Example: 200 example: 400 instance: type: string description: >- The relative path that was hit by the user. Example: /api/v1/corporations/1 Errors: type: array items: type: object properties: details: type: string description: More details on how to solve this particular error. pointer: type: string description: >- Relative reference to missing or invalid piece of passed information. Currency: type: string example: USD description: ISO 4217 alpha-3 currency code for the transaction. transaction_type: type: string enum: - SALE - RETURN - REFUND - PURCHASE - PURCHASE_REFUND description: >- Type of transaction: - SALE: Standard sales transaction (new sales, corrections, re-invoicing) - RETURN: Return/refund transaction (full or partial returns of previous sales) - REFUND: Legacy refund type (use RETURN instead for backward compatibility) - PURCHASE: Purchase transaction for input tax credit tracking (EU VAT, UK VAT). Line item amounts must be negative. - PURCHASE_REFUND: Auto-derived when creating a refund against a PURCHASE transaction. Cannot be set directly. Address: type: object required: - country description: > Address object. Only `country` is required at the schema level. All other field requirements (including `postal_code` and `state`) vary by country — use the `/address-requirements` endpoint to check which fields are REQUIRED, OPTIONAL, or IGNORED for a given country. When provided, postal codes and state codes are validated against country-specific formats and allowed values. properties: address_line_1: type: string example: 1776 Main St description: Primary street address. Required for some countries (e.g., US). address_line_2: type: string example: 'Apt. #123' description: >- Secondary address line (apartment, suite, etc.). Optional for most countries. address_line_3: type: string description: Tertiary address line. Ignored for most countries. postal_code: type: string description: > Postal or ZIP code. Required for many countries (e.g., US, GB, DE, FR) and optional for others (e.g., CA). Format varies by country. For US addresses, either 5-digit ZIP or 9-digit ZIP+4 is accepted. Use the `/address-requirements` endpoint to check whether this field is required and to get the validation regex for each country. example: '90401' city: type: string example: Santa Monica description: City name. Required for some countries (e.g., US). state: $ref: '#/components/schemas/State' description: > State or province code. Required for some countries (e.g., US) and optional for others (e.g., GB, DE). Must be a valid ISO 3166-2 subdivision code for the given country when provided. Use the `/address-requirements` endpoint to check whether this field is required and to get the list of valid state codes for each country. country: $ref: '#/components/schemas/Country' ExemptionType: type: string description: Reason for a sales tax exemption. enum: - PURPOSE_RESALE - ENTITY_TYPE_NONPROFIT - GOVERNMENT - MANUFACTURER - AGRICULTURAL - EXEMPT_PRODUCT - OTHER - EXEMPT_PRODUCT State: type: string example: CA description: >- 2-letter code for each state. Suffix of the ISO 3166-2 code. Ex: CA, NY, TX. Country: type: string example: US description: 'ISO 3166 2-letter country code. Ex: US, IN, GB.' securitySchemes: bearerAuth: type: http scheme: bearer ````