Subscription Items - ThriveStack API Reference

Create a subscription item

POST https://azure.dev.app.thrivestack.ai/revenue/subscription-items

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
`subscription_item_id`	string	Yes	Your unique identifier for this subscription item.
`subscription_id`	string	Yes	ID of the parent subscription this item belongs to.
`customer_id`	string	Yes	Customer ID in your billing system.
`plan_id`	string	Yes	Identifier for the plan associated with this item (e.g. `"plan_pro_monthly"`).
`price_id`	string	Yes	Identifier for the specific price variant of the plan.
`term_unit`	string	Yes	Billing interval unit: `"day"`, `"week"`, `"month"`, or `"year"`.
`term_frequency`	string	Yes	Number of `term_unit` intervals per billing cycle (e.g. `"1"` for monthly).
`start_date`	string	Yes	ISO 8601 timestamp when the subscription item started.
`status`	string	Yes	Item status: `"active"`, `"cancelled"`, or `"expired"`.
`quantity`	integer	Yes	Number of units for this line item.
`created_date`	string	No	ISO 8601 timestamp when the record was created.
`ended_at`	string	No	ISO 8601 timestamp when the item ended or is scheduled to end.
`trial_start_date`	string	No	ISO 8601 start of the trial period for this item.
`trial_end_date`	string	No	ISO 8601 end of the trial period for this item.
`cancelled_at`	string\|null	No	ISO 8601 timestamp when the item was cancelled, or `null`.
`current_period_start`	string	No	ISO 8601 start of the current billing period.
`current_period_end`	string	No	ISO 8601 end of the current billing period.
`updated_date`	string	No	ISO 8601 timestamp when the record was last updated.

Example

curl -X POST https://azure.dev.app.thrivestack.ai/revenue/subscription-items \
  -H "x-api-key: <Your API Key with Revenue APIs Scope>" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_item_id": "si_123",
    "subscription_id": "sub_123",
    "customer_id": "cust_123",
    "plan_id": "plan_pro_monthly",
    "price_id": "price_123",
    "term_unit": "month",
    "term_frequency": "1",
    "start_date": "2024-01-15T00:00:00Z",
    "status": "active",
    "quantity": 1,
    "created_date": "2024-01-15T00:00:00Z",
    "ended_at": "2025-01-15T00:00:00Z",
    "trial_start_date": "2024-01-01T00:00:00Z",
    "trial_end_date": "2024-01-14T23:59:59Z",
    "cancelled_at": null,
    "current_period_start": "2024-01-15T00:00:00Z",
    "current_period_end": "2024-02-14T23:59:59Z",
    "updated_date": "2024-01-15T00:00:00Z"
  }'

const response = await fetch(
  'https://azure.dev.app.thrivestack.ai/revenue/subscription-items',
  {
    method: 'POST',
    headers: {
      'x-api-key': '<Your API Key with Revenue APIs Scope>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subscription_item_id: 'si_123',
      subscription_id: 'sub_123',
      customer_id: 'cust_123',
      plan_id: 'plan_pro_monthly',
      price_id: 'price_123',
      term_unit: 'month',
      term_frequency: '1',
      start_date: '2024-01-15T00:00:00Z',
      status: 'active',
      quantity: 1,
      created_date: '2024-01-15T00:00:00Z',
      ended_at: '2025-01-15T00:00:00Z',
      trial_start_date: '2024-01-01T00:00:00Z',
      trial_end_date: '2024-01-14T23:59:59Z',
      cancelled_at: null,
      current_period_start: '2024-01-15T00:00:00Z',
      current_period_end: '2024-02-14T23:59:59Z',
      updated_date: '2024-01-15T00:00:00Z'
    })
  }
);
const data = await response.json();
console.log(data);

package main

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

