Transactions

A transaction is the payable record of a sale. It holds the lines, the buyer, the amounts, and the tax. Every payment collects a transaction.

Read Transactions for the model and the lifecycle. For a walkthrough, read Build a transaction.

The transaction object#

A payable record. It is the source of truth for the amount.

Attributes

idstring
accountIdstring
customerIdstringCan be absent
The customer of the transaction. Absent when the transaction has none.
externalReferencestringCan be absent
A caller-supplied reference for the transaction. Absent when there is none.
originstring
Where the transaction came from.
One of: checkout, account_manual, api
amountSourcestring
Whether the total comes from a supplied amount or from lines.
One of: amount_only, line_items
currencystring
An ISO 4217 alphabetic currency code.
Pattern ^[A-Z]{3}$.
amountsobject
The subtotal, discount, net, tax, and total of a transaction, in minor units.
Child attributes of amounts
- subtotalinteger
- discountinteger
- netinteger
- taxinteger
- totalinteger
taxStatusstring
not_applicable: no tax applies. pending: tax applies, but Merxian does not have the buyer details to calculate it. calculated: amounts.tax holds the result.
One of: not_applicable, pending, calculated
promotionCodestringCan be absent
The promotion code applied to the transaction. Absent when there is none.
authorizedAmountinteger
The amount authorized by payments, in minor units.
capturedAmountinteger
The amount captured by payments, in minor units.
refundedAmountinteger
The refunded amount, in minor units.
netCollectedAmountinteger
The captured amount less refunds, in minor units.
adjustedRequiredAmountinteger
The required amount after adjustments, in minor units.
remainingCollectibleAmountinteger
What is still collectible, in minor units.
statusstring
The state of a transaction. draft accepts changes. ready is finalized and collectible. completed and canceled are final.
One of: draft, ready, processing, completed, past_due, canceled
paymentStatusstring
The payment progress of the transaction.
One of: unpaid, pending, partially_paid, paid, partially_refunded, refunded
lineItemsarray of objects
The lines of the transaction. Empty when the transaction has none.
Child attributes of lineItems
- idstring
- namestring
  The name of the product, from the catalog.
- descriptionstringCan be absentCan be null
  The description of the product, from the catalog. Null when the product has none.
- quantityinteger
- taxBehaviorstring
  Whether the unit amount includes the tax or excludes it.
  One of: inclusive, exclusive
- unitAmountinteger
  Minor units.
- subtotalinteger
  Minor units.
- discountinteger
  Minor units.
- netinteger
  Minor units.
- taxinteger
  Minor units.
- totalinteger
  Minor units.
- productIdstringCan be absent
  The product the line resolves to.
- priceIdstringCan be absent
  The frozen catalog price.
- taxCodestringCan be absent
  The tax code applied to the line. Absent when there is none.
adjustmentsarray of objects
The adjustments of the transaction, oldest first. Empty when it has none.
Child attributes of adjustments
- idstring
- typestring
  The caller-supplied adjustment type.
- amountinteger
  The signed amount, in minor units.
- changesCollectibleAmountboolean
  True when the adjustment changes what is still collectible.
- reasonstringCan be absent
  Why the adjustment was made. Absent when there is no reason to give.
- effectiveAtstring (date-time)
- actorTypestring
  Who made the adjustment, for example account or system.
- actorIdstringCan be absent
  The ID of the actor, when there is one.
- sourceReferencestringCan be absent
  A caller-supplied reference for the adjustment. Absent when there is none.
- createdAtstring (date-time)
dueAtstring (date-time)Can be absent
When the transaction is due. Absent when it has no due date.
revisioninteger
Goes up by one each time the transaction changes. Use it with If-Match.
createdAtstring (date-time)
When the transaction was created.
updatedAtstring (date-time)
When the transaction was last updated.
metadataobject
Your own key-value pairs. Empty when the transaction has none.

The response can include fields that this page does not list. Ignore fields that you do not know.

The transaction object

