Plans API

The Plans 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 Plans API requires that a server token is used to authenticate the request. The server token is expected in the Authorization header.

Queries

Plans Query

query GetPlans($siteId: String!, $pagination: PaginationGQLInputType, $sorting: [SortingGQLInputType], $filter: FilterGQLInputType) {
  plans(
    siteId: $siteId
    pagination: $pagination
    sorting: $sorting
    filter: $filter
  ) {
    isSuccess
    message
    pagination {
      page
      perPage
      totalRecords
    }
    data {
      id
      activeSubscribersCount
      planCode
      canBeDeleted
      hostedPageUrl
      name
      billingModel
      billingType
      pricingModel
      localizationDictionary
      addOns {
        billingModel
      }
      fixedPricing {
        price
      }
      perUnitPricing {
        pricePerUnit
        unit
        freeQuantity
      }
      variablePricing {
        type
        unit
        tiers {
          from
          to
          price
        }
      }
      status
      baseCurrency {
        code
      }
      description
      invoiceName
      accountingCode
      effectiveStartDate
      effectiveEndDate
      setupFee
      trialPeriod {
        duration
        requiresCreditCard
        unit
      }
      billingCycle {
        duration
        termLimit {
          actionOnEnd
          cycles
        }
        unit
      }
    }
  }
}
#All properties are found in the PlanGQLType

// Variables Sample:
{
  "siteId": "test-site",
  "pagination": {
    "perPage": 20,
    "page": 1
  },
  "sorting": [
    {
      "field": "name",
      "direction": "Ascending"
    }
  ]
}

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

Plan Query

query GetPlan($siteId: String!, $planCode: String!) {
  plan(siteId: $siteId, planCode: $planCode) {
    id
    data
    planCode
    name
    canBeDeleted
    billingModel
    billingType
    hostedPageUrl
    pricingModel
    hasActiveSubscribers
    activeSubscribersCount
    displaySettings
    discountedFrom
    data
    localizationDictionary
    taxProfile {
      id
      name
      taxAuthority
    }
    dunningProfile {
      id
      name
    }
    narrativeTemplate {
      id
      name
    }
    planPausingDurations {
      id
      displayText
      pausingValue {
        unit
        duration
      }
    }
    planFutureStarts {
      id
      displayText
      interval {
        unit
        duration
      }
    }
    fixedPricing {
      price
      displayCurrencyConversion
      taxInclusive
      extraFees {
        id
        name
        type
        value
        rule {
          name
          operation
          value
          valueType
        }
      }
    }
    perUnitPricing {
      pricePerUnit
      unit
      freeQuantity
      taxInclusive
      displayCurrencyConversion
      extraFees {
        id
        name
        type
        value
        rule {
          name
          operation
          value
          valueType
        }
      }
      rules {
        values {
          label
          value
        }
        min
        max
        step
      }
    }
    variablePricing {
      type
      unit
      taxInclusive
      displayCurrencyConversion
      extraFees {
        id
        name
        type
        value
        rule {
          name
          operation
          value
          valueType
        }
      }
      tiers {
        from
        to
        price
      }
      rules {
        values {
          label
          value
        }
        min
        max
        step
      }
    }
    status
    baseCurrency {
      code
      displayText
      symbol
    }
    displayCurrency {
      code
      displayText
      symbol
    }
    billingCurrency {
      code
      displayText
      symbol
    }
    description
    imageUrl
    invoiceName
    accountingCode
    effectiveStartDate
    effectiveEndDate
    setupFee
    trialPeriod {
      duration
      requiresCreditCard
      unit
    }
    billingCycle {
      duration
      termLimit {
        actionOnEnd
        cycles
      }
      unit
      dueInvoiceDueSettings {
        duration
        unit
        action
      }
      earlyInvoiceCreationSettings {
        duration
        unit
      }
      usageQuery {
        codes
        endpoint
        customHeaders {
          key
          value
        }
      }
      model
      cycleStart {
        startDayInMonth
        startDay
        startMonth
      }
      changeMode
    }
    infoFields {
      name
      label
      type
      validation
      required
      editable
      disabled
      associatedTo
    }
    planRules {
      maxTotalAddonsQuantity
      exactTotalAddonsQuantity
    }
    addOns {
      id
      data
      name
      code
      description
      accountingCode
      imageUrl
      status
      hasActiveSubscribers
      displaySettings
      canBeDeleted
      localizationDictionary
      baseCurrency {
        code
        displayText
        symbol
      }
      taxProfile {
        id
        name
        taxAuthority
      }
      billingCycle {
        duration
        unit
      }
      billingType
      billingModel
      pricingModel
      fixedPricing {
        price
        rules {
          min
        }
        required
      }
      perUnitPricing {
        pricePerUnit
        unit
        freeQuantity
        rules {
          values {
            label
            value
          }
          min
          max
          step
        }
      }
      variablePricing {
        type
        unit
        tiers {
          from
          to
          price
        }
        rules {
          values {
            label
            value
          }
          min
          max
          step
        }
      }
    }
  }
}
#All properties are found in the PlanGQLType

