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

Subscriptions Query

  • To retrieve the list of subscriptions linked to a specific customer, use the query below.
query GetSubscriptions($siteId: String!, $customerId: String!) {
  customer(siteId: $siteId, customerId: $customerId) {
    status
    subscriptions {
      id
      currency
      quantity
      status
      startedOn
      endedOn
      futureStart
      attachments {
        fileName
        externalFileName
        createdAtUtc
        fileSizeKb
        canBeDeleted
      }
    }
  }
}
#All properties are found in the SubscriptionGQLType
// Variables Sample:
{
  "siteId": "test-site",
  "customerId": "test-site_65950a2940f341dbab60ccf5e47e7d66"
}

Plan Subscriptions Query

  • To retrieve a list of all subscriptions for the plans on your site, use the query below.
query GetPlanSubscriptions($siteId: String!, $pagination: PaginationGQLInputType, $sorting: [SortingGQLInputType], $filter: FilterGQLInputType) {
  planSubscriptions(
    siteId: $siteId
    pagination: $pagination
    sorting: $sorting
    filter: $filter
  ) {
    isSuccess
    message
    data {
      id
      customerId
      customer{
        id
        customerId
      }
      status
    }
  }
}
#All properties are found in the SubscriptionGQLType
// Variables Sample:
{
  "siteId": "test-site",
  "filter": {
    "originalPlanId": "specific-plan-id"
  }
}
// You can filter the results by "originalPlanId" to retrieve subscriptions for a specific plan.

Usage Query

  • To retrieve the usage for a post-paid subscription plan, use the query below.