{
  "id": "txn_0F8mQ2rXbT4kL9pZa",
  "accountId": "acct_5Rn8bQ2xW7mK4tLzP",
  "status": "ready",
  "currency": "EUR",
  "amountSource": "line_items",
  "amounts": {
    "subtotal": 12000,
    "discount": 0,
    "net": 12000,
    "tax": 2280,
    "total": 14280
  },
  "lineItems": [
    {
      "id": "txnitm_8QmZ3vK1pX6nT2bLw",
      "productId": "prod_5Tq8LmN2xB7vK4pRz",
      "priceId": "price_4Wm9TqLz2Xb7KdN8r",
      "name": "Team plan, annual",
      "description": null,
      "quantity": 1,
      "taxBehavior": "exclusive",
      "unitAmount": 12000,
      "subtotal": 12000,
      "discount": 0,
      "net": 12000,
      "tax": 2280,
      "total": 14280
    }
  ],
  "taxStatus": "calculated",
  "paymentStatus": "unpaid",
  "adjustedRequiredAmount": 14280,
  "remainingCollectibleAmount": 14280,
  "authorizedAmount": 0,
  "capturedAmount": 0,
  "netCollectedAmount": 0,
  "refundedAmount": 0,
  "adjustments": [],
  "customerId": "cus_2Lp7XcN4vB8mQ1tKd",
  "externalReference": "A-1042",
  "metadata": {
    "order_ref": "A-1042"
  },
  "origin": "api",
  "revision": 2,
  "createdAt": "2026-09-14T09:21:07Z",
  "updatedAt": "2026-09-14T09:21:07Z"
}

Create a transaction#

POST/v1/transactions

Creates a transaction in the draft state. Give either amount or lines, not both. A draft can change. Finalize it before you collect it.

A retry with the same Idempotency-Key and the same body returns the first result.

Requires the transactions:write scope.

Headers

Idempotency-KeystringRequired
A unique key for this request, at most 200 characters. A retry with the same key and body returns the first result.
At most 200 characters.

Request body

currencystringRequired
An ISO 4217 alphabetic currency code.
Pattern ^[A-Z]{3}$.
amountinteger
The gross amount, in minor units. Use it without lines.
linesarray of objects
The commercial lines. Use them without amount.
Child attributes of lines
- catalogPriceIdstring
  A catalog price of the account to resolve the line from.
- productIdstring
  A product of the account to resolve the line from.
- quantityintegerRequired
customerIdstring
A customer of your account. Values in buyer override the stored customer values for this transaction.
externalReferencestring
A caller-supplied reference for the transaction.
buyerobject
One-time payer evidence, frozen when no reusable customer is referenced.
Child attributes of buyer
- emailstring
- namestring
- phonestring
- vatIdstring
- customerTypestring
- countrystring
billingAddressobject
Child attributes of billingAddress
- line1stringRequired
- line2string
- postalCodestringRequired
- citystringRequired
- regionstring
- countrystringRequired
metadataobject
Your own key-value pairs. At most 50 entries. A key has at most 64 characters, a value at most 1024.
promotionCodestring
A promotion code of the account to apply.

Returns

201The transaction object.

Errors

Status	Meaning
400	The request is not valid. See the error body for the field at fault.
401	The API key is missing, malformed, revoked, or unknown.
403	The API key does not hold the scope that this operation requires.
409	The request conflicts with the current state of the resource, or the idempotency key was used with a different request.
422	The request is valid, but Merxian cannot apply it to the current data.
500	An unexpected error occurred. Retry with the same idempotency key.
502	Merxian could not complete the request. Retry with the same idempotency key.
503	Merxian could not verify the API key. Retry later.

The error reference lists the codes in each error body.

Webhook events

This call can cause these events, later and in any order:

transaction.created

POST /v1/transactions

curl -X POST "https://api.merxian.com/v1/transactions" \
  -H "Authorization: Bearer $MERXIAN_API_KEY" \
  -H "Idempotency-Key: 9b3f6c1e-2a47-4d8b-b5e0-7c1d2e3f4a5b" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "lines": [
      {
        "catalogPriceId": "price_4Wm9TqLz2Xb7KdN8r",
        "quantity": 1
      }
    ],
    "customerId": "cus_2Lp7XcN4vB8mQ1tKd",
    "billingAddress": {
      "line1": "Torstraße 1",
      "city": "Berlin",
      "postalCode": "10119",
      "country": "DE"
    },
    "externalReference": "A-1042",
    "metadata": {
      "order_ref": "A-1042"
    }
  }'

const response = await fetch('https://api.merxian.com/v1/transactions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "currency": "EUR",
    "lines": [
      {
        "catalogPriceId": "price_4Wm9TqLz2Xb7KdN8r",
        "quantity": 1
      }
    ],
    "customerId": "cus_2Lp7XcN4vB8mQ1tKd",
    "billingAddress": {
      "line1": "Torstraße 1",
      "city": "Berlin",
      "postalCode": "10119",
      "country": "DE"
    },
    "externalReference": "A-1042",
    "metadata": {
      "order_ref": "A-1042"
    }
  }),
})
const result = await response.json()

Response · 201

