Skip to main content

Documentation

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:

Depending on the parameters in the request, some of these webhooks are triggered synchronously.

Note

Code Samples
    • .NET

      • 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

      • const makeRequest = require('<path-to-your-utility-file>/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
        $path = $_SERVER['DOCUMENT_ROOT'];
        $path .= "/<path-to-your-utility-file>/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

      • 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 -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'
    -d '{
        "customer": "cus_ec543c4dfcf6ac1d015b2e3e4fd07180",
        "billing": "pay_automatically",
        "cancel_at_period_end": true,
        "coupon": "",
        "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
    }
    '
    
  • {
        "status": {
            "error_code": "",
            "status": "SUCCESS",
            "message": "",
            "response_code": "",
            "operation_id": "0192a34d-c0ad-4b89-b7b3-dbe3129cba66"
        },
        "data": {
            "id": "sub_4d9bcdf0a768a90e2f39a04ae1331e90",
            "billing": "pay_automatically",
            "billing_cycle_anchor": 1592379647,
            "created_at": 1592379647,
            "customer_token": "cus_ec543c4dfcf6ac1d015b2e3e4fd07180",
            "days_until_due": null,
            "metadata": {
                "merchant_defined": true
            },
            "tax_percent": 10.5,
            "cancel_at_period_end": true,
            "canceled_at": null,
            "current_period_end": 1594971647,
            "current_period_start": 1592379647,
            "discount": null,
            "ended_at": null,
            "subscription_items": {
                "data": [
                    {
                        "id": "subi_a9f34be0551bf85ffb13e4fdb6107d6d",
                        "created": 1592379647,
                        "metadata": null,
                        "quantity": 1,
                        "plan": {
                            "id": "plan_51788cf4ed1b672cb0a2a97773887f5b",
                            "aggregate_usage": "sum",
                            "amount": 0,
                            "billing_scheme": "tiered",
                            "created_at": 1592311574,
                            "currency": "USD",
                            "interval": "month",
                            "interval_count": 1,
                            "metadata": {
                                "merchant_defined": true
                            },
                            "product": "product_ab9599d248f6d4d4311148aea68e20d0",
                            "nickname": "Basic parking",
                            "tiers": [
                                {
                                    "amount": 15,
                                    "up_to": "inf",
                                    "flat_amount": 0
                                }
                            ],
                            "tiers_mode": "volume",
                            "transform_usage": {
                                "divide_by": 0,
                                "round": ""
                            },
                            "trial_period_days": 0,
                            "usage_type": "licensed"
                        }
                    }
                ],
                "has_more": false,
                "total_count": 0,
                "url": "/v1/subscription_items?subscription=sub_4d9bcdf0a768a90e2f39a04ae1331e90"
            },
            "status": "active",
            "trial_end": null,
            "trial_start": null,
            "payment_method": "card_156da7de485275ad0bae798b7cb8fea1",
            "payment_fields": null,
            "payout_fields": null,
            "type": "payment",
            "simultaneous_invoice": true
        }
    }
  • Create Subscription with Payment Fields

  • 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'
    -d '{
        "customer": "cus_ec543c4dfcf6ac1d015b2e3e4fd07180",
        "billing": "pay_automatically",
        "cancel_at_period_end": false,
        "coupon": "",
        "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": "",
        "payment_fields": {
            "error_payment_url": "https://error.example1234.net",
            "complete_payment_url": "https://complete.example5678.net"
        }
    }
    '
    
  • {
        "status": {
            "error_code": "",
            "status": "SUCCESS",
            "message": "",
            "response_code": "",
            "operation_id": "ad65f71a-c208-479d-9e79-8cce9ca2f05b"
        },
        "data": {
            "id": "sub_324ee75f8c26f1df94bc8cc693f3c729",
            "billing": "pay_automatically",
            "billing_cycle_anchor": 1592380020,
            "created_at": 1592380020,
            "customer_token": "cus_ec543c4dfcf6ac1d015b2e3e4fd07180",
            "days_until_due": null,
            "metadata": {
                "merchant_defined": "true"
            },
            "tax_percent": 10.5,
            "cancel_at_period_end": false,
            "canceled_at": null,
            "current_period_end": 1594972020,
            "current_period_start": 1592380020,
            "discount": null,
            "ended_at": null,
            "subscription_items": {
                "data": [
                    {
                        "id": "subi_8de71d1894d62170571afbe14df1f848",
                        "created": 1592380020,
                        "metadata": null,
                        "quantity": 1,
                        "plan": {
                            "id": "plan_51788cf4ed1b672cb0a2a97773887f5b",
                            "aggregate_usage": "sum",
                            "amount": 0,
                            "billing_scheme": "tiered",
                            "created_at": 1592311574,
                            "currency": "USD",
                            "interval": "month",
                            "interval_count": 1,
                            "metadata": {
                                "merchant_defined": true
                            },
                            "product": "product_ab9599d248f6d4d4311148aea68e20d0",
                            "nickname": "Basic parking",
                            "tiers": [
                                {
                                    "amount": 15,
                                    "up_to": "inf",
                                    "flat_amount": 0
                                }
                            ],
                            "tiers_mode": "volume",
                            "transform_usage": {
                                "divide_by": 0,
                                "round": ""
                            },
                            "trial_period_days": 0,
                            "usage_type": "licensed"
                        }
                    }
                ],
                "has_more": false,
                "total_count": 0,
                "url": "/v1/subscription_items?subscription=sub_324ee75f8c26f1df94bc8cc693f3c729"
            },
            "status": "active",
            "trial_end": null,
            "trial_start": null,
            "payment_method": "card_156da7de485275ad0bae798b7cb8fea1",
            "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 -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'
    -d '{
        "customer": "cus_5bee14584a78638ba717e746be62ee01",
        "billing": "pay_automatically",
        "cancel_at_period_end": false,
        "payment_method": "card_794ddbfd19fcc548c8399ca957f11a24",
        "subscription_items": [
            {
                "plan": "plan_27921a1d4ebeb2db2e6aadf69a0094b1",
                "quantity": 1
            },
            {
                "plan": "plan_9609f87fcf8144a53ce52964497b1bab",
                "quantity": 1
            }
        ]
    }
    '
    
  • {
        "status": {
            "error_code": "",
            "status": "SUCCESS",
            "message": "",
            "response_code": "",
            "operation_id": "4c6949d5-bf37-4835-88bc-6f4d60edf5ff"
        },
        "data": {
            "id": "sub_1b33870bcc1b5d1b62da638170efa843",
            "billing": "pay_automatically",
            "billing_cycle_anchor": 1671427743,
            "created_at": 1671427743,
            "customer_token": "cus_5bee14584a78638ba717e746be62ee01",
            "days_until_due": 30,
            "metadata": {},
            "tax_percent": 0,
            "cancel_at_period_end": false,
            "canceled_at": null,
            "current_period_end": 1674106143,
            "current_period_start": 1671427743,
            "discount": null,
            "ended_at": null,
            "subscription_items": {
                "data": [
                    {
                        "id": "subi_345afc1b6b0f48923593034ac3cf55d6",
                        "created": 1671427743,
                        "metadata": null,
                        "quantity": 1,
                        "plan": {
                            "id": "plan_27921a1d4ebeb2db2e6aadf69a0094b1",
                            "aggregate_usage": "sum",
                            "amount": 5,
                            "billing_scheme": "per_unit",
                            "created_at": 1669022872,
                            "currency": "USD",
                            "interval": "month",
                            "interval_count": 1,
                            "metadata": {},
                            "product": "product_8a9a3932967cb7f2caf91d3cc07be5c8",
                            "nickname": "Basic",
                            "tiers": [],
                            "tiers_mode": "",
                            "transform_usage": {
                                "divide_by": 1,
                                "round": "up"
                            },
                            "trial_period_days": 0,
                            "usage_type": "licensed"
                        }
                    },
                    {
                        "id": "subi_c5ab875d7288b4b238440e1cdfd82339",
                        "created": 1671427743,
                        "metadata": null,
                        "quantity": 1,
                        "plan": {
                            "id": "plan_9609f87fcf8144a53ce52964497b1bab",
                            "aggregate_usage": "max",
                            "amount": 50,
                            "billing_scheme": "per_unit",
                            "created_at": 1669288713,
                            "currency": "USD",
                            "interval": "month",
                            "interval_count": 1,
                            "metadata": {},
                            "product": "product_2ddd6f6b43f598d30543ef23ab806b58",
                            "nickname": "Premium Metered",
                            "tiers": [],
                            "tiers_mode": "",
                            "transform_usage": {
                                "divide_by": 1,
                                "round": "up"
                            },
                            "trial_period_days": 0,
                            "usage_type": "metered"
                        }
                    }
                ],
                "has_more": false,
                "total_count": 0,
                "url": "/v1/subscription_items?subscription=sub_1b33870bcc1b5d1b62da638170efa843"
            },
            "status": "active",
            "trial_end": null,
            "trial_start": null,
            "payment_method": "card_794ddbfd19fcc548c8399ca957f11a24",
            "payment_fields": null,
            "payout_fields": null,
            "type": "payment"
        }
    }