query GetSubscriptionUsage($siteId: String!, $subscriptionId: String!, $utcStartDate: DateTime!, $utcEndDate: DateTime!) {
  queryUsage(
    siteId: $siteId
    subscriptionId: $subscriptionId
    utcStartDate: $utcStartDate
    utcEndDate: $utcEndDate
  ) {
    message
    isSuccess
  }
}
#All properties are found in the QueryUsageResultGQLType
// Variables Sample:
{
  "siteId": "test-site",
  "subscriptionId": "fe7ce595-7ba7-4223-abae-95f649abb6c8",
  "utcStartDate": "2025-02-03T12:19:49.641067",
  "utcEndDate": "2025-03-03T12:19:49.641067"
}

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 Sample:
{
    "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 Sample:
{
    "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 Sample:
{
    "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 Sample:
{
    "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 Sample:
{
    "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 Sample:
{
    "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 Sample:
{
  "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 protected]"
    }
  ]
}

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 Sample:
{
  "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 Sample:
{
  "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": "[email protected]"
    }
  ]
}

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 Sample:
{
  "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 Sample:
{
    "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 Sample:
{
    "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 Sample:
{
    "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 Sample:
{
    "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
      }
    ]
}

Plan Subscription Fields

Add Info Field to Plan Subscription

  • To add info fields to a plan subscription profile, you need to use the following Mutation:
mutation AddPlanSubscriptionInfoField(
    $siteId: String!
    $customerId: String
    $planSubscriptionId: String!
    $infoField: CustomerInfoFieldGQLInputType!
) {
    customer(siteId: $siteId, customerId: $customerId) {
        subscription(planSubscriptionId: $planSubscriptionId) {
            infoFields {
                add(infoField: $infoField) {
                    isSuccess
                    message
                }
            }
        }
    }
}
// Variables Sample:
{
    "siteId": "test-site",
    "planSubscriptionId": "34ef5158-a9f1-4c6e-9ccd-4d7e071391ac",
    "infoField": {
        "name": "name",
        "value": "full name",
        "label": "full name"
    }
}

Update Info Field in Plan Subscription

  • To update info fields in a plan subscription profile, you need to use the following Mutation:
mutation UpdateInfoField($siteId: String!, $customerId: String!, $planSubscriptionId: String!, $name: String!, $infoField: CustomerInfoFieldGQLInputType!) {
  customer(
    siteId: $siteId
    customerId: $customerId
    planSubscriptionId: $planSubscriptionId
  ) {
    subscription(planSubscriptionId: $planSubscriptionId) {
      infoField(name: $name) {
        update(infoField: $infoField) {
          isSuccess
          message
        }
      }
    }
  }
}
// Variables Sample:
{
  "siteId": "test-site",
  "customerId": "test-site_1af0ef202d3e48ec89d2a765b0975465",
  "name": "lala",
  "planSubscriptionId": "34ef5158-a9f1-4c6e-9ccd-4d7e071391ac",
  "infoField": {
    "name": "name",
    "label": "phone",
    "value": "phone",
    "type": null,
    "editable": null,
    "required": null,
    "validation": null
  }
}

Delete Info Field from Plan Subscription

  • To delete info fields from a plan subscription profile, you need to use the following Mutation:
mutation DeleteSubscriptionCustomField($siteId: String!, $customerId: String!, $name: String!, $planSubscriptionId: String!) {
  customer(siteId: $siteId, customerId: $customerId) {
    subscription(planSubscriptionId: $planSubscriptionId) {
      infoField(name: $name) {
        delete {
          isSuccess
          message
        }
      }
    }
  }
}
// Variables Sample:
{
  "siteId": "test-site",
  "customerId": "test-site_1af0ef202d3e48ec89d2a765b0975465",
  "planSubscriptionId": "34ef5158-a9f1-4c6e-9ccd-4d7e071391ac",
  "name": "name"
}

Add Custom Field to Plan Subscription

  • To add custom fields to a plan subscription profile, you need to use the following Mutation:
mutation AddPlanSubscriptionCustomField(
    $siteId: String!
    $customerId: String
    $planSubscriptionId: String!
    $customField: KeyValuePairGQLInputType!
) {
    customer(siteId: $siteId, customerId: $customerId) {
        subscription(planSubscriptionId: $planSubscriptionId) {
            customFields {
                add(customField: $customField) {
                    isSuccess
                    message
                }
            }
        }
    }
}
// Variables Sample:
{
    "siteId": "test-site",
    "planSubscriptionId": "172e08fe-8cc7-4680-a3d1-90fff1b3251e",
    "customField": {
        "key": "Preferred Contact Method",
        "value": "email"
    }
}

Update Custom Field in Plan Subscription

  • To update custom fields in a plan subscription profile, you need to use the following Mutation:
mutation UpdateSubscriptionCustomField($siteId: String!, $customerId: String!, $name: String!, $planSubscriptionId: String!, $customField: KeyValuePairGQLInputType!) {
  customer(
    siteId: $siteId
    customerId: $customerId
    planSubscriptionId: $planSubscriptionId
  ) {
    subscription(planSubscriptionId: $planSubscriptionId) {
      customField(name: $name) {
        update(customField: $customField) {
          isSuccess
          message
        }
      }
    }
  }
}
// Variables Sample:
{
  "siteId": "test-site",
  "customerId": "test-site_1af0ef202d3e48ec89d2a765b0975465",
  "planSubscriptionId": "34ef5158-a9f1-4c6e-9ccd-4d7e071391ac",
  "name": "test",
  "customField": {
    "key": "Preferred Contact Method",
    "value": "Mobile"
  }
}

Delete Custom Field from Plan Subscription

  • To delete custom fields from a plan subscription profile, you need to use the following Mutation:
mutation DeleteSubscriptionCustomField($siteId: String!, $customerId: String!, $name: String!, $planSubscriptionId: String!) {
  customer(siteId: $siteId, customerId: $customerId) {
    subscription(planSubscriptionId: $planSubscriptionId) {
      customField(name: $name) {
        delete {
          isSuccess
          message
        }
      }
    }
  }
}
// Variables Sample:
{
  "siteId": "test-site",
  "customerId": "test-site_1af0ef202d3e48ec89d2a765b0975465",
  "planSubscriptionId": "34ef5158-a9f1-4c6e-9ccd-4d7e071391ac",
  "name": "name"
}

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