{
  "id": "txn_0F8mQ2rXbT4kL9pZa",
  "accountId": "acct_5Rn8bQ2xW7mK4tLzP",
  "status": "draft",
  "currency": "EUR",
  "amountSource": "line_items",
  "amounts": {
    "subtotal": 12000,
    "discount": 0,
    "net": 12000,
    "tax": 2280,
    "total": 14280
  },
  "lineItems": [
    {
      "id": "txnitm_8QmZ3vK1pX6nT2bLw",
      "productId": "prod_5Tq8LmN2xB7vK4pRz",
      "priceId": "price_4Wm9TqLz2Xb7KdN8r",
      "name": "Team plan, annual",
      "description": null,
      "quantity": 1,
      "taxBehavior": "exclusive",
      "unitAmount": 12000,
      "subtotal": 12000,
      "discount": 0,
      "net": 12000,
      "tax": 2280,
      "total": 14280
    }
  ],
  "taxStatus": "calculated",
  "paymentStatus": "unpaid",
  "adjustedRequiredAmount": 14280,
  "remainingCollectibleAmount": 14280,
  "authorizedAmount": 0,
  "capturedAmount": 0,
  "netCollectedAmount": 0,
  "refundedAmount": 0,
  "adjustments": [],
  "customerId": "cus_2Lp7XcN4vB8mQ1tKd",
  "externalReference": "A-1042",
  "metadata": {
    "order_ref": "A-1042"
  },
  "origin": "api",
  "revision": 1,
  "createdAt": "2026-09-14T09:21:07Z",
  "updatedAt": "2026-09-14T09:21:07Z"
}

Preview a transaction#

POST/v1/transactions/preview

Calculates the transaction that the same create request would make, with its amounts, discounts, and tax. It stores nothing, so it needs no Idempotency-Key.

Requires the transactions:read scope.

Request body

currencystringRequired
An ISO 4217 alphabetic currency code.
Pattern ^[A-Z]{3}$.
amountinteger
The gross amount, in minor units. Use it without lines.
linesarray of objects
The commercial lines. Use them without amount.
Child attributes of lines
- catalogPriceIdstring
  A catalog price of the account to resolve the line from.
- productIdstring
  A product of the account to resolve the line from.
- quantityintegerRequired
customerIdstring
A customer of your account. Values in buyer override the stored customer values for this transaction.
externalReferencestring
A caller-supplied reference for the transaction.
buyerobject
One-time payer evidence, frozen when no reusable customer is referenced.
Child attributes of buyer
- emailstring
- namestring
- phonestring
- vatIdstring
- customerTypestring
- countrystring
billingAddressobject
Child attributes of billingAddress
- line1stringRequired
- line2string
- postalCodestringRequired
- citystringRequired
- regionstring
- countrystringRequired
metadataobject
Your own key-value pairs. At most 50 entries. A key has at most 64 characters, a value at most 1024.
promotionCodestring
A promotion code of the account to apply.

Returns

200The transaction object.

Errors

Status	Meaning
400	The request is not valid. See the error body for the field at fault.
401	The API key is missing, malformed, revoked, or unknown.
403	The API key does not hold the scope that this operation requires.
422	The request is valid, but Merxian cannot apply it to the current data.
500	An unexpected error occurred. Retry with the same idempotency key.
502	Merxian could not complete the request. Retry with the same idempotency key.
503	Merxian could not verify the API key. Retry later.

The error reference lists the codes in each error body.

POST /v1/transactions/preview

curl -X POST "https://api.merxian.com/v1/transactions/preview" \
  -H "Authorization: Bearer $MERXIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "lines": [
      {
        "catalogPriceId": "price_4Wm9TqLz2Xb7KdN8r",
        "quantity": 1
      }
    ],
    "buyer": {
      "country": "DE"
    }
  }'

const response = await fetch('https://api.merxian.com/v1/transactions/preview', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "currency": "EUR",
    "lines": [
      {
        "catalogPriceId": "price_4Wm9TqLz2Xb7KdN8r",
        "quantity": 1
      }
    ],
    "buyer": {
      "country": "DE"
    }
  }),
})
const result = await response.json()

Response · 200