func main() {
  payload := map[string]interface{}{
    "subscription_item_id": "si_123",
    "subscription_id":      "sub_123",
    "customer_id":          "cust_123",
    "plan_id":              "plan_pro_monthly",
    "price_id":             "price_123",
    "term_unit":            "month",
    "term_frequency":       "1",
    "start_date":           "2024-01-15T00:00:00Z",
    "status":               "active",
    "quantity":             1,
    "created_date":         "2024-01-15T00:00:00Z",
    "ended_at":             "2025-01-15T00:00:00Z",
    "trial_start_date":     "2024-01-01T00:00:00Z",
    "trial_end_date":       "2024-01-14T23:59:59Z",
    "cancelled_at":         nil,
    "current_period_start": "2024-01-15T00:00:00Z",
    "current_period_end":   "2024-02-14T23:59:59Z",
    "updated_date":         "2024-01-15T00:00:00Z",
  }
  body, _ := json.Marshal(payload)

  req, _ := http.NewRequest("POST",
    "https://azure.dev.app.thrivestack.ai/revenue/subscription-items",
    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,
  "subscription_item_id": "si_123"
}

Update a subscription item

PUT https://azure.dev.app.thrivestack.ai/revenue/subscription-items

Request body

Field	Type	Required	Description
`subscription_item_id`	string	Yes	ID of the subscription item to update.
`subscription_id`	string	No	Updated parent subscription ID.
`plan_id`	string	No	Updated plan identifier.
`price_id`	string	No	Updated price identifier (e.g. when a price change occurs).
`term_unit`	string	No	Updated billing interval unit.
`term_frequency`	string	No	Updated billing interval frequency.
`start_date`	string	No	Updated ISO 8601 start date.
`status`	string	No	Updated status: `"active"`, `"cancelled"`, or `"expired"`.
`quantity`	integer	No	Updated quantity of units.
`current_period_start`	string	No	Updated ISO 8601 start of the current billing period.
`current_period_end`	string	No	Updated ISO 8601 end of the current billing period.
`updated_date`	string	No	ISO 8601 timestamp of this update.

Example

curl -X PUT https://azure.dev.app.thrivestack.ai/revenue/subscription-items \
  -H "x-api-key: <Your API Key with Revenue APIs Scope>" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_item_id": "si_123",
    "subscription_id": "sub_123",
    "plan_id": "plan_pro_monthly",
    "price_id": "price_456",
    "term_unit": "month",
    "term_frequency": "1",
    "start_date": "2024-01-15T00:00:00Z",
    "status": "active",
    "quantity": 2,
    "current_period_start": "2024-01-15T00:00:00Z",
    "current_period_end": "2024-02-14T23:59:59Z",
    "updated_date": "2024-02-01T00:00:00Z"
  }'

const response = await fetch(
  'https://azure.dev.app.thrivestack.ai/revenue/subscription-items',
  {
    method: 'PUT',
    headers: {
      'x-api-key': '<Your API Key with Revenue APIs Scope>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subscription_item_id: 'si_123',
      subscription_id: 'sub_123',
      plan_id: 'plan_pro_monthly',
      price_id: 'price_456',
      term_unit: 'month',
      term_frequency: '1',
      start_date: '2024-01-15T00:00:00Z',
      status: 'active',
      quantity: 2,
      current_period_start: '2024-01-15T00:00:00Z',
      current_period_end: '2024-02-14T23:59:59Z',
      updated_date: '2024-02-01T00:00:00Z'
    })
  }
);
const data = await response.json();
console.log(data);

package main

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

func main() {
  payload := map[string]interface{}{
    "subscription_item_id": "si_123",
    "subscription_id":      "sub_123",
    "plan_id":              "plan_pro_monthly",
    "price_id":             "price_456",
    "term_unit":            "month",
    "term_frequency":       "1",
    "start_date":           "2024-01-15T00:00:00Z",
    "status":               "active",
    "quantity":             2,
    "current_period_start": "2024-01-15T00:00:00Z",
    "current_period_end":   "2024-02-14T23:59:59Z",
    "updated_date":         "2024-02-01T00:00:00Z",
  }
  body, _ := json.Marshal(payload)

  req, _ := http.NewRequest("PUT",
    "https://azure.dev.app.thrivestack.ai/revenue/subscription-items",
    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,
  "subscription_item_id": "si_123"
}

Delete a subscription item

DELETE https://azure.dev.app.thrivestack.ai/revenue/subscription-items

Request body

Field	Type	Required	Description
`subscription_item_id`	string	Yes	ID of the subscription item to delete.

Example

curl -X DELETE https://azure.dev.app.thrivestack.ai/revenue/subscription-items \
  -H "x-api-key: <Your API Key with Revenue APIs Scope>" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_item_id": "si_123"
  }'

const response = await fetch(
  'https://azure.dev.app.thrivestack.ai/revenue/subscription-items',
  {
    method: 'DELETE',
    headers: {
      'x-api-key': '<Your API Key with Revenue APIs Scope>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subscription_item_id: 'si_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{
    "subscription_item_id": "si_123",
  }
  body, _ := json.Marshal(payload)

  req, _ := http.NewRequest("DELETE",
    "https://azure.dev.app.thrivestack.ai/revenue/subscription-items",
    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,
  "subscription_item_id": "si_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 — subscription item ID does not exist
`429`	Rate Limit Exceeded
`500`	Server Error — try again later