// Variables Sample:
{
  "planCode": "semi-annual-plan",
  "siteId": "test-site"
}

Returns a specific plan.
You can specify any of the fields detailed in the Plan Type Definition and Billing Cycle Info Type Definition.

Plan Mutations/Operations

Create Plan

To create a 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 CreatePlan($siteId: String!, $plan: PlanGQLInputType!) {
    plans(siteId: $siteId) {
        create(plan: $plan) {
            isSuccess
            message
            value {
                id
                #All properties are found in the PlanGQLType
            }
        }
    }
}

// Variables Sample:
{
  "plan": {
    "siteId": "test-site",
    "name": "test17281q",
    "planCode": "test17281q",
    "billingModel": "PrePaid",
    "description": "",
    "data": "{}",
    "pricingModel": "Fixed",
    "fixedPricing": {
      "price": 144,
      "displayCurrencyConversion": null,
      "taxes": null,
      "extraFees": null
    },
    "variablePricing": null,
    "perUnitPricing": null,
    "setupFee": 12,
    "status": "Active",
    "displaySettings": "{\"description\":{},\"image\":{}}",
    "discountedFrom": null,
    "defaultCurrencyCode": "egp",
    "displayCurrencyCode": null,
    "trialPeriod": {
      "duration": 0,
      "unit": "Day"
    },
    "billingType": "Recurring",
    "planPausingDurations": [],
    "planFutureStarts": [],
    "billingCycle": {
      "unit": "Month",
      "duration": 1,
      "Model" : "StartImmediately",
      "ChangeMode" : "ShiftBillingCycle",
      "CycleStart" : "",
      "termLimit": {
        "cycles": 0,
        "actionOnEnd": "renew"
      },
      "earlyInvoiceCreationSettings": {
        "duration": 0,
        "unit": "Day"
      },
      "dueInvoiceDueSettings": {
        "duration": 3,
        "unit": "Day",
        "action": "DoNothing"
      },
      "usageQuery": null
    },
    "infoFields": [],
    "planRules": {
      "maxTotalAddonsQuantity": null
    },
    "addOns": []
  },
  "siteId": "test-site"
}

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

Update Plan

To update a plan, you need to use the following Mutation:

mutation UpdatePlan($siteId: String!, $planId: String!, $plan: PlanGQLInputType!) {
    plan(siteId: $siteId, planId: $planId) {
        update(plan: $plan) {
            isSuccess
            message
            value {
                id
                #All properties are found in the PlanGQLType
            }
        }
    }
}