{
  "id": "txn_0F8mQ2rXbT4kL9pZa",
  "accountId": "acct_5Rn8bQ2xW7mK4tLzP",
  "status": "draft",
  "currency": "EUR",
  "amountSource": "line_items",
  "amounts": {
    "subtotal": 12000,
    "discount": 0,
    "net": 12000,
    "tax": 2280,
    "total": 14280
  },
  "lineItems": [
    {
      "id": "txnitm_8QmZ3vK1pX6nT2bLw",
      "productId": "prod_5Tq8LmN2xB7vK4pRz",
      "priceId": "price_4Wm9TqLz2Xb7KdN8r",
      "name": "Team plan, annual",
      "description": null,
      "quantity": 1,
      "taxBehavior": "exclusive",
      "unitAmount": 12000,
      "subtotal": 12000,
      "discount": 0,
      "net": 12000,
      "tax": 2280,
      "total": 14280
    }
  ],
  "taxStatus": "calculated",
  "paymentStatus": "unpaid",
  "adjustedRequiredAmount": 14280,
  "remainingCollectibleAmount": 14280,
  "authorizedAmount": 0,
  "capturedAmount": 0,
  "netCollectedAmount": 0,
  "refundedAmount": 0,
  "adjustments": [],
  "metadata": {},
  "origin": "api",
  "revision": 1,
  "createdAt": "2026-09-14T09:21:07Z",
  "updatedAt": "2026-09-14T09:21:07Z"
}

Retrieve a transaction#

GET/v1/transactions/{transactionId}

Returns one transaction. The response does not include payments. Use List the payments of a transaction to read them.

A transaction that does not exist, or that belongs to another account, returns 404.

Requires the transactions:read scope.

Path parameters

transactionIdstringRequired
The transaction id.

Returns

200The transaction object.

Errors

Status	Meaning
401	The API key is missing, malformed, revoked, or unknown.
403	The API key does not hold the scope that this operation requires.
404	The resource does not exist, or it belongs to another account.
500	An unexpected error occurred. Retry with the same idempotency key.
502	Merxian could not complete the request. Retry with the same idempotency key.
503	Merxian could not verify the API key. Retry later.

The error reference lists the codes in each error body.

GET /v1/transactions/{transactionId}

curl "https://api.merxian.com/v1/transactions/txn_0F8mQ2rXbT4kL9pZa" \
  -H "Authorization: Bearer $MERXIAN_API_KEY"

const response = await fetch('https://api.merxian.com/v1/transactions/txn_0F8mQ2rXbT4kL9pZa', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
  },
})
const result = await response.json()

Response · 200

{
  "id": "txn_0F8mQ2rXbT4kL9pZa",
  "accountId": "acct_5Rn8bQ2xW7mK4tLzP",
  "status": "draft",
  "currency": "EUR",
  "amountSource": "line_items",
  "amounts": {
    "subtotal": 12000,
    "discount": 0,
    "net": 12000,
    "tax": 2280,
    "total": 14280
  },
  "lineItems": [
    {
      "id": "txnitm_8QmZ3vK1pX6nT2bLw",
      "productId": "prod_5Tq8LmN2xB7vK4pRz",
      "priceId": "price_4Wm9TqLz2Xb7KdN8r",
      "name": "Team plan, annual",
      "description": null,
      "quantity": 1,
      "taxBehavior": "exclusive",
      "unitAmount": 12000,
      "subtotal": 12000,
      "discount": 0,
      "net": 12000,
      "tax": 2280,
      "total": 14280
    }
  ],
  "taxStatus": "calculated",
  "paymentStatus": "unpaid",
  "adjustedRequiredAmount": 14280,
  "remainingCollectibleAmount": 14280,
  "authorizedAmount": 0,
  "capturedAmount": 0,
  "netCollectedAmount": 0,
  "refundedAmount": 0,
  "adjustments": [],
  "customerId": "cus_2Lp7XcN4vB8mQ1tKd",
  "externalReference": "A-1042",
  "metadata": {
    "order_ref": "A-1042"
  },
  "origin": "api",
  "revision": 1,
  "createdAt": "2026-09-14T09:21:07Z",
  "updatedAt": "2026-09-14T09:21:07Z"
}

List transactions#

GET/v1/transactions

Returns one page of your transactions, newest first.

Requires the transactions:read scope.

Query parameters

statusstring
Keep only transactions in this state, for example draft or completed. An unknown value fails the request with 400.
One of: draft, ready, processing, completed, past_due, canceled
customerIdstring
Keep only transactions of this customer.
fromDatestring (date-time)
Keep only transactions created at or after this ISO-8601 instant.
toDatestring (date-time)
Keep only transactions created at or before this ISO-8601 instant.
limitinteger
How many transactions to return. Defaults to 20.
1 to 100. Default 20.
cursorstring
An opaque cursor taken from a previous response's pagination.nextCursor.

Returns

200A page of transaction objects, in data, with pagination.

Errors

Status	Meaning
400	The request is not valid. See the error body for the field at fault.
401	The API key is missing, malformed, revoked, or unknown.
403	The API key does not hold the scope that this operation requires.
500	An unexpected error occurred. Retry with the same idempotency key.
502	Merxian could not complete the request. Retry with the same idempotency key.
503	Merxian could not verify the API key. Retry later.

The error reference lists the codes in each error body.

GET /v1/transactions

