Skip to main content
POST
/
transactions
Create Transaction
curl --request POST \
  --url https://api.taxwire.com/transactions \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "status": "draft",
  "currency": "USD",
  "discount_amount": "100",
  "vendor_discount_amount": "100",
  "transaction_date": "2023-11-07T05:31:56Z",
  "line_items": [
    {
      "customer": {
        "address": {
          "city": "Anytown",
          "line1": "123 Main St",
          "postal_code": "12345",
          "state": "CA"
        },
        "tax_ids": [
          {
            "country": "DE",
            "type": "eu_vat",
            "value": "DE123456789"
          }
        ]
      },
      "id": "item_123",
      "product": {
        "tax_attributes": [
          "DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED"
        ]
      },
      "quantity": "1",
      "unit_price": "100"
    }
  ],
  "parent_transaction_id": "txn_123",
  "reference_id": "INV-123",
  "parent_reference_id": "INV-123",
  "type": "sale",
  "tax_amount": "100"
}
'
{
  "id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "filing_tax_amount": "<string>",
  "filing_tax_amount_source": "provided",
  "status": "draft",
  "tax_calculation": {
    "tax_amount": "<string>",
    "line_items": [
      {
        "id": "<string>",
        "tax_amount": "<string>",
        "taxes": [
          {
            "detail": "County Transportation Fund",
            "jurisdiction_name": "<string>",
            "jurisdiction_type": "<string>",
            "tax_amount": "<string>",
            "tax_type": "<string>",
            "rule_name": "Clothing taxability rule"
          }
        ]
      }
    ],
    "currency": "USD"
  },
  "currency": "USD",
  "discount_amount": "100",
  "vendor_discount_amount": "100",
  "transaction_date": "2023-11-07T05:31:56Z",
  "line_items": [
    {
      "customer": {
        "address": {
          "city": "Anytown",
          "line1": "123 Main St",
          "postal_code": "12345",
          "state": "CA"
        },
        "tax_ids": [
          {
            "country": "DE",
            "type": "eu_vat",
            "value": "DE123456789"
          }
        ]
      },
      "id": "item_123",
      "product": {
        "tax_attributes": [
          "DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED"
        ]
      },
      "quantity": "1",
      "unit_price": "100"
    }
  ],
  "parent_transaction_id": "txn_123",
  "reference_id": "INV-123",
  "type": "sale",
  "tax_amount": "100"
}

​
Idempotency

This endpoint is idempotent. If you call it with the same reference_id, it will not create the record again.

Authorizations

​
X-API-Key
string
header
required

Body

application/json

Create transaction request model.

​
status
enum<string>
required

Status of the transaction. Draft will exist for 24hrs

Available options:
draft,
finalized,
void,
filed
Examples:

"draft"

"finalized"

"void"

"filed"

​
currency
string
default:USD

The currency of the transaction. Defaults to USD. The currency must be a valid ISO 4217 currency code.

Required string length: 3
Example:

"USD"

​
discount_amount
string | null

Amount of discount applied to the transaction. Amount is expressed in the currency of the transaction and in denominations of the smallest unit of the currency, such as cents for USD. e.g: "100" would be 100 cents or $1.00 in a USD transaction.

Example:

"100"

​
vendor_discount_amount
string | null

Amount of discount applied to the vendor in the transaction. Most of the time, you should use the discount_amount field instead. Unlike discount_amount, this discount is funded by the vendor and typically does not reduce the taxable base of the transaction. Amount is expressed in the currency of the transaction and in denominations of the smallest unit of the currency, such as cents for USD. e.g: "100" would be 100 cents or $1.00 in a USD transaction.

Example:

"100"

​
transaction_date
string<date-time>

Date and time for the tax calculation. Timezone is required for better accuracy. Use the ISO 8601 format. e.g: 2024-03-15T12:00:00Z. If not provided, the current UTC date and time will be used.

Example:

"2024-03-15T12:00:00Z"

​
line_items
LineItem · object[] | null

List of line items for an invoice or transaction. Required for sale transactions, optional for credits. A credit transaction without line_items will be assumed to be a full refund of the invoice.

Example:
[
  {
    "customer": {
      "address": {
        "city": "Anytown",
        "line1": "123 Main St",
        "postal_code": "12345",
        "state": "CA"
      },
      "tax_ids": [
        {
          "country": "DE",
          "type": "eu_vat",
          "value": "DE123456789"
        }
      ]
    },
    "id": "item_123",
    "product": {
      "tax_attributes": [
        "DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED"
      ]
    },
    "quantity": "1",
    "unit_price": "100"
  }
]
​
parent_transaction_id
string | null

