cURL
curl --request POST \
--url https://api.tirdad.ai/v1/subscriptions/{id}/change/preview \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"billing_cadence": "RECURRING",
"target_plan_id": "<string>",
"billing_period_count": 123,
"metadata": {}
}
'from tirdad_sdk import Tirdad
with Tirdad(
api_key_auth="<YOUR_API_KEY_HERE>",
) as f_client:
res = f_client.subscriptions.preview_subscription_change(id="<id>", billing_cadence="RECURRING", billing_cycle="anniversary", billing_period="ONETIME", proration_behavior="none", target_plan_id="<id>")
# Handle response
print(res)import { Tirdad } from "@tirdad/sdk";
const tirdad = new Tirdad({
apiKeyAuth: "<YOUR_API_KEY_HERE>",
});
async function run() {
const result = await tirdad.subscriptions.previewSubscriptionChange("<id>", {
billingCadence: "RECURRING",
billingCycle: "anniversary",
billingPeriod: "ONETIME",
prorationBehavior: "none",
targetPlanId: "<id>",
});
console.log(result);
}
run();package main
import(
"context"
tirdad "github.com/tirdad-billing/go-sdk/v2"
"github.com/tirdad-billing/go-sdk/v2/models/types"
"log"
)
func main() {
ctx := context.Background()
s := tirdad.New(
tirdad.WithSecurity("<YOUR_API_KEY_HERE>"),
)
res, err := s.Subscriptions.PreviewSubscriptionChange(ctx, "<id>", types.SubscriptionChangeRequest{
BillingCadence: types.BillingCadenceRecurring,
BillingCycle: types.BillingCycleAnniversary,
BillingPeriod: types.BillingPeriodOnetime,
ProrationBehavior: types.ProrationBehaviorNone,
TargetPlanID: "<id>",
})
if err != nil {
log.Fatal(err)
}
if res.SubscriptionChangePreviewResponse != nil {
// handle response
}
}{
"change_type": "upgrade",
"current_plan": {
"description": "<string>",
"id": "<string>",
"lookup_key": "<string>",
"name": "<string>"
},
"effective_date": "2023-11-07T05:31:56Z",
"metadata": {},
"new_billing_cycle": {
"billing_anchor": "2023-11-07T05:31:56Z",
"billing_cadence": "RECURRING",
"billing_period": "MONTHLY",
"billing_period_count": 123,
"period_end": "2023-11-07T05:31:56Z",
"period_start": "2023-11-07T05:31:56Z"
},
"next_invoice_preview": {
"currency": "<string>",
"due_date": "2023-11-07T05:31:56Z",
"line_items": [
{
"amount": "<string>",
"description": "<string>",
"is_proration": true,
"period_end": "2023-11-07T05:31:56Z",
"period_start": "2023-11-07T05:31:56Z",
"quantity": "<string>",
"unit_price": "<string>"
}
],
"subtotal": "<string>",
"tax_amount": "<string>",
"total": "<string>"
},
"proration_details": {
"charge_amount": "<string>",
"charge_description": "<string>",
"credit_amount": "<string>",
"credit_description": "<string>",
"currency": "<string>",
"current_period_end": "2023-11-07T05:31:56Z",
"current_period_start": "2023-11-07T05:31:56Z",
"days_remaining": 123,
"days_used": 123,
"net_amount": "<string>",
"proration_date": "2023-11-07T05:31:56Z"
},
"subscription_id": "<string>",
"target_plan": {
"description": "<string>",
"id": "<string>",
"lookup_key": "<string>",
"name": "<string>"
},
"warnings": [
"<string>"
]
}{
"code": "http_client_error",
"http_status_code": 123,
"message": "<string>"
}{
"code": "http_client_error",
"http_status_code": 123,
"message": "<string>"
}{
"code": "http_client_error",
"http_status_code": 123,
"message": "<string>"
}Subscriptions
Preview subscription plan change
Use when showing a customer the cost of a plan change before they confirm (e.g. upgrade/downgrade preview with proration).
POST
/
subscriptions
/
{id}
/
change
/
preview
cURL
curl --request POST \
--url https://api.tirdad.ai/v1/subscriptions/{id}/change/preview \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"billing_cadence": "RECURRING",
"target_plan_id": "<string>",
"billing_period_count": 123,
"metadata": {}
}
'from tirdad_sdk import Tirdad
with Tirdad(
api_key_auth="<YOUR_API_KEY_HERE>",
) as f_client:
res = f_client.subscriptions.preview_subscription_change(id="<id>", billing_cadence="RECURRING", billing_cycle="anniversary", billing_period="ONETIME", proration_behavior="none", target_plan_id="<id>")
# Handle response
print(res)import { Tirdad } from "@tirdad/sdk";
const tirdad = new Tirdad({
apiKeyAuth: "<YOUR_API_KEY_HERE>",
});
async function run() {
const result = await tirdad.subscriptions.previewSubscriptionChange("<id>", {
billingCadence: "RECURRING",
billingCycle: "anniversary",
billingPeriod: "ONETIME",
prorationBehavior: "none",
targetPlanId: "<id>",
});
console.log(result);
}
run();package main
import(
"context"
tirdad "github.com/tirdad-billing/go-sdk/v2"
"github.com/tirdad-billing/go-sdk/v2/models/types"
"log"
)
func main() {
ctx := context.Background()
s := tirdad.New(
tirdad.WithSecurity("<YOUR_API_KEY_HERE>"),
)
res, err := s.Subscriptions.PreviewSubscriptionChange(ctx, "<id>", types.SubscriptionChangeRequest{
BillingCadence: types.BillingCadenceRecurring,
BillingCycle: types.BillingCycleAnniversary,
BillingPeriod: types.BillingPeriodOnetime,
ProrationBehavior: types.ProrationBehaviorNone,
TargetPlanID: "<id>",
})
if err != nil {
log.Fatal(err)
}
if res.SubscriptionChangePreviewResponse != nil {
// handle response
}
}{
"change_type": "upgrade",
"current_plan": {
"description": "<string>",
"id": "<string>",
"lookup_key": "<string>",
"name": "<string>"
},
"effective_date": "2023-11-07T05:31:56Z",
"metadata": {},
"new_billing_cycle": {
"billing_anchor": "2023-11-07T05:31:56Z",
"billing_cadence": "RECURRING",
"billing_period": "MONTHLY",
"billing_period_count": 123,
"period_end": "2023-11-07T05:31:56Z",
"period_start": "2023-11-07T05:31:56Z"
},
"next_invoice_preview": {
"currency": "<string>",
"due_date": "2023-11-07T05:31:56Z",
"line_items": [
{
"amount": "<string>",
"description": "<string>",
"is_proration": true,
"period_end": "2023-11-07T05:31:56Z",
"period_start": "2023-11-07T05:31:56Z",
"quantity": "<string>",
"unit_price": "<string>"
}
],
"subtotal": "<string>",
"tax_amount": "<string>",
"total": "<string>"
},
"proration_details": {
"charge_amount": "<string>",
"charge_description": "<string>",
"credit_amount": "<string>",
"credit_description": "<string>",
"currency": "<string>",
"current_period_end": "2023-11-07T05:31:56Z",
"current_period_start": "2023-11-07T05:31:56Z",
"days_remaining": 123,
"days_used": 123,
"net_amount": "<string>",
"proration_date": "2023-11-07T05:31:56Z"
},
"subscription_id": "<string>",
"target_plan": {
"description": "<string>",
"id": "<string>",
"lookup_key": "<string>",
"name": "<string>"
},
"warnings": [
"<string>"
]
}{
"code": "http_client_error",
"http_status_code": 123,
"message": "<string>"
}{
"code": "http_client_error",
"http_status_code": 123,
"message": "<string>"
}{
"code": "http_client_error",
"http_status_code": 123,
"message": "<string>"
}Body
application/json
Subscription change preview request
Request object for changing a subscription plan (upgrade/downgrade)
Response
OK
Response showing the financial impact of a subscription plan change