curl "https://api.merxian.com/v1/transactions?status=completed&limit=20" \
  -H "Authorization: Bearer $MERXIAN_API_KEY"

const response = await fetch('https://api.merxian.com/v1/transactions?status=completed&limit=20', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
  },
})
const result = await response.json()

Response · 200

{
  "data": [
    {
      "id": "txn_0F8mQ2rXbT4kL9pZa",
      "accountId": "acct_5Rn8bQ2xW7mK4tLzP",
      "status": "completed",
      "currency": "EUR",
      "amountSource": "line_items",
      "amounts": {
        "subtotal": 12000,
        "discount": 0,
        "net": 12000,
        "tax": 2280,
        "total": 14280
      },
      "lineItems": [
        {
          "id": "txnitm_8QmZ3vK1pX6nT2bLw",
          "productId": "prod_5Tq8LmN2xB7vK4pRz",
          "priceId": "price_4Wm9TqLz2Xb7KdN8r",
          "name": "Team plan, annual",
          "description": null,
          "quantity": 1,
          "taxBehavior": "exclusive",
          "unitAmount": 12000,
          "subtotal": 12000,
          "discount": 0,
          "net": 12000,
          "tax": 2280,
          "total": 14280
        }
      ],
      "taxStatus": "calculated",
      "paymentStatus": "paid",
      "adjustedRequiredAmount": 14280,
      "remainingCollectibleAmount": 14280,
      "authorizedAmount": 0,
      "capturedAmount": 0,
      "netCollectedAmount": 0,
      "refundedAmount": 0,
      "adjustments": [],
      "customerId": "cus_2Lp7XcN4vB8mQ1tKd",
      "externalReference": "A-1042",
      "metadata": {
        "order_ref": "A-1042"
      },
      "origin": "api",
      "revision": 4,
      "createdAt": "2026-09-14T09:21:07Z",
      "updatedAt": "2026-09-14T09:21:07Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6InR4bl8wRjhtUTJyWGJUNGtMOXBaYSJ9"
  }
}

Update a draft transaction#

PATCH/v1/transactions/{transactionId}

Replaces the commercial content of a draft transaction. You cannot change a transaction after it is finalized.

To prevent lost updates, send the revision that you last read, in If-Match as W/"<revision>" or in expectedRevision. If the transaction changed after that revision, the request returns 409 with the code revision_conflict.

You cannot change a transaction from amount to lines, or from lines to amount.

Requires the transactions:write scope.

Path parameters

transactionIdstringRequired
The transaction id.

Headers

Idempotency-KeystringRequired
A unique key for this request, at most 200 characters. A retry with the same key and body returns the first result.
At most 200 characters.
If-Matchstring
The expected revision as an entity tag, for example W/"3".

Request body

expectedRevisioninteger
The revision the caller last saw. The update is refused when it moved on.
currencystringRequired
amountinteger
linesarray of objects
Child attributes of lines
- catalogPriceIdstring
  A catalog price of the account to resolve the line from.
- productIdstring
  A product of the account to resolve the line from.
- quantityintegerRequired
customerIdstring
A customer of your account. Values in buyer override the stored customer values for this transaction.
externalReferencestring
buyerobject
One-time payer evidence, frozen when no reusable customer is referenced.
Child attributes of buyer
- emailstring
- namestring
- phonestring
- vatIdstring
- customerTypestring
- countrystring
billingAddressobject
Child attributes of billingAddress
- line1stringRequired
- line2string
- postalCodestringRequired
- citystringRequired
- regionstring
- countrystringRequired
metadataobject
The same rules as on create.
promotionCodestring

Returns

200The transaction object.

Errors

Status	Meaning
400	The request is not valid. See the error body for the field at fault.
401	The API key is missing, malformed, revoked, or unknown.
403	The API key does not hold the scope that this operation requires.
404	The resource does not exist, or it belongs to another account.
409	The request conflicts with the current state of the resource, or the idempotency key was used with a different request.
422	The request is valid, but Merxian cannot apply it to the current data.
500	An unexpected error occurred. Retry with the same idempotency key.
502	Merxian could not complete the request. Retry with the same idempotency key.
503	Merxian could not verify the API key. Retry later.

The error reference lists the codes in each error body.

PATCH /v1/transactions/{transactionId}

curl -X PATCH "https://api.merxian.com/v1/transactions/txn_0F8mQ2rXbT4kL9pZa" \
  -H "Authorization: Bearer $MERXIAN_API_KEY" \
  -H "Idempotency-Key: 9b3f6c1e-2a47-4d8b-b5e0-7c1d2e3f4a5b" \
  -H "If-Match: W/\"1\"" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "lines": [
      {
        "catalogPriceId": "price_4Wm9TqLz2Xb7KdN8r",
        "quantity": 2
      }
    ],
    "customerId": "cus_2Lp7XcN4vB8mQ1tKd"
  }'

