Transactions - ThriveStack API Reference

Create a transaction

POST https://api.app.thrivestack.ai/revenue/transactions

Authentication

Pass your API key in the x-api-key header. Your key must have the Revenue APIs scope enabled.

x-api-key: <Your API Key with Revenue APIs Scope>

Request body

Field	Type	Required	Description
`transaction_id`	string	Yes	Your unique identifier for this transaction.
`customer_id`	string	Yes	Customer ID in your billing system. Can be the same as `group_id`.
`group_id`	string	Yes	Group ID from product telemetry (links billing to product events).
`customer_name`	string	No	Display name of the customer.
`invoice_id`	string	No	ID of the associated invoice.
`type`	string	Yes	`"payment"` or `"refund"`.
`status`	string	Yes	`"paid"`, `"cancelled"`, `"failed"`, `"refund"`, or `"charged_back"`.
`transaction_date`	string	Yes	ISO 8601 timestamp when the transaction occurred.
`amount`	number	Yes	Transaction amount (e.g., `99.99`).
`currency`	string	No	ISO 4217 currency code: `"USD"`, `"EUR"`, `"GBP"`. Default: `"USD"`.
`payment_method`	string	No	`"credit_card"`, `"paypal"`, or `"stripe"`.
`transaction_fee`	number	No	Processing fee charged by the payment gateway.
`tax_amount`	number	No	Tax applied to this transaction.
`discount_amount`	number	No	Discount applied before billing.
`term_frequency`	integer	No	Number of `term_unit` intervals in the billing period. Default: `1`.
`term_unit`	string	No	`"day"`, `"week"`, `"month"`, or `"year"`. Default: `"month"`.
`period_start_date`	string	No	ISO 8601 start of the billing period.
`period_end_date`	string	No	ISO 8601 end of the billing period.
`line_item_type`	string	Yes	`"subscription"` for recurring revenue, or `"one_time"` for setup or professional charges.

Example

curl -X POST https://api.app.thrivestack.ai/revenue/transactions \
  -H "x-api-key: <Your API Key with Revenue APIs Scope>" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_123",
    "customer_id": "cust_123",
    "group_id": "group_456",
    "customer_name": "John Doe",
    "invoice_id": "inv_123",
    "type": "payment",
    "status": "paid",
    "transaction_date": "2024-01-15T14:30:00Z",
    "amount": 99.99,
    "currency": "USD",
    "payment_method": "credit_card",
    "transaction_fee": 2.99,
    "tax_amount": 5.00,
    "discount_amount": 10.00,
    "term_frequency": 1,
    "term_unit": "month",
    "period_start_date": "2024-01-01T00:00:00Z",
    "period_end_date": "2024-01-31T23:59:59Z",
    "line_item_type": "subscription"
  }'

const response = await fetch(
  'https://api.app.thrivestack.ai/revenue/transactions',
  {
    method: 'POST',
    headers: {
      'x-api-key': '<Your API Key with Revenue APIs Scope>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      transaction_id: 'txn_123',
      customer_id: 'cust_123',
      group_id: 'group_456',
      customer_name: 'John Doe',
      invoice_id: 'inv_123',
      type: 'payment',
      status: 'paid',
      transaction_date: '2024-01-15T14:30:00Z',
      amount: 99.99,
      currency: 'USD',
      payment_method: 'credit_card',
      transaction_fee: 2.99,
      tax_amount: 5.00,
      discount_amount: 10.00,
      term_frequency: 1,
      term_unit: 'month',
      period_start_date: '2024-01-01T00:00:00Z',
      period_end_date: '2024-01-31T23:59:59Z',
      line_item_type: 'subscription'
    })
  }
);
const data = await response.json();
console.log(data);

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io"
  "net/http"
)

func main() {
  payload := map[string]interface{}{
    "transaction_id":   "txn_123",
    "customer_id":      "cust_123",
    "group_id":         "group_456",
    "customer_name":    "John Doe",
    "invoice_id":       "inv_123",
    "type":             "payment",
    "status":           "paid",
    "transaction_date": "2024-01-15T14:30:00Z",
    "amount":           99.99,
    "currency":         "USD",
    "payment_method":   "credit_card",
    "transaction_fee":  2.99,
    "tax_amount":       5.00,
    "discount_amount":  10.00,
    "term_frequency":   1,
    "term_unit":        "month",
    "period_start_date": "2024-01-01T00:00:00Z",
    "period_end_date":   "2024-01-31T23:59:59Z",
    "line_item_type":   "subscription",
  }
  body, _ := json.Marshal(payload)

  req, _ := http.NewRequest("POST",
    "https://api.app.thrivestack.ai/revenue/transactions",
    bytes.NewBuffer(body))
  req.Header.Set("x-api-key", "<Your API Key with Revenue APIs Scope>")
  req.Header.Set("Content-Type", "application/json")

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer resp.Body.Close()
  result, _ := io.ReadAll(resp.Body)
  fmt.Println(string(result))
}

Response

{
  "success": true,
  "transaction_id": "txn_123"
}

Update a transaction

PUT https://api.app.thrivestack.ai/revenue/transactions

Request body

