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

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
                  }
                  infoFields {
                    name
                    label
                    type
                    value
                    validation
                    required
                    editable
                  }
                  customFields {
                    key
                    value
                  }
                  activePromoCode {
                    status
                    data {
                      billingCycleStartIndex
                      usageCount
                    }
                    promoCode {
                      code
                      campaign {
                        usageLimit
                        name
                        id
                      }
                    }
                  }
                  currentBillingCycleIndex
                  currentBillingCycleStart
                  currentBillingCycleEnd
                  currentBillingCycleId
                  plan {
                    planCode
                    id
                    name
                    data
                    description
                    pricingModel
                    addOns {
                      id
                    }
                    billingType
                    billingModel
                    billingCycle {
                      duration
                      termLimit {
                        actionOnEnd
                        cycles
                      }
                      usageQuery {
                        endpoint
                        codes
                        method
                      }
                      unit
                    }
                    fixedPricing {
                      price
                    }
                    perUnitPricing {
                      pricePerUnit
                      unit
                      freeQuantity
                    }
                    variablePricing {
                      type
                      unit
                      tiers {
                        from
                        to
                        price
                      }
                    }
                    baseCurrency {
                      code
                      displayText
                      symbol
                    }
                  }
                  addOns {
                    quantity
                    id
                    startedOn
                    endedOn
                    status
                    addOn {
                      id
                      name
                      description
                      code
                      baseCurrency {
                        code
                        displayText
                        symbol
                      }
                      billingCycle {
                        duration
                        unit
                      }
                      billingType
                      billingModel
                      pricingModel
                      fixedPricing {
                        price
                      }
                      perUnitPricing {
                        pricePerUnit
                        unit
                        freeQuantity
                      }
                      variablePricing {
                        type
                        unit
                        tiers {
                          from
                          to
                          price
                        }
                      }
                    }
                  }
                  pausingInfo {
                    timestamp
                    pausingDuration
                    remainingPeriodWhenPaused
                  }
                }
              }
            }

Returns an array of subscriptions
You can specify any of the fields detailed in the Subscription Type Definition.
For details about Pagination, Sorting, and Filtering Input Types, please check out PaginationGQLInputType, SortingGQLInputType, FilteringGQLInputType.

Plan Subscriptions Query

query PlanSubscriptions($siteId: String!, $pagination: PaginationGQLInputType, $sorting: [SortingGQLInputType], $filter: FilterGQLInputType) {
  planSubscriptions(
    siteId: $siteId
    pagination: $pagination
    sorting: $sorting
    filter: $filter
  ) {
    isSuccess
    message
    pagination {
      page
      perPage
      totalRecords
    }
    data {
      id
      customerId
      customer{
        id
        customerId
        firstName
        lastName
        fullName
        emailAddress
        localizationDictionary
      }
      status
    }
  }
}

### variables
{"siteId":"","pagination":"","sorting":"","filter":""}

Returns an array of subscriptions for all plans on your site.
You can filter the results by originalPlanId to retrieve subscriptions for a specific plan.
You can specify any of the fields detailed in the Subscription Type Definition.
For details about Pagination, Sorting, and Filtering Input Types, please check out PaginationGQLInputType, SortingGQLInputType, FilteringGQLInputType.

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}

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

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

You can specify any of the fields detailed in the Add Plan Result Type Definition.

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

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

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

You can specify any of the fields detailed in the Change Plan Subscription Result Type Definition.

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

You can specify any of the fields detailed in the Change Plan Subscription Result Type Definition.

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

You can specify any of the fields detailed in the Result GraphQL Type Definition.

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

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

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

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

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

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

{
  "siteId": "test-site",
  "customerId": "test-site_1af0ef202d3e48ec89d2a765b0975465",
  "planSubscriptionId": "34ef5158-a9f1-4c6e-9ccd-4d7e071391ac",
  "name": "name"
}

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.

Api And WebhooksCustomers API

Api And WebhooksPlans API