🔁Subscriptions

Introduction

This section provides an overview of the Subscription feature provided by Sonic Payment Gateway. Subscriptions allow merchants to charge their customers on a recurring basis for goods or services. The subscriptions can be set up to be charged at a fixed interval (weekly, monthly, etc) and can be set up to run indefinitely or for a specific number of payments.

Create a Subscription

In order to create a subscription, you will need to make a POST request to the subscriptions endpoint with the following information.

Parameter	Type	Description
payment_link_id	string	The ID of the payment link associated with the subscription
start_date	date	The date when the first payment will be charged
interval_unit	string	The unit of the interval (day, week, month, year)
interval_count	integer	The number of units in the interval
total_occurrences	integer	The total number of payments that will be charged (optional)
metadata	json object	Additional information to associate with the subscription (optional)

GET https://api.sonicpay.org/subscriptions

Headers

Name	Type	Description
content-type*	application/json

Request Body

Name	Type	Description
payment_link_id*	5f6a2f7f-3400-4f47-8973-fa8bb2f5d483
start_date*	2022-05-30
interval_unit*	month
interval_count*	1
total_occurrences*	12
metadata*	"customer_id": "1234567890"

201: Created

{
    "id": "5f6a2f7f-3400-4f47-8973-fa8bb2f5d483",
    "payment_link_id": "5f6a2f7f-3400-4f47-8973-fa8bb2f5d483",
    "start_date": "2022-05-30",
    "interval_unit": "month",
    "interval_count": 1,
    "total_occurrences": 12,
    "metadata": {
        "customer_id": "1234567890"
    },
    "status": "active",
    "created_at": "2022-05-30T00:00:00.000Z"
}

Upon successful creation, the API will return a JSON object containing the subscription details, including the subscription_id which can be used to manage the subscription.

Get a Subscription

To retrieve a specific subscription, you will need to make a GET request to the subscriptions endpoint with the subscription_id as a path parameter.

GET https://api.sonicpay.org/subscriptions/5f6a2f7f-3400-4f47-8973-fa8bb2f5d483

Headers

Name	Type	Description
Authorization: Bearer	your_api_key

200: OK

{
    "id": "5f6a2f7f-3400-4f47-8973-fa8bb2f5d483",
    "payment_link_id": "5f6a2f7f-3400-4f47-8973-fa8bb2f5d483",
    "start_date": "2022-05-30",
    "interval_unit": "month",
    "interval_count": 1,
    "total_occurrences": 12,
    "metadata": {
        "customer_id": "1234567890"
    },
    "status": "active",
    "created_at": "2022-05-30T00:00:00.000Z"
}

The API will return a JSON object containing the subscription details.

Cancel a Subscription

To cancel a subscription, you will need to make a DELETE request to the subscriptions endpoint with the subscription_id as a path parameter

DELETE https://api.sonicpay.org/subscriptions/5f6a2f7f-3400-4f47-8973-fa8bb2f5d483

Headers

Name	Type	Description
Authorization: Bearer*	your_api_key

204: No Content

{
    // Response
}

The API will return a JSON object with a status of 'cancelled' for the subscription.

Update a Subscription

To update an existing subscription, you will need to make a PUT request to the /subscriptions/:id endpoint, where id is the unique identifier of the subscription you wish to update. The request body should contain a JSON object with the updated fields.

GET https://api.sonicpay.org/subscriptions/12345

Headers

Name	Type	Description
Authorization: Bearer*	YOUR_API_KEY
Content-Type*	application/json

Request Body

Name	Type	Description
plan_id*	new_plan_id
quantity*	2

200: OK

{
  "id": "12345",
  "plan_id": "new_plan_id",
  "quantity": 2,
  "status": "active",
  "metadata": {},
  "created_at": "2022-07-12T17:23:45.678Z",
  "updated_at": "2022-07-12T17:23:45.678Z"
}

Here is an example of how you can update a subscription using curl:

curl -X PUT https://api.sonicpay.org/subscriptions/12345 -H 
"Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{
  "plan_id": "new_plan_id",
  "quantity": 2
}'

In this example, we are updating the subscription with ID 12345 to have a new plan ID of new_plan_id and a quantity of 2.

You can also update the following fields:

Field	Type	Description
plan_id	string	The unique identifier of the plan associated with the subscription.
quantity	integer	The number of units of the plan associated with the subscription.
metadata	object	A JSON object that can be used to store additional information about the subscription.

Please note that the plan_id and quantity fields are required when updating a subscription.

If the update is successful, the API will return a 200 OK response with the updated subscription object in the response body. In case of any errors, the API will return a relevant error message and status code.

Here's an example of the expected response for a successful update:

{
  "id": "12345",
  "plan_id": "new_plan_id",
  "quantity": 2,
  "status": "active",
  "metadata": {},
  "created_at": "2022-07-12T17:23:45.678Z",
  "updated_at": "2022-07-12T17:23:45.678Z"
}

Get all Subscriptions

To retrieve all subscriptions, you will need to make a GET request to the /subscriptions endpoint. The API will return an array of subscription objects in the response body.

GET https://api.sonicpay.org/subscriptions

Headers

Name	Type	Description
Authorization: Bearer*	YOUR_API_KEY

200: OK

{
    "meta": {
        "total_count": 10,
        "page": 1,
        "per_page": 20
    },
    "data": [
        {
            "id": "5f6a2f7f-3400-4f47-8973-fa8bb2f5d483",
            "plan_id": "plan_123",
            "customer_id": "customer_456",
            "status": "active",
            "end_date": "2022-12-31",
            "start_date": "2022-05-30",
            "next_billing_date": "2022-06-30",
            "cancel_at_period_end": false,
            "created_at": "2022-05-30T00:00:00.000Z",
            "updated_at": "2022-06-01T00:00:00.000Z",
            "metadata": {
                "order_id": "order_789"
            }
        },
        {
            "id": "5f6a2f7f-3400-4f47-8973-fa8bb2f5d484",
            "plan_id": "plan_456",
            "customer_id": "customer_789",
            "status": "canceled",
            "end_date": "2022-12-31",
            "start_date": "2022-05-30",
            "next_billing_date": "2022-06-30",
            "cancel_at_period_end": true,
            "created_at": "2022-05-30T00:00:00.000Z",
            "updated_at": "2022-06-01T00:00:00.000Z",
            "metadata": {
                "order_id": "order_789"
            }
        }
}

Here is an example of how you can retrieve all subscriptions using curl:

curl -X GET https://api.sonicpay.org/subscriptions -H "Authorization: Bearer YOUR_API_KEY"

You can also use the following optional query parameters to filter the subscriptions:

Parameter	Type	Description
plan_id	string	The unique identifier of the plan to filter by.
status	string	The status of the subscriptions to filter by.

Here is an example of how you can retrieve all active subscriptions for a specific plan using curl:

curl -X GET https://api.sonicpay.org/subscriptions?plan_id=plan_id&status=active -H "Authorization: Bearer YOUR_API_KEY"

If the request is successful, the API will return a 200 OK response with an array of subscription objects in the response body. Each object will have the following properties:

Property	Type	Description
id	string	Unique identifier for the subscription
plan_id	string	ID of the plan associated with the subscription
customer_id	string	ID of the customer associated with the subscription
status	string	Status of the subscription (active, canceled, etc.)
start_date	string	Date the subscription started in ISO 8601 format
end_date	string	Date the subscription ends in ISO 8601 format, if applicable
next_billing_date	string	Date of the next billing in ISO 8601 format
cancel_at_period_end	boolean	Indicates if the subscription will cancel at the end of the current billing period
created_at	string	Date the subscription was created in ISO 8601 format
updated_at	string	Date the subscription was last updated in ISO 8601 format
metadata	object	Additional information associated with the subscription