--- title: "Create Subscription Item" source_url: https://docs.rapyd.net/en/create-subscription-item.html lang: en --- # 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](https://docs.rapyd.net/en/create-invoice.md "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: > > - [General Errors](https://docs.rapyd.net/en/general-errors.md "General Errors") > - [Subscription Item Errors](https://docs.rapyd.net/en/subscription-item-errors.md "Subscription Item Errors") > - For information about unauthorized request (401) and other authentication errors, see [Troubleshooting Authentication and Authorization Errors](https://docs.rapyd.net/en/troubleshooting-authentication-and-authorization-errors.md "Troubleshooting Authentication and Authorization Errors"). ### Parameters ### Request Header Parameters - - access_key - Unique access key provided by Rapyd for each authorized user. See [Developers](https://docs.rapyd.net/en/developers.md "Developers"). - - Content-Type - Indicates that the data appears in JSON format. Set to **application/json**. - - idempotency - A unique key that prevents the platform from creating the same object twice. See [Idempotency](https://docs.rapyd.net/en/idempotency.md "Idempotency"). - - salt - Random string. Recommended length: 8-16 characters. - - signature - Signature calculated for each request individually. See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures"). - - timestamp - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds). ### Request Body Parameters - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - plan - ID of the pricing plan that defines the product and pricing structure associated with this subscription item. The plan must be active. String starting with **plan_**. Cannot be a plan that is already part of the subscription. - - prorate - Determines whether the charge is prorated when a subscription item is switched from one subscription to another in a billing cycle. - - proration_date - Determines the date in the middle of the billing period that is the start of the prorated charges. The other end is determined by the `period_start` or `period_end` of the invoice. If the subscription and its subscription item have different proration dates, the proration takes place on the earlier of the two dates. Relevant to the first and last billing cycles. - - quantity - The number of units of the service defined in the plan. Integer. This number can be updated during the billing cycle using [Update Subscription](https://docs.rapyd.net/en/update-subscription.md "Update Subscription") or [Update Subscription Item](https://docs.rapyd.net/en/update-subscription-item.md "Update Subscription Item"). - - subscription - ID of the subscription that this subscription item belongs to. ### Response Parameters - - created - The time the subscription item was created, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - id - ID of the subscription item. String starting with **subi_**. - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - plan - The pricing plan that defines the product and pricing structure associated with this subscription item. Cannot be a plan that is already part of the subscription. For details of the fields in the 'plan' object, see [Create Plan](https://docs.rapyd.net/en/create-plan.md "Create Plan"). - - quantity - The number of units of the service defined in the plan. Integer. This number can be updated during the billing cycle using [Update Subscription](https://docs.rapyd.net/en/update-subscription.md "Update Subscription") or [Update Subscription Item](https://docs.rapyd.net/en/update-subscription-item.md "Update Subscription Item"). - - subscription_id - ID of the subscription that this subscription item belongs to. ### Code Samples - - .NET - ```csharp 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 - ```javascript const makeRequest = require('/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 /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 - ```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 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 }' ``` - ```json { "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 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 }' ``` - ```json { "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 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 }' ``` - ```json { "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" } } ```