🔁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.
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
content-type*
application/json
Request Body
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"
{
"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
Authorization: Bearer
your_api_key
{
"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
Authorization: Bearer*
your_api_key
{
// 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
Authorization: Bearer*
YOUR_API_KEY
Content-Type*
application/json
Request Body
plan_id*
new_plan_id
quantity*
2
{
"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:
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
Authorization: Bearer*
YOUR_API_KEY
{
"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:
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:
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
Last updated