Update Subscription
Modify a subscription.
You can redefine the trial period if the status is active or trialing. If you change trial_end to now, the trial period ends immediately and billing_cycle_anchor is set to the present time. If you define a new trial period and prorate is true, the charges will be prorated.
To change a payment method, set the payment_method field to the ID of a payment method belonging to the same customer.
This method triggers the Subscription Updated Webhook. This webhook contains the same information as the response.
subscription
ID of the subscription. String starting with sub_.
Code Samples
.NET
using System; using System.Text.Json; namespace RapydApiRequestSample { class Program { static void Main(string[] args) { try { string subscription = "sub_4d9bcdf0a768a90e2f39a04ae1331e90"; var requestObj = new { metadata = new { merchant_defined = "updated" }, tax_percent = 10 }; string request = JsonSerializer.Serialize(requestObj); string result = RapydApiRequestSample.Utilities.MakeRequest("POST", $"/v1/subscriptions/{subscription}"); 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 = { trial_period_days: 30, coupon: 'coupon_f0517cffe4792ef3dd77f08a41b80d4e' }; const result = await makeRequest( 'POST', '/v1/payments/subscriptions/sub_4d9bcdf0a768a90e2f39a04ae1331e90', 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 { $body = [ "tax_percent"=> 10 ]; $object = make_request('post', '/v1/subscriptions/sub_4d9bcdf0a768a90e2f39a04ae1331e90'); var_dump($object); } catch(Exception $e) { echo "Error: $e"; } ?>
Python
from pprint import pprint from utilities import make_request subscription = { "metadata": { "merchant_defined": True }, "tax_percent": 10 } result = make_request(method='post', path='/v1/subscriptions/sub_4d9bcdf0a768a90e2f39a04ae1331e90', body=subscription) pprint(result)
/v1/payments/subscriptions/:subscription
Update Subscription - tax percent
curl -X post 'https://sandboxapi.rapyd.net/v1/payments/subscriptions/sub_4d9bcdf0a768a90e2f39a04ae1331e90' \ -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 '{ "tax_percent": 10 }'{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "de58446a-2006-4065-8586-095148de22c7" }, "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": 10, "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", "active": true, "attributes": [ "users" ], "created_at": 1673509005, "description": "SaaS Users", "images": [ "64bit-encoded-image-1" ], "metadata": { "merchant_defined": true }, "name": "SaaS Users", "package_dimensions": { "height": 0, "length": 0, "weight": 0, "width": 0 }, "shippable": false, "skus": [], "statement_descriptor": "Number of Users", "type": "services", "unit_label": "users", "updated_at": 1673509005 }, "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": 1, "url": "/v1/subscription_items?subscription=sub_1219e2329c4c5b26f08203d826a59d92" }, "status": "unpaid", "trial_end": null, "trial_start": null, "payment_method": "card_169329a41beed1e8fedb9e9bbc10d6b6", "payment_fields": null, "payout_fields": null, "type": "payment", "simultaneous_invoice": true } }
Add Discount
curl -X post 'https://sandboxapi.rapyd.net/v1/payments/subscriptions/sub_210c3425c928495873104df273ed237a' \ -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 '{ "coupon": "coupon_636099c2c0e77613cff7d83674ac72af" }'{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "75133e80-19bd-487a-8b26-876845b08928" }, "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": 10, "cancel_at_period_end": false, "canceled_at": null, "current_period_end": 1766483525, "current_period_start": 1761213125, "discount": { "id": "dis_70b371b231b819df77bec66e321ad4cd", "coupon": { "id": "coupon_636099c2c0e77613cff7d83674ac72af", "amount_off": 2, "created": 1761221460, "currency": "USD", "duration": "repeating", "duration_in_months": 1, "max_redemptions": 1, "metadata": {}, "percent_off": 0, "redeem_by": 0, "times_redeemed": 1, "discount_valid_until": 0, "discount_validity_in_months": 0, "discount_duration_in_uses": 1, "description": "", "valid": false }, "customer": "", "end": -1, "start": 1761221477, "number_of_uses": 0, "valid": true }, "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", "active": true, "attributes": [ "users" ], "created_at": 1673509005, "description": "SaaS Users", "images": [ "64bit-encoded-image-1" ], "metadata": { "merchant_defined": true }, "name": "SaaS Users", "package_dimensions": { "height": 0, "length": 0, "weight": 0, "width": 0 }, "shippable": false, "skus": [], "statement_descriptor": "Number of Users", "type": "services", "unit_label": "users", "updated_at": 1673509005 }, "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": 1, "url": "/v1/subscription_items?subscription=sub_1219e2329c4c5b26f08203d826a59d92" }, "status": "unpaid", "trial_end": null, "trial_start": null, "payment_method": "card_169329a41beed1e8fedb9e9bbc10d6b6", "payment_fields": null, "payout_fields": null, "type": "payment", "simultaneous_invoice": true } }
Change payment method
curl -X post 'https://sandboxapi.rapyd.net/v1/payments/subscriptions/sub_b2db5191d9623a958697614d665a5be5' \ -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 '{ "payment_method": "card_b9548d9b53a565b2315fecdc6c87f158" }'{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "8cd0dd9a-f860-4625-ab55-3bac32bd94d8" }, "data": { "id": "sub_b2db5191d9623a958697614d665a5be5", "billing": "pay_automatically", "billing_cycle_anchor": 1761221727, "created_at": 1761221727, "customer_token": "cus_4e25112ac20e144ad073a614dc46934b", "days_until_due": 30, "metadata": {}, "tax_percent": 0, "cancel_at_period_end": false, "canceled_at": null, "current_period_end": 1766492127, "current_period_start": 1761221727, "discount": null, "ended_at": null, "subscription_items": { "data": [ { "id": "subi_fd4d2d48578564f16c3c19d3e09612b9", "created": 1761221727, "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", "active": true, "attributes": [ "users" ], "created_at": 1673509005, "description": "SaaS Users", "images": [ "64bit-encoded-image-1" ], "metadata": { "merchant_defined": true }, "name": "SaaS Users", "package_dimensions": { "height": 0, "length": 0, "weight": 0, "width": 0 }, "shippable": false, "skus": [], "statement_descriptor": "Number of Users", "type": "services", "unit_label": "users", "updated_at": 1673509005 }, "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": 1, "url": "/v1/subscription_items?subscription=sub_b2db5191d9623a958697614d665a5be5" }, "status": "active", "trial_end": null, "trial_start": null, "payment_method": "card_b9548d9b53a565b2315fecdc6c87f158", "payment_fields": null, "payout_fields": null, "type": "payment", "simultaneous_invoice": true } }
Update Subscription Billing Cycle Anchor - testing only
curl -X post 'https://sandboxapi.rapyd.net/v1/payments/subscriptions/sub_17b55f5ccfe97f80fe73a7acc0545386' \ -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' \ -d '{ "billing_cycle_anchor": "now", "days_until_due": 0 }'{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "f3d596ad-0d48-45e5-87a2-e5e0a6fa57ba" }, "data": { "id": "sub_17b55f5ccfe97f80fe73a7acc0545386", "billing": "pay_automatically", "billing_cycle_anchor": 1673500131, "created_at": 1673499338, "customer_token": "cus_5bee14584a78638ba717e746be62ee01", "days_until_due": null, "metadata": {}, "tax_percent": 0, "cancel_at_period_end": false, "canceled_at": null, "current_period_end": 1674104931, "current_period_start": 1673500131, "discount": null, "ended_at": null, "subscription_items": { "data": [ { "id": "subi_a6f17fb61f9cad3c86327dd71dfaeb0c", "created": 1673499338, "metadata": { "merchant_defined": true }, "quantity": 25, "plan": { "id": "plan_d2b079cfbe29fc802baf215aa64bb1fa", "aggregate_usage": "sum", "amount": 0, "billing_scheme": "tiered", "created_at": 1673499122, "currency": "USD", "interval": "month", "interval_count": 1, "metadata": {}, "product": { "id": "product_fa1b30b1caa6711910f60e758dbe70c6", "active": true, "attributes": [ "quantity" ], "created_at": 1673498178, "description": "Public Transportation Usage", "images": [ "64bit-encoded-image-1" ], "metadata": { "merchant_defined": true }, "name": "Transit Rides", "package_dimensions": { "height": 0, "length": 0, "weight": 0, "width": 0 }, "shippable": false, "skus": [], "statement_descriptor": "Transit Usage", "type": "services", "unit_label": "rides", "updated_at": 1673498178 }, "nickname": "Transit Use", "tiers": [ { "amount": 4, "up_to": 5, "flat_amount": 1 }, { "amount": 3, "up_to": 10, "flat_amount": 0 }, { "amount": 2, "up_to": 20, "flat_amount": 0 }, { "amount": 1, "up_to": "inf", "flat_amount": 0 } ], "tiers_mode": "graduated", "transform_usage": { "divide_by": 1, "round": "up" }, "trial_period_days": 0, "usage_type": "licensed" } } ], "has_more": false, "total_count": 0, "url": "/v1/subscription_items?subscription=sub_17b55f5ccfe97f80fe73a7acc0545386" }, "status": "active", "trial_end": null, "trial_start": null, "payment_method": "card_794ddbfd19fcc548c8399ca957f11a24", "payment_fields": null, "payout_fields": null, "type": "payment", "simultaneous_invoice": false } }