Skip to main content
POST
/
transactions
Create a transaction
curl --request POST \
  --url https://api.prod.commenda.io/api/v1/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "corporation_id": "b6d009b0-d174-463f-b030-94643c28e209",
  "transacted_at": "2023-12-25",
  "invoice_currency": "USD",
  "customer_details": {
    "customer_id": "<string>",
    "customer_external_id": "<string>"
  },
  "line_items": {
    "items": [
      {
        "amount": 123,
        "quantity": 123,
        "line_number": "<string>",
        "price_per_unit": 123,
        "discount_amount": 1,
        "tax_collected": 123,
        "tax_code": "<string>",
        "product_id": "<string>",
        "product_sku": "<string>",
        "exemption_reason": "<string>",
        "exemption_certificate_id": "<string>"
      }
    ]
  },
  "tax_date_override": "2023-12-25",
  "calculation_date_override": "2023-12-25",
  "reporting_date_override": "2023-12-25",
  "invoice_number": "<string>",
  "subtotal": 1,
  "discount": 0.99,
  "shipping_and_handling": 1,
  "total": 1,
  "tax_collected": 1,
  "calculation_id": "<string>",
  "parent_invoice_id": "<string>",
  "marketplace": "<string>",
  "tax_included": true
}
'
{
  "data": {
    "id": "9753a999-6d64-4a4f-ad9b-345890d32722",
    "corporation_id": "74df772f-9260-42cf-9c20-3b613b60fecd",
    "transacted_at": "2025-11-30",
    "created_at": 1765177896736899,
    "reporting_date_override": "2025-11-30",
    "invoice_currency": "USD",
    "subtotal": 46.15,
    "discount": 0,
    "shipping_and_handling": 0,
    "total": 48.09,
    "tax_collected": 1.94,
    "invoice_status": "LOCKED",
    "invoice_type": "SALE",
    "invoice_number": "c85100ab-7c61-4aa6-b207-c4dae0d40d13",
    "creation_method": "TRANSACTIONS_API_BULK",
    "marketplace": "<string>",
    "metadata": {},
    "customer_details": {
      "shipping_address": {
        "country": "US",
        "address_line_1": "1776 Main St",
        "address_line_2": "Apt. #123",
        "address_line_3": "<string>",
        "postal_code": "90401",
        "city": "Santa Monica",
        "state": "CA"
      },
      "customer_id": "<string>"
    },
    "line_items": {
      "items": [
        {
          "id": "aec197ca-a1fa-4669-8496-f52c82da5d3c",
          "amount": 46.15,
          "quantity": 1,
          "shipping": 0,
          "handling": 0,
          "discount": 0,
          "price_per_unit": 46.15,
          "tax_collected": 1.94,
          "tax_code": "<string>",
          "product_id": "<string>",
          "exemption_certificate_id": "00000000-0000-0000-0000-000000000000"
        }
      ]
    }
  },
  "message": "Successfully created transaction."
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
corporation_id
string
required

The unique identifier for the corporation associated with this transaction.

Example:

"b6d009b0-d174-463f-b030-94643c28e209"

​
transacted_at
string<date>
required

ISO 8601 formatted date string indicating date on which the transaction took place.

​
invoice_currency
string
required

ISO 4217 alpha-3 currency code for the transaction.

Example:

"USD"

​
transaction_type
enum<string>
required

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.
Available options:
SALE,
RETURN,
REFUND,
PURCHASE,
PURCHASE_REFUND
​
customer_details
object
required
​
line_items
object
required
​
tax_date_override
string<date>

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
string<date>

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
string<date>

ISO 8601 formatted date string indicating when this transaction should appear in reports, if different from transacted_at.

​
invoice_number
string

Invoice or receipt number for this transaction.

​
subtotal
number<float>

Total amount before tax, shipping, handling, and discounts.

Required range: x >= 0
​
discount
number<float>

Total discount amount applied to the transaction.

Required range: x >= 0
Example:

0.99

​
shipping_and_handling
number<float>

Total shipping and handling charges.

Required range: x >= 0
​
total
number<float>

This is the total amount charged to the customer, which includes the subtotal, shipping and handling fees, tax, and reflects any applied discounts.

Required range: x >= 0
​
tax_collected
number<float>

Numeric value representing the amount of sales tax paid by the customer for this transaction.

Required range: x >= 0
​
calculation_id
string

Optional ID of a previous calculation used for this transaction.

​
parent_invoice_id
string

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
enum<string>

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
Available options:
FULL,
PARTIAL
​
marketplace
string

Marketplace name if the transaction originates from a marketplace.

​
tax_remitter_type
enum<string>

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).
Available options:
SELLER,
MARKETPLACE_FACILITATOR,
BUYER
​
tax_included
boolean

Whether tax is included in the line item prices.

​
exemption_type
enum<string>

If this field is present, this transaction will be considered exempt.

Available options:
PURPOSE_RESALE,
ENTITY_TYPE_NONPROFIT,
GOVERNMENT,
MANUFACTURER,
AGRICULTURAL,
EXEMPT_PRODUCT,
OTHER,
EXEMPT_PRODUCT

Response

Transaction creation response

​
data
object
​
message
string
Example:

"Successfully created transaction."