const response = await fetch('https://api.merxian.com/v1/transactions/txn_0F8mQ2rXbT4kL9pZa', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'If-Match': 'W/"1"',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "currency": "EUR",
    "lines": [
      {
        "catalogPriceId": "price_4Wm9TqLz2Xb7KdN8r",
        "quantity": 2
      }
    ],
    "customerId": "cus_2Lp7XcN4vB8mQ1tKd"
  }),
})
const result = await response.json()

Response · 200

{
  "id": "txn_0F8mQ2rXbT4kL9pZa",
  "accountId": "acct_5Rn8bQ2xW7mK4tLzP",
  "status": "draft",
  "currency": "EUR",
  "amountSource": "line_items",
  "amounts": {
    "subtotal": 24000,
    "discount": 0,
    "net": 24000,
    "tax": 4560,
    "total": 28560
  },
  "lineItems": [
    {
      "id": "txnitm_8QmZ3vK1pX6nT2bLw",
      "productId": "prod_5Tq8LmN2xB7vK4pRz",
      "priceId": "price_4Wm9TqLz2Xb7KdN8r",
      "name": "Team plan, annual",
      "description": null,
      "quantity": 2,
      "taxBehavior": "exclusive",
      "unitAmount": 12000,
      "subtotal": 24000,
      "discount": 0,
      "net": 24000,
      "tax": 4560,
      "total": 28560
    }
  ],
  "taxStatus": "calculated",
  "paymentStatus": "unpaid",
  "adjustedRequiredAmount": 28560,
  "remainingCollectibleAmount": 28560,
  "authorizedAmount": 0,
  "capturedAmount": 0,
  "netCollectedAmount": 0,
  "refundedAmount": 0,
  "adjustments": [],
  "customerId": "cus_2Lp7XcN4vB8mQ1tKd",
  "externalReference": "A-1042",
  "metadata": {
    "order_ref": "A-1042"
  },
  "origin": "api",
  "revision": 2,
  "createdAt": "2026-09-14T09:21:07Z",
  "updatedAt": "2026-09-14T09:21:07Z"
}

Finalize a transaction#

POST/v1/transactions/{transactionId}/finalize

Moves a draft transaction to ready. Merxian calculates the final amounts, discounts, and tax, and freezes them with the buyer and line details. After this, the payable amount does not change, except through an adjustment.

A ready transaction can be collected.

Requires the transactions:write scope.

Path parameters

transactionIdstringRequired
The transaction id.

Headers

Idempotency-KeystringRequired
A unique key for this request, at most 200 characters. A retry with the same key and body returns the first result.
At most 200 characters.

Returns

200The transaction object.

Errors

Status	Meaning
400	The request is not valid. See the error body for the field at fault.
401	The API key is missing, malformed, revoked, or unknown.
403	The API key does not hold the scope that this operation requires.
404	The resource does not exist, or it belongs to another account.
409	The request conflicts with the current state of the resource, or the idempotency key was used with a different request.
422	The request is valid, but Merxian cannot apply it to the current data.
500	An unexpected error occurred. Retry with the same idempotency key.
502	Merxian could not complete the request. Retry with the same idempotency key.
503	Merxian could not verify the API key. Retry later.

The error reference lists the codes in each error body.

Webhook events

This call can cause these events, later and in any order:

transaction.ready

POST /v1/transactions/{transactionId}/finalize

curl -X POST "https://api.merxian.com/v1/transactions/txn_0F8mQ2rXbT4kL9pZa/finalize" \
  -H "Authorization: Bearer $MERXIAN_API_KEY" \
  -H "Idempotency-Key: 9b3f6c1e-2a47-4d8b-b5e0-7c1d2e3f4a5b"

const response = await fetch('https://api.merxian.com/v1/transactions/txn_0F8mQ2rXbT4kL9pZa/finalize', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
  },
})
const result = await response.json()

Response · 200

