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

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

Add and Change Plan

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

Bulk Add Plan

  • For bulk add of 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 BulkAddPlan(
  $siteId: String!
  $customersIds: [String]!
  $planCode: String!
  $planQuantity: Long
  $addonsQuantity: [KeyValuePairGQLInputType!]
  $futureStart: IntervalGQLInputType
  $adminRequirements: AdminRequirementsGQLInputType
  $version: String
) {
  customers(siteId: $siteId) {
    bulkAddPlan(
      customersIds: $customersIds
      planCode: $planCode
      planQuantity: $planQuantity
      addonsQuantity: $addonsQuantity
      futureStart: $futureStart
      adminRequirements: $adminRequirements
      version: $version
    ) {
      isSuccess
      message
    }
  }
}

### variables
{
  "siteId": "test-site",
  "customersIds": ["customer_id_1", "customer_id_2", "customer_id_3"],
  "planCode": "a-daily-plan",
  "planQuantity": 1,
  "addonsQuantity": null,
  "futureStart": null,
  "adminRequirements": null,
  "version": "1.0"
}

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
) {

    # 'Move' is equivalent to 'Change', and 'Moving' is equivalent to 'Changing'.

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

Bulk Change Plan

  • For bulk change of 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 BulkChangePlan ($siteId: String!, $customersIds: [String]!, $oldPlanCode: String!, $planCode: String!) {
    customers(siteId: $siteId) {
        bulkChangePlan(customersIds: $customersIds, oldPlanCode: $oldPlanCode, planCode: $planCode) {
            isSuccess
            message
        }
    }
}

### variables
{
  "siteId": "test-site",
  "customersIds": ["customer_id_1", "customer_id_2", "customer_id_3"],
  "oldPlanCode": "old-plan-code",
  "planCode": "new-plan-code"
}

Subscription Addons

Add Free Addon

  • To add a free addon from a plan a customer is subscribed to, you need to use the following Mutation:
mutation AddFreeAddonCustomerSubscription(
    $siteId: String!
    $customerId: String!
    $planSubscriptionId: String!
    $addonId: ID!
) {
    customer(siteId: $siteId, customerId:$customerId) {
        subscription(planSubscriptionId: $planSubscriptionId) {
            addFreeAddon(addonId: $addonId) {
                isSuccess
                message
            }
        }
    }
}

### variables
{
    "siteId": "test-site",
    "customerId": "test-site_44884ed891424a44a25de0180f2e47fc",
    "planSubscriptionId": "8751108d-8da8-4be9-9868-dee831e770e0",
    "addonId": "8689aa26-43a6-4366-958f-21224ae63691"
}

Remove Free Addon

  • To remove a free addon from a plan a customer is subscribed to, you need to use the following Mutation:
mutation RemoveFreeAddonCustomerSubscription(
    $siteId: String!
    $customerId: String!
    $planSubscriptionId: String!
    $addonSubscriptionId: String!
) {
    customer(siteId: $siteId, customerId: $customerId) {
        subscription(planSubscriptionId: $planSubscriptionId) {
            removeFreeAddon(
                addonSubscriptionId: $addonSubscriptionId
            ) {
                isSuccess
                message
            }
        }
    }
}

### variables
{
    "siteId": "test-site",
    "customerId": "test-site_44884ed891424a44a25de0180f2e47fc",
    "planSubscriptionId": "49d274aa-4caf-4813-baba-4fb5184f0291",
    "addonSubscriptionId": "873b1170-7476-4bab-a6e6-46935c2e7a7c"
}

Update Free Addon

  • To update a free addon in a plan a customer is subscribed to, you need to use the following Mutation:
mutation UpdateFreeAddonCustomerSubscription(
    $siteId: String!
    $customerId: String!
    $planSubscriptionId: String!
    $addonSubscriptions: [AddonSubscriptionGQLInputType]!
) {
    customer(siteId: $siteId, customerId: $customerId) {
        subscription(planSubscriptionId: $planSubscriptionId) {
            updateFreeAddon(addonSubscriptions: $addonSubscriptions) {
                isSuccess
                message
            }
        }
    }
}

### variables
{
    "siteId": "test-site",
    "customerId": "test-site_44884ed891424a44a25de0180f2e47fc",
    "planSubscriptionId": "49d274aa-4caf-4813-baba-4fb5184f0291",
    "addonSubscriptions": [
        {
            "planSubscriptionId": "49d274aa-4caf-4813-baba-4fb5184f0291",
            "originalAddOnId": "4f926433-b7be-4e86-b83f-55d34de14713",
            "quantity": 10
        }
    ]
}

Edit Addons

  • To edit addons in a plan a customer is subscribed to, you need to use the following Mutation:
mutation EditCustomerSubscriptionAddons(
    $siteId: String!
    $customerId: String
    $planSubscriptionId: String!
    $addonsQuantity: [KeyValuePairGQLInputType]!
) {
    customer(siteId: $siteId, customerId: $customerId) {
        subscription(planSubscriptionId: $planSubscriptionId) {
            editAddons(addonsQuantity: $addonsQuantity) {
                isSuccess
                message
            }
        }
    }
}

### variables
{
    "siteId": "test-site",
    "planSubscriptionId": "e800135b-8e0e-47c8-a9c5-e00205ab076f",
    "customerId": "test-site_44884ed891424a44a25de0180f2e47fc",
    "addonsQuantity": [
        { 
      
        #The key is the plan addon Id, not the addon subscription Id.
        "key" :"a81b52a6-f0e1-4dde-ac08-df3ab74166b4",
        "value": 5
      }
    ]
}

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