Transactions

Transactions

Record transactions for compliance reporting and audit trails.

Create Transaction

POST /v1/transactions

curl -X POST https://api.shipvat.com/v1/transactions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "order_12345",
    "customer": {
      "address": {
        "country": "DE",
        "postal_code": "10115"
      }
    },
    "line_items": [
      {
        "amount": 9999,
        "quantity": 1,
        "product_type": "saas",
        "description": "Pro Plan",
        "taxable": true,
        "tax_rate": 0.19,
        "tax_amount": 1900
      }
    ],
    "currency": "USD",
    "jurisdiction_id": "DE",
    "seller_registered": true
  }'

Response

{
  "id": "txn_abc123",
  "external_id": "order_12345",
  "customer": {
    "address": {
      "country": "DE",
      "region": null,
      "postal_code": "10115"
    }
  },
  "line_items": [
    {
      "id": "li_xyz789",
      "amount": 9999,
      "quantity": 1,
      "product_type": "saas",
      "description": "Pro Plan",
      "taxable": true,
      "tax_rate": 0.19,
      "tax_amount": 1900,
      "taxability_reason": null
    }
  ],
  "subtotal": 9999,
  "tax_amount": 1900,
  "total": 11899,
  "currency": "USD",
  "tax_rate": 0.19,
  "jurisdiction_id": "DE",
  "seller_registered": true,
  "status": "completed",
  "transaction_date": "2024-01-15T10:30:00Z",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

List Transactions

GET /v1/transactions

Query Parameters

Parameter	Type	Description
limit	number	Results per page (default: 50, max: 100)
offset	number	Pagination offset
from_date	string	Start date (YYYY-MM-DD)
to_date	string	End date (YYYY-MM-DD)
jurisdiction_id	string	Filter by jurisdiction
status	string	Filter by status: pending, completed, refunded, voided

curl "https://api.shipvat.com/v1/transactions?from_date=2024-01-01&to_date=2024-01-31&limit=20" \
  -H "Authorization: Bearer sk_live_..."

Get Transaction

GET /v1/transactions/:id

curl https://api.shipvat.com/v1/transactions/txn_abc123 \
  -H "Authorization: Bearer sk_live_..."

Get Transaction by External ID

Retrieve a transaction using your external reference ID (e.g., your order ID).

GET /v1/transactions/external/:externalId

curl https://api.shipvat.com/v1/transactions/external/order_12345 \
  -H "Authorization: Bearer sk_live_..."

Refund Transaction

POST /v1/transactions/:id/refund

curl -X POST https://api.shipvat.com/v1/transactions/txn_abc123/refund \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "reason": "Customer requested partial refund"
  }'

Response

{
  "id": "txn_abc123",
  "status": "refunded",
  "refund": {
    "refunded_at": "2024-01-16T14:00:00Z",
    "amount": 5000,
    "reason": "Customer requested partial refund"
  }
}

Void Transaction

Void a pending transaction. Only transactions with pending status can be voided.

POST /v1/transactions/:id/void

curl -X POST https://api.shipvat.com/v1/transactions/txn_abc123/void \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "id": "txn_abc123",
  "status": "voided",
  "voided_at": "2024-01-16T14:00:00Z"
}

Batch Create Transactions

POST /v1/transactions/batch

Create up to 50 transactions in a single request.

curl -X POST https://api.shipvat.com/v1/transactions/batch \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "transactions": [
      {
        "external_id": "order_001",
        "customer": { "address": { "country": "DE" } },
        "line_items": [{ "amount": 1000, "quantity": 1, "product_type": "saas", "taxable": true, "tax_rate": 0.19, "tax_amount": 190 }],
        "currency": "EUR",
        "jurisdiction_id": "DE",
        "seller_registered": true
      },
      {
        "external_id": "order_002",
        "customer": { "address": { "country": "FR" } },
        "line_items": [{ "amount": 2000, "quantity": 1, "product_type": "saas", "taxable": true, "tax_rate": 0.20, "tax_amount": 400 }],
        "currency": "EUR",
        "jurisdiction_id": "FR",
        "seller_registered": true
      }
    ]
  }'

Response

{
  "results": [
    { "index": 0, "success": true, "data": { "id": "txn_001", ... } },
    { "index": 1, "success": true, "data": { "id": "txn_002", ... } }
  ],
  "summary": {
    "total": 2,
    "succeeded": 2,
    "failed": 0
  }
}

Transaction Status

Status	Description
pending	Transaction created but not finalized
completed	Transaction completed
refunded	Fully or partially refunded
voided	Transaction cancelled