{
  "id": "txn_0F8mQ2rXbT4kL9pZa",
  "accountId": "acct_5Rn8bQ2xW7mK4tLzP",
  "status": "ready",
  "currency": "EUR",
  "amountSource": "line_items",
  "amounts": {
    "subtotal": 12000,
    "discount": 0,
    "net": 12000,
    "tax": 2280,
    "total": 14280
  },
  "lineItems": [
    {
      "id": "txnitm_8QmZ3vK1pX6nT2bLw",
      "productId": "prod_5Tq8LmN2xB7vK4pRz",
      "priceId": "price_4Wm9TqLz2Xb7KdN8r",
      "name": "Team plan, annual",
      "description": null,
      "quantity": 1,
      "taxBehavior": "exclusive",
      "unitAmount": 12000,
      "subtotal": 12000,
      "discount": 0,
      "net": 12000,
      "tax": 2280,
      "total": 14280
    }
  ],
  "taxStatus": "calculated",
  "paymentStatus": "unpaid",
  "adjustedRequiredAmount": 14280,
  "remainingCollectibleAmount": 14280,
  "authorizedAmount": 0,
  "capturedAmount": 0,
  "netCollectedAmount": 0,
  "refundedAmount": 0,
  "adjustments": [],
  "customerId": "cus_2Lp7XcN4vB8mQ1tKd",
  "externalReference": "A-1042",
  "metadata": {
    "order_ref": "A-1042"
  },
  "origin": "api",
  "revision": 2,
  "createdAt": "2026-09-14T09:21:07Z",
  "updatedAt": "2026-09-14T09:21:07Z"
}

Cancel a transaction#

POST/v1/transactions/{transactionId}/cancel

Cancels a transaction that has not completed. A canceled transaction cannot be collected.

You cannot cancel a transaction that has collected money or that has a payment in progress. Such a request returns 409 with the code not_cancelable.

Requires the transactions:write scope.

Path parameters

transactionIdstringRequired
The transaction id.

Headers

Idempotency-KeystringRequired
A unique key for this request, at most 200 characters. A retry with the same key and body returns the first result.
At most 200 characters.

Request bodyOptional

reasonstring
Why the transaction is canceled. Absent when there is no reason to give.

Returns

200The transaction object.

Errors

Status	Meaning
400	The request is not valid. See the error body for the field at fault.
401	The API key is missing, malformed, revoked, or unknown.
403	The API key does not hold the scope that this operation requires.
404	The resource does not exist, or it belongs to another account.
409	The request conflicts with the current state of the resource, or the idempotency key was used with a different request.
500	An unexpected error occurred. Retry with the same idempotency key.
502	Merxian could not complete the request. Retry with the same idempotency key.
503	Merxian could not verify the API key. Retry later.

The error reference lists the codes in each error body.

Webhook events

This call can cause these events, later and in any order:

transaction.canceled

POST /v1/transactions/{transactionId}/cancel

curl -X POST "https://api.merxian.com/v1/transactions/txn_0F8mQ2rXbT4kL9pZa/cancel" \
  -H "Authorization: Bearer $MERXIAN_API_KEY" \
  -H "Idempotency-Key: 9b3f6c1e-2a47-4d8b-b5e0-7c1d2e3f4a5b" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "The buyer changed the order."
  }'

const response = await fetch('https://api.merxian.com/v1/transactions/txn_0F8mQ2rXbT4kL9pZa/cancel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "reason": "The buyer changed the order."
  }),
})
const result = await response.json()

Response · 200

{
  "id": "txn_0F8mQ2rXbT4kL9pZa",
  "accountId": "acct_5Rn8bQ2xW7mK4tLzP",
  "status": "canceled",
  "currency": "EUR",
  "amountSource": "line_items",
  "amounts": {
    "subtotal": 12000,
    "discount": 0,
    "net": 12000,
    "tax": 2280,
    "total": 14280
  },
  "lineItems": [
    {
      "id": "txnitm_8QmZ3vK1pX6nT2bLw",
      "productId": "prod_5Tq8LmN2xB7vK4pRz",
      "priceId": "price_4Wm9TqLz2Xb7KdN8r",
      "name": "Team plan, annual",
      "description": null,
      "quantity": 1,
      "taxBehavior": "exclusive",
      "unitAmount": 12000,
      "subtotal": 12000,
      "discount": 0,
      "net": 12000,
      "tax": 2280,
      "total": 14280
    }
  ],
  "taxStatus": "calculated",
  "paymentStatus": "unpaid",
  "adjustedRequiredAmount": 14280,
  "remainingCollectibleAmount": 14280,
  "authorizedAmount": 0,
  "capturedAmount": 0,
  "netCollectedAmount": 0,
  "refundedAmount": 0,
  "adjustments": [],
  "customerId": "cus_2Lp7XcN4vB8mQ1tKd",
  "externalReference": "A-1042",
  "metadata": {
    "order_ref": "A-1042"
  },
  "origin": "api",
  "revision": 3,
  "createdAt": "2026-09-14T09:21:07Z",
  "updatedAt": "2026-09-14T09:21:07Z"
}

Add an adjustment#

POST/v1/transactions/{transactionId}/adjustments

