Create Subscription Item
Create a subscription item and add it to an existing subscription for recurring payment.
To add a non-recurring charge to a subscription invoice, see Create Invoice.
This method triggers the Customer Subscription Item Created webhook. This webhook contains the same information as the response.
Note
The code samples include successful requests (200) and bad requests (400).
For error messages that appear due to bad requests (400), see:
For information about unauthorized request (401) and other authentication errors, see Troubleshooting Authentication and Authorization Errors.
Code Samples
.NET
using System; using System.Text.Json; namespace RapydApiRequestSample { class Program { static void Main(string[] args) { try { var requestObj = new { plan = "plan_dad429f5e16c41499c9c23356a5e8dea", subscription = "sub_0de9c79c1e2beee09499dc8220493d59", metadata = new { merchant_defined = true }, quantity = 1 }; string request = JsonSerializer.Serialize(requestObj); string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/subscription_items", request); Console.WriteLine(result); } catch (Exception e) { Console.WriteLine("Error completing request: " + e.Message); } } } }
JavaScript
const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest; async function main() { try { const body = { plan: 'plan_dad429f5e16c41499c9c23356a5e8dea', subscription: 'sub_0de9c79c1e2beee09499dc8220493d59', metadata: { merchant_defined: true }, quantity: 1 }; const result = await makeRequest('POST', '/v1/subscription_items', body); console.log(result); } catch (error) { console.error('Error completing request', error); } }
PHP
<?php $path = $_SERVER['DOCUMENT_ROOT']; $path .= "<path-to-your-utility-file>/utilities.php"; include($path); try { $subscription_items = [ "plan" => "plan_dad429f5e16c41499c9c23356a5e8dea", "subscription" => "sub_0de9c79c1e2beee09499dc8220493d59", "metadata" => array( "merchant_defined" => true ), "quantity" => 1 ]; $object = make_request('post', '/v1/subscription_items', $subscription_items); var_dump($object); } catch(Exception $e) { echo "Error: $e"; } ?>
Python
from pprint import pprint from utilities import make_request subscription_item = { "plan": "plan_dad429f5e16c41499c9c23356a5e8dea", "subscription": "sub_0de9c79c1e2beee09499dc8220493d59", "metadata": { "merchant_defined": True }, "quantity": 1 } result = make_request(method='post', path='/v1/subscription_items', body=subscription_item) pprint(result)
/v1/subscription_items
Create Subscription Item
curl -X post 'https://sandboxapi.rapyd.net/v1/subscription_items' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "plan": "plan_4304ce1f6d347a2204711cd2d5354fa9", "subscription": "sub_1219e2329c4c5b26f08203d826a59d92", "quantity": 1 }'{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "5a3821d6-1d92-434a-9c0c-175e39916c5b" }, "data": { "id": "subi_41e09a78ca1a10c2aedaa7d0225fe43b", "created": 1761573700, "metadata": null, "quantity": 1, "subscription_id": "sub_1219e2329c4c5b26f08203d826a59d92", "plan": { "id": "plan_4304ce1f6d347a2204711cd2d5354fa9", "aggregate_usage": "sum", "amount": 1500, "billing_scheme": "per_unit", "created_at": 1761210402, "currency": "USD", "interval": "month", "interval_count": 2, "metadata": {}, "product": { "id": "product_88fde8f1365082b50e8f4b37127edd99" }, "nickname": "Licenses", "tiers": [], "tiers_mode": "", "transform_usage": { "divide_by": 5, "round": "up" }, "trial_period_days": 0, "usage_type": "licensed", "active": true } } }
Bad Request - Subscription Not Found
curl -X post 'https://sandboxapi.rapyd.net/v1/subscription_items' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "plan": "plan_b49199dd68bfc5102171518b32208f30", "subscription": "sub_e38643c5d8d59f4ccd8ae08f8cc61c8", "quantity": 1 }'{ "status": { "error_code": "ERROR_GET_SUBSCRIPTION", "status": "ERROR", "message": "The request attempted an operation that requires a subscription, but the subscription was not found. The request was rejected. Corrective action: Use the ID of an active subscription.", "response_code": "ERROR_GET_SUBSCRIPTION", "operation_id": "47cd107e-2f7e-434d-aa62-2babd3ed8c52" } }
Bad Request - Subscription Already Contains the Plan
curl -X post 'https://sandboxapi.rapyd.net/v1/subscription_items' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "plan": "plan_b49199dd68bfc5102171518b32208f30", "subscription": "sub_e38643c5d8d59f4ccd8ae08f8cc61c8d", "quantity": 1 }'{ "status": { "error_code": "ERROR_SUBSCRIPTION_DUPLICATE_PLANS", "status": "ERROR", "message": "The request attempted an operation on a subscription that would result in duplicate plans. The request was rejected. Corrective action: In the 'subscription_items' array, ensure that each plan ID is used one time, and set 'quantity' as required.", "response_code": "ERROR_SUBSCRIPTION_DUPLICATE_PLANS", "operation_id": "17120038-bef9-41f6-8079-3bb521fe8821" } }