// Variables Sample:
{
  "plan": {
    "siteId": "test-site",
    "name": "12121",
    "planCode": "12121",
    "invoiceName": null,
    "imageUrl": null,
    "accountingCode": "accounting code",
    "billingModel": "PrePaid",
    "description": "",
    "data": "{\"taxInvoicing\":{\"sku\":\"12365\",\"item-type\":\"213132\",\"unit-type\":\"432423\",\"integrationId\":\"685EFEA0-165F-42DC-ADB9-D325C51C216A\"},\"canBeChanged\":true,\"calculateCreditNote\":true,\"usageCalculationMode\":\"Both\"}",
    "pricingModel": "Fixed",
    "fixedPricing": {
      "price": 12,
      "displayCurrencyConversion": null,
      "taxes": [
        {
          "type": "Percentage",
          "name": "1212",
          "value": 0.2
        }
      ],
      "extraFees": []
    },
    "variablePricing": null,
    "perUnitPricing": null,
    "setupFee": 12,
    "status": "Active",
    "displaySettings": "{\"image\":{},\"description\":{}}",
    "discountedFrom": null,
    "defaultCurrencyCode": "egp",
    "displayCurrencyCode": null,
    "trialPeriod": {
      "duration": 0,
      "unit": "Day",
      "requiresCreditCard": false
    },
    "billingType": "Recurring",
    "planPausingDurations": [],
    "planFutureStarts": [],
    "billingCycle": {
      "unit": "Month",
      "duration": 1,
      "Model" : "StartImmediately",
      "ChangeMode" : "ShiftBillingCycle",
      "CycleStart" : "",
      "termLimit": {
        "cycles": 12,
        "actionOnEnd": "Renew"
      },
      "earlyInvoiceCreationSettings": {
        "duration": 0,
        "unit": "Day"
      },
      "dueInvoiceDueSettings": {
        "duration": 3,
        "unit": "Day",
        "action": "DoNothing"
      },
      "usageQuery": null
    },
    "infoFields": [
      {
        "name": "name",
        "label": "Full Name",
        "type": "Full Name",
        "validation": ".*\\s+.+",
        "required": true,
        "editable": false,
        "disabled": false
      },
      {
        "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,
        "disabled": false
      },
      {
        "name": "registration",
        "label": "Registration Number/National ID",
        "type": "Text",
        "validation": "",
        "required": true,
        "editable": false,
        "disabled": true
      },
      {
        "name": "tax-number",
        "label": "Tax number",
        "type": "Text",
        "validation": "",
        "required": true,
        "editable": false,
        "disabled": true
      },
      {
        "name": "is-individual",
        "label": "Is Person",
        "type": "Checkbox",
        "validation": "",
        "required": false,
        "editable": false,
        "disabled": true
      },
      {
        "name": "country-iso-code",
        "label": "Country ISO code",
        "type": "Text",
        "validation": "",
        "required": true,
        "editable": false,
        "disabled": true
      }
    ],
    "planRules": {
      "maxTotalAddonsQuantity": null,
      "exactTotalAddonsQuantity": null
    },
    "addOns": [
      {
        "id": "37dfd8b5-b534-464e-98db-77542319c8ef",
        "name": "sssdsadasdasdasd",
        "data": "{\"taxInvoicing\":{\"sku\":\"ssss\",\"item-type\":\"ssss\",\"unit-type\":\"ssss\"}}",
        "code": "sssdsadasdasdasd",
        "description": null,
        "imageUrl": null,
        "status": "Active",
        "billingModel": "PrePaid",
        "billingType": "Recurring",
        "displaySettings": "{\"image\":{},\"description\":{}}",
        "billingCycle": {
          "unit": "Month",
          "duration": 1,
          "termLimit": {
            "cycles": 12,
            "actionOnEnd": "Renew"
          }
        },
        "pricingModel": "Fixed",
        "fixedPricing": {
          "price": 22,
          "required": false,
          "displayCurrencyConversion": null
        },
        "variablePricing": null,
        "perUnitPricing": null
      },
      {
        "id": "3d703b6b-e499-4c28-95c6-5021c48d5088",
        "name": "addon 1",
        "data": "{\"taxInvoicing\":{\"sku\":\"sssss\",\"item-type\":\"ssss\",\"unit-type\":\"sssss\"}}",
        "code": "addon-1",
        "description": null,
        "imageUrl": null,
        "status": "Active",
        "billingModel": "PrePaid",
        "billingType": "Recurring",
        "displaySettings": "{\"image\":{},\"description\":{}}",
        "billingCycle": {
          "unit": "Month",
          "duration": 1,
          "termLimit": {
            "cycles": 12,
            "actionOnEnd": "Renew"
          }
        },
        "pricingModel": "PerUnit",
        "fixedPricing": null,
        "variablePricing": null,
        "perUnitPricing": {
          "pricePerUnit": 150,
          "freeQuantity": 0,
          "unit": "giga",
          "rules": {
            "min": 1,
            "max": 10,
            "step": 1
          },
          "displayCurrencyConversion": null
        }
      }
    ],
    "id": "571a6b8f-0730-4146-b2f5-7a5a6b92279d"
  },
  "planId": "571a6b8f-0730-4146-b2f5-7a5a6b92279d",
  "siteId": "test-site"
}

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

Enable or Disable Change Plan by Customer

To enable or disable the "Change Plan by Customer" feature for a specific plan by modifying its canBeChanged attribute, you will need to follow these steps:

Query the Plan: Use this GraphQL query GetPlan to retrieve the plan information, including the data field.

mutation UpdatePlan($siteId: String!, $planId: String!, $plan: PlanGQLInputType!) {
  plan(siteId: $siteId, planId: $planId) {
    update(plan: $plan) {
      isSuccess
      message
      value {
        planCode
      }
    }
  }
}

Add data Field: This data field should include the canBeChanged flag with the desired value (true or false).

Update Plan with New Flag: Once you have fetched the plan details, modify the data field by adding the canBeChanged flag with a value of true or false. This modification is performed using a mutation UpdatePlan.

For true (indicating "Change Plan by Customer" is enabled):

"data": "{\"canBeChanged\": true}",

For false (indicating "Change Plan by Customer" is disabled):

"data": "{\"canBeChanged\": false}",

Copy Plan

To copy a plan, you need to use the following Mutation:

mutation CopyPlan($siteId: String!, $planId: String!){
    plan(siteId: $siteId, planId: $planId){
        copy{
            isSuccess
            message
            value{
                id
                #All properties are found in the PlanGQLType
            }
        }
    }
}

// Variables Sample:
{
    "siteId": "test-site",
    "planId": "0110d46e-6e33-4817-839d-d600cba83f6b"
}

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

Delete Plan

To delete a plan, you need to use the following Mutation:

mutation DeletePlan($siteId: String!, $planId: String!){
    plan(siteId: $siteId, planId: $planId){
        delete{
            isSuccess
            message
        }
    }
}

// Variables Sample:
{
    "siteId": "test-site",
    "planId": "0110d46e-6e33-4817-839d-d600cba83f6b"
}

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

Api And WebhooksSubscriptions API

Api And WebhooksBilling Cycles API