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":""}

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"
    }
  ]
}

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"
    }
  ]

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
    }
}

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

VariablesType
siteIdstring
planSubscriptionIdstring (obtained from a previous customer query that includes subscriptions)
immediateCancellationBoolean, (optional) - If true, it cancels immediately. If false, it cancels at the end of the billing cycle, which is the default behavior.
Table of Contents