Subcriptions API
The Subcriptions API is an integral component of the core
service. As a result, all requests should be directed to: https://api.subsbase.io/core/v2/graphql
.
The core service expects 2 headers, the X-SITE-ID
and Authorization
so the request would be:
POST https://api.subsbase.io/core/v2/graphql
Authorization: Bearer {server token}
X-SITE-ID: {your site id}
Consuming the Subscriptions API requires that a server token is used to authenticate the request. The server token is expected in the Authorization header.
Queries
Usage Query
query GetSubscriptionUsage($siteId: String!,$subscriptionId: String!,$utcStartDate: DateTime!,$utcEndDate: DateTime!) {
queryUsage (siteId: $siteId,subscriptionId: $subscriptionId,utcStartDate: $utcStartDate,utcEndDate: $utcEndDate) {
isSuccess
message
value {
name
#All properties are found in the QueryUsageResultGQLType
}
}
}
### variables
{"siteId":"","subscriptionId":"","utcStartDate":"","utcEndDate":""}
- Returns usage in a post-paid plan supscription.
- You can specify any of the fields detailed in the Query Usage Result Type Definition.
Mutations/Operations
Your Request
would look like this:
POST https://api.subsbase.io/core/v2/graphql
Content-Type: application/json
x-site-id: {site-id}
Authorization: Bearer {Customer Token}
Add Plan Subscription
- This operation assigns a selected plan to the customer, and notifies the customer to complete the checkout process.
- To update an existing customer plan, you need to use the following Mutation, it is advisable to use
variables
in this case since the input types are more complex than just strings:
mutation AddPlanSubscription(
$siteId: String!
$customerId: String!
$planCode: String!
$planQuantity: Long!
$addonsQuantity: [KeyValuePairGQLInputType!]
$infoFields: [CustomerInfoFieldGQLInputType!]
$futureStart: IntervalGQLInputType
$invoiceId: String
$adminRequirements: AdminRequirementsGQLInputType
) {
customer(siteId: $siteId, customerId: $customerId) {
subscriptions {
add(
planCode: $planCode
planQuantity: $planQuantity
addonsQuantity: $addonsQuantity
infoFields: $infoFields
futureStart: $futureStart
invoiceId: $invoiceId
adminRequirements: $adminRequirements
) {
isSuccess
message
value {
checkoutUrl
#All properties are found in the AddPlanResultGQLType
}
}
}
}
}
### variables
{
"siteId": "test-site",
"customerId": "test-site_b5ef7415bf3144e9ba0f92f2325dba84",
"planCode": "a-daily-plan",
"planQuantity": 1,
"addonsQuantity": null,
"infoFields": [
{
"name": "name",
"label": "Full Name",
"type": "Full Name",
"validation": ".*\\s+.+",
"required": true,
"editable": false,
"value": "2 coupon"
},
{
"name": "email",
"label": "Email",
"type": "Email",
"validation": "^(([^<>()[\\]\\\\.,;:\\s@\"]+(\\.[^<>()[\\]\\\\.,;:\\s@\"]+)*)|(\".+\"))@((\\[[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}])|(([a-zA-Z\\-0-9]+\\.)+[a-zA-Z]{2,}))$",
"required": true,
"editable": false,
"value": "email@email.com"
}
]
}
- You can specify any of the fields detailed in the Add Plan Result Type Definition.
Change Plan Subscription
- This operation either changes a plan subscription immediately, or at the end of the current billing cycle. You should have this subscription on an existing
customer
. - To change a plan subscription, you need to use the following Mutation, it is advisable to use
variables
in this case since the input types are more complex than just strings:
mutation ChangePlanSubscription(
$siteId: String!
$customerId: String!
$planSubscriptionId: String!
$planCode: String!
$planQuantity: Long
$addonsQuantity: [KeyValuePairGQLInputType]
$infoFields: [CustomerInfoFieldGQLInputType]
$immediateMoving: Boolean!
$adminRequirements: AdminRequirementsGQLInputType
) {
customer(siteId: $siteId, customerId: $customerId) {
subscription(planSubscriptionId: $planSubscriptionId) {
change(
planCode: $planCode
planQuantity: $planQuantity
infoFields: $infoFields
immediateMoving: $immediateMoving
addonsQuantity: $addonsQuantity
adminRequirements: $adminRequirements
) {
isSuccess
message
value {
needInfoFields
# All properties found in the ChangePlanSubscriptionResultGQLType
}
}
}
}
}
### variables
{
"siteId": "test-site",
"customerId": "test-site_434da7d505514500b4cadd7e1c7e9dbc",
"planCode": "rules-addons",
"planQuantity": 3,
"planSubscriptionId": "0df4d26a-7b5d-4b59-8dad-5afb95df09a6",
"immediateMoving": true,
"addonsQuantity": [
{
"key": "6ecc4455-390c-45d2-b0e6-e8f8ee2ac074",
"value": 1
},
{
"key": "baaa959e-4e9b-4144-99bb-91e91ced385c",
"value": 1
}
],
"infoFields": [
{
"key": "name",
"value": "John Smith"
},
{
"key": "email",
"value": "johnsmith@mail.com"
}
]
- You can specify any of the fields detailed in the Change Plan Subscription Result Type Definition.
Cancel Subscription
- This operation either cancels a subscription immediately, or at the end of the current billing cycle. You should have this subscription on an existing
customer
. - To cancel an existing subscription, you need to use the following Mutation, it is advisable to use
variables
in this case since the input types are more complex than just strings:
mutation CancelCustomerSubscription(
$siteId: String!
$customerId: String
$planSubscriptionId: String!
$immediateCancellation: Boolean!
) {
customer(siteId: $siteId, customerId: $customerId) {
subscription(planSubscriptionId: $planSubscriptionId) {
cancel(immediateCancellation: $immediateCancellation) {
isSuccess
message
}
}
}
}
### variables
{
"siteId": "test-site",
"planSubscriptionId": "e800135b-8e0e-47c8-a9c5-e00205ab076f",
"customerId": "test-site_44884ed891424a44a25de0180f2e47fc",
"immediateCancellation": true
}
Suspend Subscription
- To suspend a customer subscription, you need to use the following Mutation:
mutation SuspendCustomerSubscription(
$siteId: String!
$customerId: String!
$planSubscriptionId: String!
) {
customer(siteId: $siteId, customerId: $customerId) {
subscription(planSubscriptionId: $planSubscriptionId) {
suspend {
isSuccess
message
}
}
}
}
### variables
{
"siteId": "test-site",
"customerId": "test-site_44884ed891424a44a25de0180f2e47fc",
"planSubscriptionId": "8751108d-8da8-4be9-9868-dee831e770e0"
}
Pause Subscription
- To pause a customer subscription, you need to use the following Mutation:
mutation PauseCustomerSubscription(
$siteId: String!
$customerId: String!
$planSubscriptionId: String!
$pauseDurationId: String
) {
customer(siteId: $siteId, customerId: $customerId) {
subscription(planSubscriptionId: $planSubscriptionId) {
pause(pauseDurationId: $pauseDurationId) {
isSuccess
message
}
}
}
}
### variables
{
"siteId": "test-site",
"planSubscriptionId": "7167030f-57e3-4d57-a88d-a793701cc5ea",
"customerId": "test-site_44884ed891424a44a25de0180f2e47fc",
"pauseDurationId": "213c5e77-65b3-447b-993a-23e327786186"
}
Pause With Interval Customer Subscription
- To pause, a customer subscription, with an interval, you need to use the following Mutation:
mutation PauseWithIntervalCustomerSubscription(
$siteId: String!
$planSubscriptionId: String!
$customerId: String!
$pauseInterval: IntervalGQLInputType!
) {
customer(siteId: $siteId, customerId: $customerId) {
subscription(planSubscriptionId: $planSubscriptionId) {
pauseWithInterval(pauseInterval: $pauseInterval) {
isSuccess
message
}
}
}
}
### variables
{
"siteId": "test-site",
"planSubscriptionId": "08f7137d-aeaa-4b64-88c1-bbac91958cda",
"customerId": "test-site_943d5a8ec50f4b95b261792ffa77d10d",
"pauseInterval": {
"unit": "day",
"duration": 3
}
}
- For more details, please check out Pause Settings.
Resume Subscription
- To resume a paused customer subscription, you need to use the following Mutation:
mutation ResumeCustomerSubscription(
$siteId: String!
$customerId: String!
$planSubscriptionId: String!
) {
customer(siteId: $siteId, customerId: $customerId) {
subscription(planSubscriptionId: $planSubscriptionId) {
resume {
isSuccess
message
}
}
}
}
### variables
{
"siteId": "test-site",
"customerId": "test-site_44884ed891424a44a25de0180f2e47fc",
"planSubscriptionId": "31335ac3-8d0d-4abd-8468-d84ea9d3faf1"
}
Reactivate Subscription
- To reactivate a customer subscription, you need to use the following Mutation:
mutation ReactivateCustomerSubscription(
$siteId: String!
$customerId: String!
$planSubscriptionId: String!
) {
customer(siteId: $siteId, customerId: $customerId) {
subscription(planSubscriptionId: $planSubscriptionId) {
reactivate {
isSuccess
message
}
}
}
}
### variables
{
"siteId": "test-site",
"customerId": "test-site_44884ed891424a44a25de0180f2e47fc",
"planSubscriptionId": "8751108d-8da8-4be9-9868-dee831e770e0"
}
Understanding Subscription Variables
Variables | Type |
---|---|
siteId | string |
planSubscriptionId | string (obtained from a previous customer query that includes subscriptions) |
immediateCancellation | Boolean, (optional) - If true, it cancels immediately. If false, it cancels at the end of the billing cycle, which is the default behavior. |