Skip to main content
PATCH
/
v0
/
plans
/
{id}
Update
curl --request PATCH \
  --url https://api.paygentic.io/v0/plans/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "defaultTaxCode": "<string>",
  "defaultTaxRate": 123,
  "description": "<string>",
  "invoiceDisplayName": "<string>",
  "name": "<string>",
  "prices": [
    "<string>"
  ],
  "renewalReminderEnabled": true,
  "renewalReminderDays": 15,
  "billingAnchor": "2023-11-07T05:31:56Z",
  "creditAllocations": [
    {
      "pricingUnitId": "<string>",
      "amount": 123,
      "recurrencePeriod": "<string>"
    }
  ]
}
'
import requests

url = "https://api.paygentic.io/v0/plans/{id}"

payload = {
    "defaultTaxCode": "<string>",
    "defaultTaxRate": 123,
    "description": "<string>",
    "invoiceDisplayName": "<string>",
    "name": "<string>",
    "prices": ["<string>"],
    "renewalReminderEnabled": True,
    "renewalReminderDays": 15,
    "billingAnchor": "2023-11-07T05:31:56Z",
    "creditAllocations": [
        {
            "pricingUnitId": "<string>",
            "amount": 123,
            "recurrencePeriod": "<string>"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    defaultTaxCode: '<string>',
    defaultTaxRate: 123,
    description: '<string>',
    invoiceDisplayName: '<string>',
    name: '<string>',
    prices: ['<string>'],
    renewalReminderEnabled: true,
    renewalReminderDays: 15,
    billingAnchor: '2023-11-07T05:31:56Z',
    creditAllocations: [{pricingUnitId: '<string>', amount: 123, recurrencePeriod: '<string>'}]
  })
};