Records a signed adjustment on a finalized transaction. When changesCollectibleAmount is true, the adjustment changes adjustedRequiredAmount and remainingCollectibleAmount.

A draft transaction returns 409. Change a draft with Update a draft transaction instead.

Requires the transactions:write scope.

Path parameters

transactionIdstringRequired
The transaction id.

Headers

Idempotency-KeystringRequired
A unique key for this request, at most 200 characters. A retry with the same key and body returns the first result.
At most 200 characters.

Request body

typestringRequired
The adjustment type. Must not be blank.
amountMinorintegerRequired
The signed amount, in minor units.
changesCollectibleAmountbooleanRequired
True when the adjustment changes what is still collectible.
reasonstring
Why the adjustment is made.
effectiveAtstring (date-time)
When the adjustment takes effect. Absent means now.
sourceReferencestring
A caller-supplied reference for the adjustment.
correctionReasonstring
Makes the adjustment a commercial correction with a decided tax split. Absent for a plain adjustment.
One of: refund, credit_note, price_adjustment, return, bad_debt_relief, tax_classification_correction

Returns

200The transaction object.

Errors

Status	Meaning
400	The request is not valid. See the error body for the field at fault.
401	The API key is missing, malformed, revoked, or unknown.
403	The API key does not hold the scope that this operation requires.
404	The resource does not exist, or it belongs to another account.
409	The request conflicts with the current state of the resource, or the idempotency key was used with a different request.
500	An unexpected error occurred. Retry with the same idempotency key.
502	Merxian could not complete the request. Retry with the same idempotency key.
503	Merxian could not verify the API key. Retry later.

The error reference lists the codes in each error body.

Webhook events

This call can cause these events, later and in any order:

transaction.adjusted

POST /v1/transactions/{transactionId}/adjustments

curl -X POST "https://api.merxian.com/v1/transactions/txn_0F8mQ2rXbT4kL9pZa/adjustments" \
  -H "Authorization: Bearer $MERXIAN_API_KEY" \
  -H "Idempotency-Key: 9b3f6c1e-2a47-4d8b-b5e0-7c1d2e3f4a5b" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "goodwill_credit",
    "amountMinor": -2000,
    "changesCollectibleAmount": true,
    "reason": "Late delivery.",
    "sourceReference": "CASE-311"
  }'

const response = await fetch('https://api.merxian.com/v1/transactions/txn_0F8mQ2rXbT4kL9pZa/adjustments', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "type": "goodwill_credit",
    "amountMinor": -2000,
    "changesCollectibleAmount": true,
    "reason": "Late delivery.",
    "sourceReference": "CASE-311"
  }),
})
const result = await response.json()

Response · 200

{
  "id": "txn_0F8mQ2rXbT4kL9pZa",
  "accountId": "acct_5Rn8bQ2xW7mK4tLzP",
  "status": "ready",
  "currency": "EUR",
  "amountSource": "line_items",
  "amounts": {
    "subtotal": 12000,
    "discount": 0,
    "net": 12000,
    "tax": 2280,
    "total": 14280
  },
  "lineItems": [
    {
      "id": "txnitm_8QmZ3vK1pX6nT2bLw",
      "productId": "prod_5Tq8LmN2xB7vK4pRz",
      "priceId": "price_4Wm9TqLz2Xb7KdN8r",
      "name": "Team plan, annual",
      "description": null,
      "quantity": 1,
      "taxBehavior": "exclusive",
      "unitAmount": 12000,
      "subtotal": 12000,
      "discount": 0,
      "net": 12000,
      "tax": 2280,
      "total": 14280
    }
  ],
  "taxStatus": "calculated",
  "paymentStatus": "unpaid",
  "adjustedRequiredAmount": 12280,
  "remainingCollectibleAmount": 12280,
  "authorizedAmount": 0,
  "capturedAmount": 0,
  "netCollectedAmount": 0,
  "refundedAmount": 0,
  "adjustments": [
    {
      "id": "adj_3Pq8WmK2vN7xL4tRb",
      "type": "goodwill_credit",
      "amount": -2000,
      "changesCollectibleAmount": true,
      "reason": "Late delivery.",
      "sourceReference": "CASE-311",
      "actorType": "account",
      "createdAt": "2026-09-14T10:02:00Z",
      "effectiveAt": "2026-09-14T10:02:00Z"
    }
  ],
  "customerId": "cus_2Lp7XcN4vB8mQ1tKd",
  "externalReference": "A-1042",
  "metadata": {
    "order_ref": "A-1042"
  },
  "origin": "api",
  "revision": 3,
  "createdAt": "2026-09-14T09:21:07Z",
  "updatedAt": "2026-09-14T09:21:07Z"
}