Customers API

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

Queries

Customers Query

query GetCustomers($siteId: String!,$filter: FilterGQLInputType,$pagination: PaginationGQLInputType,$sorting: [SortingGQLInputType]) { 
    customers (siteId: $siteId,filter: $filter,pagination: $pagination,sorting: $sorting) {
        isSuccess
        pagination
        data{
            id
            #All properties are found in the CustomerGQLType
        }
        message
    } 
}

Request Variables Sample:

{
  "siteId": "Your site ID",
  "pagination": {
    "page": 1,
    "perPage": 10,
  },
  "sorting": [
    {
      "field": "lastName",
      "direction": "Ascending",
    },
  ],
  "filter": [
    {
      "field": "firstName",
      "operator": "Contains",
      "value": "John",
    },
  ],
}

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

Customer Query

query GetCustomer($siteId: String!,$customerId: String!) { 
    customer (siteId: $siteId,customerId: $customerId) {
        siteId
        id
        customerId
        #All properties are found in the CustomerGQLType
    } 
    
### variables
{
  "siteId": "test-site",
  "customrId": "test-site_4c622d23b77540cdab092c3d7e3a96ec"
}

Returns a specific customer.
You can specify any of the fields detailed in the Customer Type Definition.

AddOns Query

query GetAddons($siteId: String!,$filter: FilterGQLInputType,$pagination: PaginationGQLInputType,$sorting: [SortingGQLInputType]) { 
    addons (siteId: $siteId,filter: $filter,pagination: $pagination,sorting: $sorting) {
        isSuccess
        data{
            id
            #All properties are found in the AddonGQLType
        }
        message
    } 
}

Request Variables Sample:

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

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

Customer Mutations/Operations

Create Customer

To create a customer, 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 CreateCustomer($siteId: String!, $customer: CustomerGQLInputType!) {
    customers(siteId: $siteId) {
        create(customer: $customer) {
            isSuccess
            message
            value {
                customerId
                firstName
                lastName
                emailAddress
        #All properties are found in the CustomerGQLType
            }
        }
    }
}

Returns a result with the new customer as its value:

{
  "data": {
    "createCustomer": {
      "isSuccess": true,
      "message": "",
      "value": {
        "customerId": "your_siteID_123",
        "firstName": "john doe",
        "lastName": "Doe",
        "emailAddress": "email@email.com"
      }
    }
  }
}

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

Understanding customer variables

Variables	Type
emailAddress	string
firstName	string
lastName	string
customerId	auto-generated (if not specified)

Update Customer ID

This operation updates the customer ID on Subsbase.
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}

To update existing customer data, you need to use the following Mutation:

mutation UpdateCustomerId(
    $siteId: String!
    $customerId: String!
    $newCustomerId: String!
) {
    customer(siteId: $siteId, customerId: $customerId) {
        customerId {
            update(newCustomerId: $newCustomerId) {
                isSuccess
                message
                value
            }
        }
    }
}

### variables
{
  "siteId": "test-site",
  "customrId": "test-site_4c622d23b77540cdab092c3d7e3a96ec",
  "newCustomerId": "test-site_4c622d23b77540cdab092c3d7e3a99eb"
}

You can specify any of the fields detailed in the Customer Type Definition.
Returns a result with a success message:

{
  "data": {
    "updateCustomerId": {
      "isSuccess": true,
      "message": "",
      "value": "{New_Value}"
    }
  }
}

Update Customer InfoFields

This operation updates the infofields of an existing customer.
To update existing customer data, 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 UpdateCustomerInfoFields(
    $siteId: String!
    $customerId: String!
    $infoFields: [CustomerInfoFieldGQLInputType]!
) {
    customer(siteId: $siteId, customerId: $customerId) {
        infoFields {
            update(infoFields: $infoFields) {
                isSuccess
                message
            }
        }
    }
}

### variables
{
    "siteId": "test-site",
    "customerId": "test-site_4c622d23b77540cdab092c3d7e3a96ec",
    "infoFields": [
        {
            "name": "address",
            "value": "Cairo",
            "label": "Address"
        }
    ]
}

You can use customer infoFields from CustomerInfoFieldGQLInputType.
Returns a result with a success message:

{
  "data": {
    "updateInfoFields": {
      "isSuccess": true,
      "message": ""
    }
  }
}

Update Customer Custom Fields

This operation updates the custom fields of an existing customer.
To update existing customer data, you need to use the following Mutation:

mutation UpdateCustomerCustomFields(
    $siteId: String!
    $customerId: String!
    $customFields: [KeyValuePairGQLInputType]
) {
    customer(siteId: $siteId, customerId: $customerId) {
        customFields {
            update(customFields: $customFields) {
                isSuccess
                message
            }
        }
    }
}

### variables
{
  "siteId": "test-site",
  "customerId": "test-site_b5ef7415bf3144e9ba0f92f2325dba84",
  "customFields": [
    {
      "key": "Address",
      "value": "Cairo"
    }
  ]
}

Payment Methods

Request Customer Payment Method

To request a customer to add a payment method, you need to use the following Mutation:

mutation RequestCustomerPaymentMethod(
    $siteId: String!
    $customerId: String!
) {
    customer(siteId: $siteId, customerId: $customerId) {
        requestCustomerPaymentMethod(siteId: $siteId, customerId: $customerId) {
            isSuccess
            message
        }
    }
}

### variables
{
    "siteId": "test-site",
    "customerId": "test-site_16695396023274150885",
}

Remove Customer Payment Method

To remove a payment method from an existing customer, you need to use the following Mutation:

mutation RemoveCustomerPaymentMethod(
    $siteId: String!
    $customerId: String!
    $paymentMethodId: String!
) {
    customer(siteId: $siteId, customerId: $customerId) {
        paymentMethod(paymentMethodId: $paymentMethodId) {
            remove {
                isSuccess
                message
            }
        }
    }
}

### variables
{
    "siteId": "test-site",
    "customerId": "test-site_16695396023274150885",
    "paymentMethodId": "d383cea0-71fe-4311-9f32-3c91947009f6"
}

The default payment method cannot be removed using this mutation.

Subscription

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

Customize Addons

To customize addons in a plan a customer is subscribed to, you need to use the following Mutation:

mutation CustomizePlanSubscriptionAddons(
    $siteId: String!
    $customerId: String!
    $planSubscriptionId: String!
    $addonsQuantity: [KeyValuePairGQLInputType!]
) {
    customer(siteId: $siteId, customerId: $customerId) {
        subscription(planSubscriptionId: $planSubscriptionId) {
            customizeAddons(addonsQuantity: $addonsQuantity) {
                isSuccess
                message
                value {
                    checkoutUrl
                    ##All properties are found in the CustomizePlanSubscriptionAddonsResultGQLType
                }
            }
        }
    }
}

### variables
{
  "siteId": "test-site",
  "customerId": "test-site_9419857bac4a4e77aa9b12c1dfe39725",
  "planSubscriptionId": "de2afc17-0419-4e8a-8132-e1150f6481cd",
  "addonsQuantity": [
    {
      "key": "3d703b6b-e499-4c28-95c6-5021c48d5088",
      "value": 6
    }
  ]
}

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

Payment Schedules

Create Customer Payment Schedules

To create a payment schedule, you need to use the following Mutation:

mutation CreateCustomerPaymentSchedules(
    $siteId: String!
    $customerId: String!
    $paymentSchedule: PaymentScheduleGQLInputType!
) {
    customer(siteId: $siteId, customerId: $customerId) {
        paymentSchedules {
            create(paymentSchedule: $paymentSchedule) {
                isSuccess
                message
                value {
                    siteId
                    id
                }
            }
        }
    }
}

### variables
{
    "siteId": "test-site",
    "customerId": "test-site_c5f19dd38d4840ce831d85e0326e58dd",
    "paymentSchedule": {
        "siteId": "test-site",
        "name": "name",
        "product": "product",
        "currencyCode": "sar",
        "paymentMethod": {
            "id": "341fd466-38f0-46a7-850f-afeaa526555b",
            "displayText": "8769",
            "isDefault": true,
            "type": "Visa Card",
            "metaData": null,
            "identifier": "",
            "providerReference": null,
            "sitePaymentMethodId": "",
            "billingInfo": null
        },
        "data": {
            "invoicing": "InvoicePerPayment",
            "allowPaymentMethodChange": true
        },
        "scheduledPayments": [
            {
                "name": "3 #1",
                "date": "2023-05-08T21:00:00.000Z",
                "amount": 3,
                "siteId": "test-site",
                "status": "NotPaid"
            },
            {
                "name": "3 #2",
                "date": "2023-11-08T22:00:00.000Z",
                "amount": 3,
                "siteId": "test-site",
                "status": "NotPaid"
            },
            {
                "name": "3 #3",
                "date": "2024-05-08T21:00:00.000Z",
                "amount": 3,
                "siteId": "test-site",
                "status": "NotPaid"
            }
        ]
    }
}

You can specify any of the fields detailed in the Payment Schedules.

Create Customer Payment Schedules From Template

To create a payment schedule from an already existing template, you need to use the following Mutation:

mutation CreateCustomerPaymentSchedulesFromTemplate(
    $siteId: String!
    $customerId: String!
    $paymentScheduleFromTemplate: PaymentScheduleFromTemplateGQLInputType!
) {
    customer(siteId: $siteId, customerId: $customerId) {
        paymentSchedules {
            createFromTemplate(
                paymentScheduleFromTemplate: $paymentScheduleFromTemplate
            ) {
                isSuccess
                message
            }
        }
    }
}

### variables
{
    "siteId": "test-site",
    "customerId": "test-site_341f7f56d2304428a19c85b6d6274322",
    "paymentScheduleFromTemplate": {
        "paymentScheduleTemplateId": "b54b9110-2627-45fd-a6d8-fa9374cb4578",
        "customerId": "test-site_341f7f56d2304428a19c85b6d6274322",
        "baseDate": "2023-02-28T22:00:00.000Z",
        "baseAmount": 20,
        "currencyCode": "egp",
        "product": "test-schedule-payment2",
        "selectedPaymentMethodId":"9392e570-f006-41c0-bbba-8705ce0030b8" 
    }
}

You can specify any of the fields detailed in the Payment Schedule Template.

Invoices

Create Customer Invoice

To create an invoice, you need to use the following Mutation:

mutation CreateCustomerInvoice(
    $siteId: String!
    $customerId: String!
    $invoice: InvoiceGQLInputType!
) {
    customer(siteId: $siteId, customerId: $customerId) {
        invoices {
            create(invoice: $invoice) {
                isSuccess
                message
                value {
                    id
                    siteId
                    billedOn
                    dueOn
                    #all other values...
                }
            }
        }
    }
}

### variables
{
   "siteId": "test-site",
    "customerId": "test-site_4c622d23b77540cdab092c3d7e3a96ec",
    "invoice": {
        "siteId": "test-site",
        "customerId": "test-site_4c622d23b77540cdab092c3d7e3a96ec",
        "number": "21221",
        "billedOn": "2023-06-06T21:00:00.000Z",
        "dueOn": "2023-06-06T21:00:00.000Z",
        "details": {},
        "status": "Open"
    }
}

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

Api And WebhooksAuthentication

Api And WebhooksInvoices API