Field	Type	Required	Description
`transaction_id`	string	Yes	ID of the transaction to update.
`status`	string	No	`"paid"`, `"cancelled"`, `"failed"`, `"refund"`, or `"charged_back"`.
`type`	string	No	`"payment"` or `"refund"`.
`date`	string	No	ISO 8601 updated transaction date.
`amount`	number	No	Updated transaction amount.
`currency`	string	No	ISO 4217 currency code. Default: `"USD"`.
`payment_method`	string	No	`"credit_card"`, `"paypal"`, or `"stripe"`.
`transaction_fee`	number	No	Updated processing fee.
`tax_amount`	number	No	Updated tax amount.
`discount_amount`	number	No	Updated discount amount.
`term_frequency`	integer	No	Billing period frequency. Default: `1`.
`term_unit`	string	No	`"day"`, `"week"`, `"month"`, or `"year"`. Default: `"month"`.
`period_start_date`	string	No	ISO 8601 start of the billing period.
`period_end_date`	string	No	ISO 8601 end of the billing period.
`line_item_type`	string	No	`"subscription"` or `"one_time"`.

Example

curl -X PUT https://api.app.thrivestack.ai/revenue/transactions \
  -H "x-api-key: <Your API Key with Revenue APIs Scope>" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_123",
    "status": "paid",
    "type": "payment",
    "date": "2024-01-20T10:30:00Z",
    "amount": 149.99,
    "currency": "USD",
    "payment_method": "credit_card",
    "transaction_fee": 3.50,
    "tax_amount": 7.50,
    "discount_amount": 15.00,
    "term_frequency": 1,
    "term_unit": "month",
    "period_start_date": "2024-01-01T00:00:00Z",
    "period_end_date": "2024-01-31T23:59:59Z",
    "line_item_type": "subscription"
  }'

const response = await fetch(
  'https://api.app.thrivestack.ai/revenue/transactions',
  {
    method: 'PUT',
    headers: {
      'x-api-key': '<Your API Key with Revenue APIs Scope>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      transaction_id: 'txn_123',
      status: 'paid',
      type: 'payment',
      date: '2024-01-20T10:30:00Z',
      amount: 149.99,
      currency: 'USD',
      payment_method: 'credit_card',
      transaction_fee: 3.50,
      tax_amount: 7.50,
      discount_amount: 15.00,
      term_frequency: 1,
      term_unit: 'month',
      period_start_date: '2024-01-01T00:00:00Z',
      period_end_date: '2024-01-31T23:59:59Z',
      line_item_type: 'subscription'
    })
  }
);
const data = await response.json();
console.log(data);

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io"
  "net/http"
)

func main() {
  payload := map[string]interface{}{
    "transaction_id":   "txn_123",
    "status":           "paid",
    "type":             "payment",
    "date":             "2024-01-20T10:30:00Z",
    "amount":           149.99,
    "currency":         "USD",
    "payment_method":   "credit_card",
    "transaction_fee":  3.50,
    "tax_amount":       7.50,
    "discount_amount":  15.00,
    "term_frequency":   1,
    "term_unit":        "month",
    "period_start_date": "2024-01-01T00:00:00Z",
    "period_end_date":   "2024-01-31T23:59:59Z",
    "line_item_type":   "subscription",
  }
  body, _ := json.Marshal(payload)

  req, _ := http.NewRequest("PUT",
    "https://api.app.thrivestack.ai/revenue/transactions",
    bytes.NewBuffer(body))
  req.Header.Set("x-api-key", "<Your API Key with Revenue APIs Scope>")
  req.Header.Set("Content-Type", "application/json")

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer resp.Body.Close()
  result, _ := io.ReadAll(resp.Body)
  fmt.Println(string(result))
}

Response

{
  "success": true,
  "transaction_id": "txn_123"
}

Delete a transaction

DELETE https://api.app.thrivestack.ai/revenue/transactions

Request body

Field	Type	Required	Description
`transaction_id`	string	Yes	ID of the transaction to delete.

Example

curl -X DELETE https://api.app.thrivestack.ai/revenue/transactions \
  -H "x-api-key: <Your API Key with Revenue APIs Scope>" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_123"
  }'

const response = await fetch(
  'https://api.app.thrivestack.ai/revenue/transactions',
  {
    method: 'DELETE',
    headers: {
      'x-api-key': '<Your API Key with Revenue APIs Scope>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      transaction_id: 'txn_123'
    })
  }
);
const data = await response.json();
console.log(data);

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io"
  "net/http"
)

func main() {
  payload := map[string]string{
    "transaction_id": "txn_123",
  }
  body, _ := json.Marshal(payload)

  req, _ := http.NewRequest("DELETE",
    "https://api.app.thrivestack.ai/revenue/transactions",
    bytes.NewBuffer(body))
  req.Header.Set("x-api-key", "<Your API Key with Revenue APIs Scope>")
  req.Header.Set("Content-Type", "application/json")

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer resp.Body.Close()
  result, _ := io.ReadAll(resp.Body)
  fmt.Println(string(result))
}

Response

{
  "success": true,
  "transaction_id": "txn_123"
}

Error codes

Status	Meaning
`400`	Bad Request — invalid JSON or missing required fields
`401`	Unauthorized — invalid or missing API key, or key lacks Revenue APIs scope
`404`	Not Found — transaction ID does not exist
`429`	Rate Limit Exceeded
`500`	Server Error — try again later