fetch('https://api.paygentic.io/v0/plans/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.paygentic.io/v0/plans/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'defaultTaxCode' => '<string>',
    'defaultTaxRate' => 123,
    'description' => '<string>',
    'invoiceDisplayName' => '<string>',
    'name' => '<string>',
    'prices' => [
        '<string>'
    ],
    'renewalReminderEnabled' => true,
    'renewalReminderDays' => 15,
    'billingAnchor' => '2023-11-07T05:31:56Z',
    'creditAllocations' => [
        [
                'pricingUnitId' => '<string>',
                'amount' => 123,
                'recurrencePeriod' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.paygentic.io/v0/plans/{id}"

	payload := strings.NewReader("{\n  \"defaultTaxCode\": \"<string>\",\n  \"defaultTaxRate\": 123,\n  \"description\": \"<string>\",\n  \"invoiceDisplayName\": \"<string>\",\n  \"name\": \"<string>\",\n  \"prices\": [\n    \"<string>\"\n  ],\n  \"renewalReminderEnabled\": true,\n  \"renewalReminderDays\": 15,\n  \"billingAnchor\": \"2023-11-07T05:31:56Z\",\n  \"creditAllocations\": [\n    {\n      \"pricingUnitId\": \"<string>\",\n      \"amount\": 123,\n      \"recurrencePeriod\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.patch("https://api.paygentic.io/v0/plans/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"defaultTaxCode\": \"<string>\",\n  \"defaultTaxRate\": 123,\n  \"description\": \"<string>\",\n  \"invoiceDisplayName\": \"<string>\",\n  \"name\": \"<string>\",\n  \"prices\": [\n    \"<string>\"\n  ],\n  \"renewalReminderEnabled\": true,\n  \"renewalReminderDays\": 15,\n  \"billingAnchor\": \"2023-11-07T05:31:56Z\",\n  \"creditAllocations\": [\n    {\n      \"pricingUnitId\": \"<string>\",\n      \"amount\": 123,\n      \"recurrencePeriod\": \"<string>\"\n    }\n  ]\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.paygentic.io/v0/plans/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"defaultTaxCode\": \"<string>\",\n  \"defaultTaxRate\": 123,\n  \"description\": \"<string>\",\n  \"invoiceDisplayName\": \"<string>\",\n  \"name\": \"<string>\",\n  \"prices\": [\n    \"<string>\"\n  ],\n  \"renewalReminderEnabled\": true,\n  \"renewalReminderDays\": 15,\n  \"billingAnchor\": \"2023-11-07T05:31:56Z\",\n  \"creditAllocations\": [\n    {\n      \"pricingUnitId\": \"<string>\",\n      \"amount\": 123,\n      \"recurrencePeriod\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
{
  "id": "plan_f3g4h5i6j7k8l9m0",
  "object": "plan",
  "billingCadence": "P1Y",
  "billingInterval": "yearly",
  "createdAt": "2024-01-20T09:00:00Z",
  "currency": "USD",
  "defaultTaxCode": "eservice",
  "defaultTaxRate": 8.5,
  "description": "Complete machine learning infrastructure with GPU access",
  "invoiceDisplayName": "ML Platform Enterprise",
  "merchantId": "org_n1o2p3q4r5s6t7u8",
  "name": "Enterprise Solution",
  "prices": [
    "price_d7e8f9g0h1i2j3k4"
  ],
  "productId": "prod_v9w0x1y2z3a4b5c6",
  "taxBehavior": "exclusive",
  "updatedAt": "2024-03-01T15:30:00Z"
}
{
  "message": "The requested resource was not found",
  "error": "not_found"
}
{
  "message": "The requested resource was not found",
  "error": "not_found"
}
{
  "message": "The requested resource was not found",
  "error": "not_found"
}
{
  "message": "The requested resource was not found",
  "error": "not_found"
}
{
  "message": "The requested resource was not found",
  "error": "not_found"
}

Authorizations

​
Authorization
string
header
required

API key authentication

Path Parameters

​
id
string
required

The unique identifier of the plan Unique identifier for a plan

Pattern: ^plan_[a-zA-Z0-9]+$

Body

application/json
​
billingCadence
enum<string>

ISO 8601 duration for the billing period. Takes precedence over billingInterval when both are provided.

Available options:
P1M,
P3M,
P1Y
​
billingInterval
enum<string>

Recurring billing period frequency. Sample values: 'monthly' for monthly billing, 'quarterly' for quarterly billing, 'yearly' for annual billing

Available options:
monthly,
quarterly,
yearly,
annual
​
defaultTaxCode
string

Default tax code for plan line items. Common values: 'eservice' (electronically supplied services), 'saas' (software as a service), 'consulting', 'ebook', 'standard', 'reduced', 'exempt'. Full list available via GET /tax/codes endpoint.

​
defaultTaxRate
number

Fallback tax rate (as percentage) if automatic tax calculation is unavailable

​
description
string

Plan details explaining included features and limits. Sample values: 'Claude API access with 500K tokens monthly allowance', 'Unlimited cloud storage plus real-time analytics tools', 'Complete machine learning infrastructure with GPU access', 'Flexible usage-based pricing with no monthly commitment'

​
invoiceDisplayName
string

Plan name shown on billing statements. Sample values: 'LLM API Basic Plan', 'Data Warehouse Business', 'ML Platform Enterprise', 'Pay-Per-Use Model'

​
name
string

Plan identifier visible to customers. Sample values: 'Basic Tier', 'Business Package', 'Enterprise Solution', 'Metered Billing', 'Free Tier', 'Premium Access'

​
prices
string[]

Array of price IDs to associate with this plan

Unique identifier for a price

Pattern: ^price_[a-zA-Z0-9]+$
​
taxBehavior
enum<string>

Whether tax is added on top of the price (exclusive) or included in the price (inclusive)

Available options:
exclusive,
inclusive
​
renewalReminderEnabled
boolean

Whether to send renewal reminder emails to customers before their subscription renews

​
renewalReminderDays
integer

Number of days before renewal to send the reminder email

Required range: 1 <= x <= 30
​
billingAnchor
string<date-time> | null

ISO 8601 datetime reference point for billing period alignment. Must be in the past or present. Set to null to clear the anchor and revert to start-time-based anchoring.

​
creditAllocations
object[]

Credit-pool funding declarations for this plan. Each entry funds a distinct pricing unit's credit pool when a subscription to this plan activates: the allocated amount is minted as a credit grant on the customer's pool for that pricing unit, once at activation, or on a recurring basis only when that allocation explicitly sets recurrencePeriod. A plan may declare zero or more allocations; no two allocations on the same plan may target the same pricingUnitId.

Response

Plan updated successfully

​
id
string
required

Unique identifier for a plan

Pattern: ^plan_[a-zA-Z0-9]+$
​
object
enum<string>
required
Available options:
plan
​
billingCadence
enum<string>
default:P1M
required

ISO 8601 duration for the billing period.

Available options:
P1M,
P3M,
P1Y
​
billingInterval
string
required
deprecated

Deprecated. Human-readable billing period derived from billingCadence. Use billingCadence instead.

​
createdAt
string<date-time>
required
​
currency
string
required
​
merchantId
string
required

The merchant organization that owns this plan

Pattern: ^org_[a-zA-Z0-9]+$
​
name
string
required
​
productId
string
required

The product this plan belongs to

Pattern: ^prod_[a-zA-Z0-9]+$
​
updatedAt
string<date-time>
required
​
defaultTaxCode
string

Default tax code for plan line items. Common values: 'eservice' (electronically supplied services), 'saas' (software as a service), 'consulting', 'ebook', 'standard', 'reduced', 'exempt'. Full list available via GET /tax/codes endpoint.

​
defaultTaxRate
number

Fallback tax rate (as percentage) if automatic tax calculation is unavailable

​
deletedAt
string<date-time>
​
description
string
​
invoiceDisplayName
string
​
paymentTerm
object
​
prices
object[]
​
taxBehavior
enum<string>

Whether tax is added on top of the price (exclusive) or included in the price (inclusive)

Available options:
exclusive,
inclusive
​
walletNamespaceId
string

Unique identifier for a wallet namespace

​
renewalReminderEnabled
boolean

Whether renewal reminder emails are enabled for subscriptions using this plan

​
renewalReminderDays
integer

Number of days before renewal to send the reminder email

​
billingVersion
integer

Billing engine version. Managed by Paygentic support.

​
billingAnchor
string<date-time> | null

ISO 8601 datetime reference point for billing period alignment. Must be in the past or present at the time of creation or update. When set, all subscriptions created under this plan align their first billing period to the next recurrence of this anchor. Null means each subscription uses its own start time (hour-rounded) as the anchor.

​
creditAllocations
object[]

Credit-pool funding declarations for this plan. Each entry funds a distinct pricing unit's credit pool when a subscription to this plan activates: the allocated amount is minted as a credit grant on the customer's pool for that pricing unit, once at activation, or on a recurring basis only when that allocation explicitly sets recurrencePeriod. A plan may declare zero or more allocations; no two allocations on the same plan target the same pricingUnitId.