--- title: "Create Subscription" source_url: https://docs.rapyd.net/en/create-subscription.html lang: en --- # Create Subscription Create a subscription for regular, automatic payments. This method triggers the **Customer Subscription Created** webhook. This webhook contains the same information as the response. The following asynchronous webhooks provide information about later changes to the subscription: - [Invoice Created Webhook](https://docs.rapyd.net/en/invoice-created-webhook.md "Invoice Created Webhook") - [Invoice Finalized Webhook](https://docs.rapyd.net/en/invoice-finalized-webhook.md "Invoice Finalized Webhook") - [Invoice Payment Created Webhook](https://docs.rapyd.net/en/invoice-payment-created-webhook.md "Invoice Payment Created Webhook") - [Invoice Payment Failed Webhook](https://docs.rapyd.net/en/invoice-payment-failed-webhook.md "Invoice Payment Failed Webhook") - [Invoice Payment Succeeded Webhook](https://docs.rapyd.net/en/invoice-payment-succeeded-webhook.md "Invoice Payment Succeeded Webhook") - [New Cycle Started Webhook](https://docs.rapyd.net/en/new-cycle-started-webhook.md "New Cycle Started Webhook") - [Payment Completed Webhook](https://docs.rapyd.net/en/payment-completed-webhook.md "Payment Completed Webhook") - [Payment Failed Webhook](https://docs.rapyd.net/en/payment-failed-webhook.md "Payment Failed Webhook") - [Payment Succeeded Webhook](https://docs.rapyd.net/en/payment-succeeded-webhook.md "Payment Succeeded Webhook") - [Subscription Unpaid Webhook](https://docs.rapyd.net/en/subscription-unpaid-webhook.md "Subscription Unpaid Webhook") - [Subscription Past Due Webhook](https://docs.rapyd.net/en/subscription-past-due-webhook.md "Subscription Past Due Webhook") - [Subscription Updated Webhook](https://docs.rapyd.net/en/subscription-updated-webhook.md "Subscription Updated Webhook") - [Trial Nearing End Webhook](https://docs.rapyd.net/en/trial-nearing-end-webhook.md "Trial Nearing End Webhook") Depending on the parameters in the request, some of these webhooks are triggered synchronously. > **Note:** > > - Clients with [PCI](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_pci "Payment Card Industry") certification can handle personal identifying information for cards. Clients that are not PCI-certified can use [Checkout Page](https://docs.rapyd.net/en/checkout-page.md "Checkout Page") or [Payment Link](https://docs.rapyd.net/en/payment-link.md "Payment Link") to collect money from a card. > - Before you create a subscription with a payment method token, verify that the value of `is_tokenizable` is **true**. See also [Payment Method Type](https://docs.rapyd.net/en/payment-method-type.md "Payment Method Type"). > - If the payment method category is **card**, certain operations require 3DS authentication. To simulate this authentication in the sandbox, use the URL from the `redirect_url` field that appears in [Invoice Payment Created Webhook](https://docs.rapyd.net/en/invoice-payment-created-webhook.md "Invoice Payment Created Webhook") and [Payment Succeeded Webhook](https://docs.rapyd.net/en/payment-succeeded-webhook.md "Payment Succeeded Webhook"). See [Simulating 3DS Authentication](https://docs.rapyd.net/en/simulating-3ds-authentication.md "Simulating 3DS Authentication"). > - A **card** payment that requires 3DS authentication must be authenticated within 15 minutes. > - All plans in the subscription must have the same value for `trial_period_days`. > - 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 Errors](https://docs.rapyd.net/en/subscription-errors.md "Subscription 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 - - billing - Determines the method of billing at the end of the billing cycle. Set to **pay_automatically** - Rapyd generates a `payment` object, then attempts to pay it using the designated payment method. - - billing_cycle_anchor - Determines the start of the next full billing cycle, as defined in the plan described in the `items`. Value: - Timestamp in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") - Number (integer). A time in the future, at or after the end of the free trial period, not more than the length of the billing cycle. The current billing cycle will be shorter than all other billing cycles. > **Note:** > > If you update `trial_end`, `billing_cycle_anchor` is reset to the end of the new trial period. - - cancel_at_period_end - Determines the last date that charges accrue. - **true** - Charges accrue until the end of the current billing period, then the subscription is canceled. - When no trial period is set, after `cancel_at_period_end` is set to **true** the subscription will not be renewed at the next interval. - When a trial period is set after `cancel_at_period_end` is set to **true**, the subscription will not begin. - **false** - When the subscription is created, no end is defined. When [Cancel Subscription](https://docs.rapyd.net/en/cancel-subscription.md "Cancel Subscription") is run, charges stop immediately and the subscription is canceled. false - - coupon - ID of a coupon to apply a discount to the subscription. If the coupon defines a fixed monetary discount, it must use the same currency as the subscription. String starting with **coupon_**. - - customer - ID of the customer who pays for this subscription. String starting with **cus_**. - - days_until_due - Number of days from the invoice date for customer to complete the payment. - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - payment_fields - Additional `payment_options` fields. - - payment_method - Payment method ID or `payment_method` object. See [Add Payment Method to Customer](https://docs.rapyd.net/en/add-payment-method-to-customer.md "Add Payment Method to Customer"). If not specified in this field, the payment method is the default payment method specified for the customer. To create a payment method ID, use [Add Payment Method to Customer](https://docs.rapyd.net/en/add-payment-method-to-customer.md "Add Payment Method to Customer") or [Create Card Token](https://docs.rapyd.net/en/create-card-token.md "Create Card Token"). The ID is a string starting with **card_** or **other_**. > **Note:** > > In the sandbox, card details are removed after six months. - - simultaneous_invoice - Determines whether each upcoming subscription invoice is issued immediately. - **true** - The invoice is issued when the subscription is created. - **false** - The invoice is issued an hour after the subscription is created. true - - subscription_items - In requests, an array of objects containing the following fields. All subscription items must have plans with identical values for `interval` and `interval_count`. - - plan - ID of a plan that describes the service and pricing structure. The plan must be active. - - quantity - Number of units of the service described in `plan`. Integer. - - tax_percent - The percentage tax rate that is applied to the subtotal of the invoice, after subtracting all discounts. Decimal. Range: 0-100, with up to four decimal places. - - trial_end - Defines the customer's free trial period. Relevant when `trial_period_days` is not defined. One of the following values: - The date and time of the end of the free trial period, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). Number (integer), - **now** - There is no free trial period. - - trial_from_plan - Determines whether the subscription uses the free trial period defined in the plan. - **true** - Uses the trial period defined in the plans added to the subscription. When `trial_from_plan` is true, all plans in the subscription must have the same value for `trial_period_days`. - **false** - Uses the trial period defined in the subscription. false - - trial_period_days - The number of days in the customer's free trial period. Integer. Range: 0-730. Relevant when `trial_end` is not defined. ### Response Parameters - - billing - Determines the method of billing at the end of the billing cycle. Set to **pay_automatically** - Rapyd generates a `payment` object, then attempts to pay it using the designated payment method. - - billing_cycle_anchor - Determines the start of the next full billing cycle, as defined in the plan described in the `items`. One of the following values: - **now** - The present day. The next billing cycle starts right now. - *Timestamp* in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") - A time in the future, at or after the end of the free trial period, not more than the length of the billing cycle. The current billing cycle will be shorter than all other billing cycles. Relevant to creating a subscription. - **unchanged** - The original billing cycle anchor is unchanged. Relevant to updating a subscription. - - cancel_at_period_end - Determines the last date that charges accrue. - **true** - Charges accrue until the end of the current billing period, then the subscription is canceled. - When no trial period is set, after `cancel_at_period_end` is set to **true** the subscription will not be renewed at the next interval. - When a trial period is set after `cancel_at_period_end` is set to **true**, the subscription will not begin. - **false** - When the subscription is created, no end is defined. When [Cancel Subscription](https://docs.rapyd.net/en/cancel-subscription.md "Cancel Subscription") is run, charges stop immediately and the subscription is canceled. - - cancel_checkout_url - URL where the customer is redirected after pressing **Back to Website** to exit the hosted page. This URL overrides the `merchant_website` URL. Does not support localhost URLs. - - canceled_at - Date and time that the subscription is canceled by the customer or by the client. [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - complete_checkout_url - URL where the customer is redirected after pressing **Finish** to exit the hosted page. This URL overrides the `merchant_website` URL. Does not support localhost URLs. - - complete_payment_url - URL where the customer is redirected when payment is successful, after returning from an external page such as a 3DS page. Does not support localhost URLs. - - coupon - ID of a coupon to apply a discount to the subscription. String starting with **coupon_**. - - created_at - Time of creation of this subscription, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - current_period_end - End of the current billing cycle, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - current_period_start - Start of the current billing cycle, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - customer_token - ID of the customer who pays for this subscription. String starting with **cus_**. - - days_until_due - Number of days the customer has for paying this invoice. - - discount - Contains information about the coupon that applies to the subscription. Returned as a **null** value when there is no discount. - - ended_at - Date that the subscription was canceled or otherwise terminated. [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - error_payment_url - URL where the customer is redirected when payment is not successful, after returning from an external page, such as a 3DS page. Does not support localhost URLs. - - id - ID of the Subscription object. String starting with **sub_**. - - language - Determines the default language of the hosted page. For a list of values, see [List Supported Languages](https://docs.rapyd.net/en/list-supported-languages.md "List Supported Languages"). - When this parameter is null, the language of the user's browser is used. - If the language of the user's browser cannot be determined, the default language is English. - - merchant_reference_id - Identifier defined by the client for reference purposes. Limit: 45 characters. - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - page_expiration - End of the time when the customer can use the hosted page, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). If `page_expiration` is not set, the hosted page expires 14 days after creation. **Range:** 1 minute to 30 days. - - payment_fields - Additional `payment_options` fields. - - payment_method - Payment method used for paying invoices generated by this subscription. The ID is a string starting with **card_** or **other_**. - - payout_fields - Reserved. - - product - ID of a `product` object. String starting with **product_** Relevant to [List Subscriptions](https://docs.rapyd.net/en/list-subscriptions.md "List Subscriptions"). - - simultaneous_invoice - Determines when the system creates a payment for an invoice. - **true** - Payment is created when the invoice is issued. - **false** - Payment is created one hour after the invoice is issued. - - status - Status of the subscription. One of the following: - **active** - The customer is currently paying for this subscription. - **canceled** - The customer has canceled this subscription, but it remains in the Rapyd database. - **past_due** - Payment for this subscription was not received by the end of the billing period. - **trialing** - The subscription is in its free trial period. - **unpaid** - An error occurred in the payment for this subscription. - - subscription_items - An object or array of objects containing the following fields: - - data - Array of objects that describe individual subscription items. - - active - Indicates whether the subscription item is active. - - 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. String starting with **sub_**. - - has_more - Indicates that the number of `subscription_items` records is greater than the number of the returned records. - - total_count - Number of `subscription_items` records. - - url - URL for the record of all subscription items for this subscription. - - tax_percent - The percentage tax rate that is applied to the subtotal of the invoice, after subtracting all discounts. Decimal. - - trial_end - The date and time of the end of the customer's free trial period, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"), or the string **now**. Relevant when `trial_period_days` is not defined. - - trial_from_plan - Determines whether the subscription uses the free trial period defined in the plan. - **true** - Uses the trial period defined in the plans added to the subscription. When `trial_from_plan` is true, all plans in the subscription must have the same value for `trial_period_days`. - **false** - Uses the trial period defined in the subscription. - - trial_period_days - The number of days in the customer's free trial period. Integer. Range: 0-730. Relevant when `trial_end` is not defined. - - trial_start - Date and time of the start of the customer's free trial period, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - type - The type of the subscription. - **payment** ### Code Samples - - .NET - ```csharp using System; using System.Text.Json; namespace RapydApiRequestSample { class Program { static void Main(string[] args) { try { var requestObj = new { customer = "cus_ec543c4dfcf6ac1d015b2e3e4fd07180", billing = "pay_automatically", billing_cycle_anchor = "", cancel_at_period_end = true, coupon = "", days_until_due = string.Empty, payment_method = "card_156da7de485275ad0bae798b7cb8fea1", subscription_items = new Object[] { new { plan = "plan_51788cf4ed1b672cb0a2a97773887f5b", quantity = 1 } }, metadata = new { merchant_defined = true }, tax_percent = 10.5, trial_end = 0, trial_from_plan = true, trial_period_days = string.Empty, plan_token = "" }; string request = JsonSerializer.Serialize(requestObj); string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/payments/subscriptions", 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 = { customer: 'cus_ec543c4dfcf6ac1d015b2e3e4fd07180', billing: 'pay_automatically', billing_cycle_anchor: '', cancel_at_period_end: true, coupon: '', days_until_due: null, payment_method: 'card_156da7de485275ad0bae798b7cb8fea1', subscription_items: [ { plan: 'plan_51788cf4ed1b672cb0a2a97773887f5b', quantity: 1 } ], metadata: { merchant_defined: true }, tax_percent: 10.5, trial_end: 0, trial_from_plan: true, trial_period_days: null, plan_token: '' }; const result = await makeRequest('POST', '/v1/payments/subscriptions', body); console.log(result); } catch (error) { console.error('Error completing request', error); } } ``` - - PHP - ```php /utilities.php"; include($path); try { $body = [ "customer" => "cus_ec543c4dfcf6ac1d015b2e3e4fd07180", "billing" => "pay_automatically", "billing_cycle_anchor" => "", "cancel_at_period_end" => true, "coupon" => "", "days_until_due" => null, "payment_method" => "card_156da7de485275ad0bae798b7cb8fea1", "subscription_items" => [ array( "plan" => "plan_51788cf4ed1b672cb0a2a97773887f5b", "quantity" => 1 ) ], "metadata" => array( "merchant_defined" => true ), "tax_percent" => 10.5, "trial_end" => 0, "trial_from_plan" => true, "trial_period_days" => null, "plan_token" => "" ]; $object = make_request('post', '/v1/payments/subscriptions', $body); var_dump($object); } catch(Exception $e) { echo "Error: $e"; } ?> ``` - - Python - ```python from pprint import pprint from utilities import make_request subscription = { "customer": "cus_ec543c4dfcf6ac1d015b2e3e4fd07180", "billing": "pay_automatically", "billing_cycle_anchor": "", "cancel_at_period_end": True, "coupon": "", "days_until_due": "", "payment_method": "card_156da7de485275ad0bae798b7cb8fea1", "subscription_items": [ { "plan": "plan_51788cf4ed1b672cb0a2a97773887f5b", "quantity": 1 } ], "metadata": { "merchant_defined": True }, "tax_percent": 10.5, "trial_end": 0, "trial_from_plan": True, "trial_period_days": "", "plan_token": "", } result = make_request(method='post', path='/v1/subscriptions', body=subscription) pprint(result) ``` - /v1/payments/subscriptions - Create Subscription - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/payments/subscriptions' \ -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 '{ "customer": "cus_85579bd2098d5baf407f7f08313f5318", "billing": "pay_automatically", "subscription_items": [ { "plan": "plan_9338044c6ca654abd79da7319c40b7dc", "quantity": 1 } ] }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "e2fad0b3-c7f8-443c-ac95-d26a2f8f8f1c" }, "data": { "id": "sub_1219e2329c4c5b26f08203d826a59d92", "billing": "pay_automatically", "billing_cycle_anchor": 1761213125, "created_at": 1761213125, "customer_token": "cus_85579bd2098d5baf407f7f08313f5318", "days_until_due": 30, "metadata": {}, "tax_percent": 0, "cancel_at_period_end": false, "canceled_at": null, "current_period_end": 1766483525, "current_period_start": 1761213125, "discount": null, "ended_at": null, "subscription_items": { "data": [ { "id": "subi_353e05ee1107b6ecb9f1a7661358e575", "created": 1761213125, "metadata": null, "quantity": 1, "plan": { "id": "plan_9338044c6ca654abd79da7319c40b7dc", "aggregate_usage": "sum", "amount": 0, "billing_scheme": "tiered", "created_at": 1761210135, "currency": "USD", "interval": "month", "interval_count": 2, "metadata": {}, "product": { "id": "product_88fde8f1365082b50e8f4b37127edd99" }, "nickname": "SaaS Users", "tiers": [ { "amount": 35, "up_to": 5, "flat_amount": 25 }, { "amount": 30, "up_to": 10, "flat_amount": 0 }, { "amount": 25, "up_to": 25, "flat_amount": 0 }, { "amount": 20, "up_to": 100, "flat_amount": 0 }, { "amount": 15, "up_to": 500, "flat_amount": 0 }, { "amount": 10, "up_to": "inf", "flat_amount": 0 } ], "tiers_mode": "volume", "transform_usage": { "divide_by": 1, "round": "up" }, "trial_period_days": 0, "usage_type": "licensed", "active": true } } ], "has_more": false, "total_count": 0, "url": "/v1/subscription_items?subscription=sub_1219e2329c4c5b26f08203d826a59d92" }, "status": "active", "trial_end": null, "trial_start": null, "payment_method": "card_169329a41beed1e8fedb9e9bbc10d6b6", "payment_fields": null, "payout_fields": null, "type": "payment", "simultaneous_invoice": true } } ``` - Create Subscription with Payment Fields - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/payments/subscriptions' \ -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 '{ "customer": "cus_85579bd2098d5baf407f7f08313f5318", "billing": "pay_automatically", "cancel_at_period_end": false, "coupon": "", "payment_method": { "type": "gb_visa_card", "fields": { "name": "John Doe", "number": "4111111111111111", "expiration_month": "12", "expiration_year": "30", "cvv": "111" } }, "subscription_items": [ { "plan": "plan_d7dcedc6ec79b21d3fe8d5fde1af47f7", "quantity": 1 } ], "tax_percent": 10.5, "trial_end": 0, "trial_from_plan": true, "trial_period_days": "", "payment_fields": { "error_payment_url": "https://error.example1234.net", "complete_payment_url": "https://complete.example5678.net" } }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "afb456ac-9af0-4de3-a81b-1a2b192de76c" }, "data": { "id": "sub_1c9334696bc18fd89681cc800f758040", "billing": "pay_automatically", "billing_cycle_anchor": 1761818252, "created_at": 1761213452, "customer_token": "cus_85579bd2098d5baf407f7f08313f5318", "days_until_due": 30, "metadata": {}, "tax_percent": 10.5, "cancel_at_period_end": false, "canceled_at": null, "current_period_end": 1761818252, "current_period_start": 1761213452, "discount": null, "ended_at": null, "subscription_items": { "data": [ { "id": "subi_512e267b9d6eb3bb9fe5c8c5a851c1a2", "created": 1761213452, "metadata": null, "quantity": 1, "plan": { "id": "plan_d7dcedc6ec79b21d3fe8d5fde1af47f7", "aggregate_usage": "sum", "amount": 9.99, "billing_scheme": "per_unit", "created_at": 1761210540, "currency": "USD", "interval": "month", "interval_count": 1, "metadata": {}, "product": { "id": "product_4ba001c7655c4a0ee4f471dbaccaa305" }, "nickname": "Unlimited Plan", "tiers": [], "tiers_mode": "", "transform_usage": { "divide_by": 1, "round": "up" }, "trial_period_days": 7, "usage_type": "licensed", "active": true } } ], "has_more": false, "total_count": 0, "url": "/v1/subscription_items?subscription=sub_1c9334696bc18fd89681cc800f758040" }, "status": "trialing", "trial_end": 1761818252, "trial_start": 1761213452, "payment_method": "card_f7541a823319e86d3e628894fa6261c1", "payment_fields": { "error_payment_url": "https://error.example1234.net", "complete_payment_url": "https://complete.example5678.net" }, "payout_fields": null, "type": "payment", "simultaneous_invoice": true } } ``` - Create Subscription with Multiple Items - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/payments/subscriptions' \ -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 '{ "customer": "cus_4e25112ac20e144ad073a614dc46934b", "billing": "pay_automatically", "cancel_at_period_end": false, "payment_method": "card_b9548d9b53a565b2315fecdc6c87f158", "subscription_items": [ { "plan": "plan_4304ce1f6d347a2204711cd2d5354fa9", "quantity": 1 }, { "plan": "plan_9338044c6ca654abd79da7319c40b7dc", "quantity": 1 } ] }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "b1934108-fb91-4cc1-8a73-5a0a7eb8b1a0" }, "data": { "id": "sub_a16955cdb7e1a0b52395ff1e29f8ece7", "billing": "pay_automatically", "billing_cycle_anchor": 1761213828, "created_at": 1761213828, "customer_token": "cus_4e25112ac20e144ad073a614dc46934b", "days_until_due": 30, "metadata": {}, "tax_percent": 0, "cancel_at_period_end": false, "canceled_at": null, "current_period_end": 1766484228, "current_period_start": 1761213828, "discount": null, "ended_at": null, "subscription_items": { "data": [ { "id": "subi_117a8e763b2f9965329a2081d5ded5e7", "created": 1761213828, "metadata": null, "quantity": 1, "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 } }, { "id": "subi_42a0955d0e5542c2b7f6350a9948c73e", "created": 1761213828, "metadata": null, "quantity": 1, "plan": { "id": "plan_9338044c6ca654abd79da7319c40b7dc", "aggregate_usage": "sum", "amount": 0, "billing_scheme": "tiered", "created_at": 1761210135, "currency": "USD", "interval": "month", "interval_count": 2, "metadata": {}, "product": { "id": "product_88fde8f1365082b50e8f4b37127edd99" }, "nickname": "SaaS Users", "tiers": [ { "amount": 35, "up_to": 5, "flat_amount": 25 }, { "amount": 30, "up_to": 10, "flat_amount": 0 }, { "amount": 25, "up_to": 25, "flat_amount": 0 }, { "amount": 20, "up_to": 100, "flat_amount": 0 }, { "amount": 15, "up_to": 500, "flat_amount": 0 }, { "amount": 10, "up_to": "inf", "flat_amount": 0 } ], "tiers_mode": "volume", "transform_usage": { "divide_by": 1, "round": "up" }, "trial_period_days": 0, "usage_type": "licensed", "active": true } } ], "has_more": false, "total_count": 0, "url": "/v1/subscription_items?subscription=sub_a16955cdb7e1a0b52395ff1e29f8ece7" }, "status": "active", "trial_end": null, "trial_start": null, "payment_method": "card_b9548d9b53a565b2315fecdc6c87f158", "payment_fields": null, "payout_fields": null, "type": "payment", "simultaneous_invoice": true } } ``` - Bad Request - Customer Not Found - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/payments/subscriptions' \ -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 '{ "customer": "cus_4e25112ac20e144ad073a614dc46934", "billing": "pay_automatically", "subscription_items": [ { "plan": "plan_390625a173f599153b5250715d861718", "quantity": 1 } ] }' ``` - ```json { "status": { "error_code": "ERROR_GET_CUSTOMER", "status": "ERROR", "message": "The request attempted an operation that requires the ID of a customer, but the customer was not found. The request was rejected. Corrective action: Use the correct ID of the customer, a string starting with 'cus_'.", "response_code": "ERROR_GET_CUSTOMER", "operation_id": "860e29ce-ca94-4f99-8738-7dd606c73477" } } ``` - Bad Request - Non-Integer Quantity - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/payments/subscriptions' \ -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 '{ "customer": "cus_4e25112ac20e144ad073a614dc46934b", "billing": "pay_automatically", "subscription_items": [ { "plan": "plan_390625a173f599153b5250715d861718", "quantity": 10.5 } ] }' ``` - ```json { "status": { "error_code": "INVALID_SUBSCRIPTION_ITEM_QUANTITY", "status": "ERROR", "message": "The request tried to create a subscription or a usage record, but the quantity for a subscription item was not valid or 'usage_type' in the relevant plan was set to 'metered'. The request was rejected. Corrective action: Use a positive integer for 'quantity' or create a new subscription item with a plan that has 'usage_type' set to 'metered'.", "response_code": "INVALID_SUBSCRIPTION_ITEM_QUANTITY", "operation_id": "0f5f45d1-ca16-4282-be7c-30f3fc0d9ef0" } } ```