Taxwire ID of the parent transaction. Used for credits on previous invoices.

Example:

"txn_123"

​
reference_id
string | null

Reference number for the transaction for your internal use.

Example:

"INV-123"

​
parent_reference_id
string | null

Reference number for the parent transaction. Used for credits on previous invoices.

Example:

"INV-123"

​
type
enum<string>
default:sale

Type of the transaction

Available options:
sale,
credit
Examples:

"sale"

"credit"

​
tax_amount
string | null

Amount of tax used in reality for the transaction. Amount is expressed in the currency of the transaction and in denominations of the smallest unit of the currency, such as cents for USD. e.g: 100 would be 100 cents or $1.00 in a USD transaction.

Example:

"100"

Response

Successful Response

Transaction response model.

​
id
string
required

Unique identifier for the transaction

Example:

"txn_123"

​
created_at
string<date-time>
required

Date at which the transaction record was created

​
updated_at
string<date-time>
required

Date at which the transaction record was last updated

​
filing_tax_amount
string
required

Amount of tax collected to be reported, filed, and remitted. Defaults to tax_amount if provided, otherwise it defaults to tax_calculation.tax_amount

Example:

"100"

​
filing_tax_amount_source
enum<string>
required

Source of the filing tax amount. Defaults to provided if a tax_amount is provided, otherwise it defaults to calculated

Available options:
provided,
calculated
Examples:

"provided"

"calculated"

​
status
enum<string>
required

Status of the transaction. Draft will exist for 24hrs

Available options:
draft,
finalized,
void,
filed
Examples:

"draft"

"finalized"

"void"

"filed"

​
tax_calculation
CreateCalculationResponse · object
required

Tax calculation for the transaction

​
currency
string
default:USD

The currency of the transaction. Defaults to USD. The currency must be a valid ISO 4217 currency code.

Required string length: 3
Example:

"USD"

​
discount_amount
string | null

Amount of discount applied to the transaction. Amount is expressed in the currency of the transaction and in denominations of the smallest unit of the currency, such as cents for USD. e.g: "100" would be 100 cents or $1.00 in a USD transaction.

Example:

"100"

​
vendor_discount_amount
string | null

Amount of discount applied to the vendor in the transaction. Most of the time, you should use the discount_amount field instead. Unlike discount_amount, this discount is funded by the vendor and typically does not reduce the taxable base of the transaction. Amount is expressed in the currency of the transaction and in denominations of the smallest unit of the currency, such as cents for USD. e.g: "100" would be 100 cents or $1.00 in a USD transaction.

Example:

"100"

​
transaction_date
string<date-time>

Date and time for the tax calculation. Timezone is required for better accuracy. Use the ISO 8601 format. e.g: 2024-03-15T12:00:00Z. If not provided, the current UTC date and time will be used.

Example:

"2024-03-15T12:00:00Z"

​
line_items
LineItem · object[] | null

List of line items for an invoice or transaction. Required for sale transactions, optional for credits. A credit transaction without line_items will be assumed to be a full refund of the invoice.

Example:
[
  {
    "customer": {
      "address": {
        "city": "Anytown",
        "line1": "123 Main St",
        "postal_code": "12345",
        "state": "CA"
      },
      "tax_ids": [
        {
          "country": "DE",
          "type": "eu_vat",
          "value": "DE123456789"
        }
      ]
    },
    "id": "item_123",
    "product": {
      "tax_attributes": [
        "DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED"
      ]
    },
    "quantity": "1",
    "unit_price": "100"
  }
]
​
parent_transaction_id
string | null

ID of the parent transaction. Used for credits on previous invoices.

Example:

"txn_123"

​
reference_id
string | null

Reference number for the transaction for your internal use.

Example:

"INV-123"

​
type
enum<string>
default:sale

Type of the transaction

Available options:
sale,
credit
Examples:

"sale"

"credit"

​
tax_amount
string | null

Amount of tax passed in the request: the amount provided. Amount is expressed in the currency of the transaction and in denominations of the smallest unit of the currency, such as cents for USD. e.g: 100 would be 100 cents or $1.00 in a USD transaction.

Example:

"100"