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
        data{
            id
            #All properties are found in the CustomerGQLType
        }
        message
    } 
}

// Variables Sample:
{
  "siteId": "test-site"
}

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) {
    id
    fullName
  }
#All properties are found in the CustomerGQLType
}

// Variables Sample:
{
  "siteId": "test-site",
  "customerId": "test-site_65950a2940f341dbab60ccf5e47e7d66"
}

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

// Variables Sample:
{
  "siteId": "test-site"
}

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 Wallets Query

query GetCustomerWallets($siteId: String!, $customerId: String!) {
    customer(siteId: $siteId,customerId: $customerId) {
        wallets {
            availableAmount
            onHoldAmount
            totalAmount
            unit
        }
    }
}
#All properties are found in the CustomerGQLType

// Variables Sample:
{
  "siteId": "test-site",
  "customerId": "test-site_65950a2940f341dbab60ccf5e47e7d66"
}

Returns all customer wallets.
You can specify any of the fields detailed in the Customer Type Definition.

Customer Wallet Movements Query

To retrieve the wallet movements of a specific customer, use the query below.

query GetCustomerWalletMovements($siteId: String!, $customerId: String!, $currency: String!) {
    customer(siteId: $siteId, customerId: $customerId) {
        walletMovements(currency: $currency) {
            isSuccess
            message
            value {
                unit
                allowTotalBalanceToBeNegative
                balanceSummary {
                    availableAmount
                    onHoldAmount
                    totalAmount
                    unit
                }
                movements {
                    utcTimestamp
                    amount
                    description
                }
                onHoldAmounts {
                    id
                    amount
                    description
                    expirationDate
                    onHoldDate
                }
            }
        }
    }
}
#All properties are found in the CustomerGQLType

// Variables Sample:
{
  "siteId": "test-site",
  "customerId": "test-site_b05d0a6ee9be492a9d0fc6acb35670d9",
  "currency":"egp"
}

Returns all customer wallet movements.
You can specify any of the fields detailed in the Customer Type Definition.

Customer Wallet On Hold Movements

To retrieve the wallet movements that are on hold for a specific customer, use the query below.

query GetCustomerWalletOnHoldMovements(
    $siteId: String!
    $customerId: String!
    $currency: String!
) {
    customer(siteId: $siteId, customerId: $customerId) {
        walletOnHoldMovements(currency: $currency) {
            isSuccess
            message
            value {
                onHoldAmounts {
                    id
                    amount
                    description
                    expirationDate
                    onHoldDate
                }
            }
        }
    }
}
#All properties are found in the CustomerGQLType

// Variables Sample:
{
  "siteId": "test-site",
  "customerId": "test-site_b05d0a6ee9be492a9d0fc6acb35670d9",
  "currency":"egp"
}

Returns all customer wallet movements that are on hold.
You can specify any of the fields detailed in the Customer Type Definition.

Customer Attachments Query

To retrieve the attachments of a specific customer, use the query below.

query GetCustomerAttachments($siteId: String!, $customerId: String!) {
              customer(siteId: $siteId, customerId: $customerId) {
                attachments {
                  fileName
                  externalFileName
                  createdAtUtc
                  fileSizeKb
                  canBeDeleted
                }
              }
            }
#All properties are found in the CustomerGQLType

// Variables Sample:
{
  "siteId": "test-site",
  "customerId": "test-site_b05d0a6ee9be492a9d0fc6acb35670d9"
}

Returns an array of all customer attachments.
You can specify any of the fields detailed in the Customer Type Definition.

Account Statement Query

To retrieve the account statement for a specific customer, use the query below.

query GetAccountStatement($siteId: String!, $customerId: String!, $currency: String! ) {
customer(siteId: $siteId, customerId: $customerId) {
   accountMovements(currency: $currency) {
     isSuccess
     message
     data {
       utcTimestamp
       amount
       netBalance
       description
     }
   }
}
}
#All properties are found in the CustomerGQLType

// Variables Sample:
{
  "siteId": "test-site",
  "customerId": "test-site_b05d0a6ee9be492a9d0fc6acb35670d9"
}

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

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

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 Sample:
{
  "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 Sample:
{
    "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 Sample:
{
  "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 RequestCustomerPaymentMethodMutation(
  $siteId: String!
  $customerId: String!
  $relatedEntity: String
  $relatedEntityId: String
  $currency: String
) {
  requestCustomerPaymentMethod(
    siteId: $siteId
    customerId: $customerId
    relatedEntity: $relatedEntity
    relatedEntityId: $relatedEntityId
    currency: $currency
  ) {
    isSuccess
    message
  }
}

// Variables Sample:
{
  "siteId": "test-site",
  "customerId": "test-site_17067140722304404667",
  "relatedEntity": "PaymentSchedule",
  "relatedEntityId": "a791fc54-2cf1-4157-8d64-86dd1a17d02e"
}

Request Customer to Update Payment Method

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

mutation RequestCustomerToUpdatePaymentMethodMutation($siteId: String!, $customerId: String!, $paymentMethodId: String!) {
  requestCustomerToUpdatePaymentMethod(siteId: $siteId, customerId: $customerId, paymentMethodId: $paymentMethodId ) {
    isSuccess
    message
  }
}

// Variables Sample:
{
    "siteId": "test-site",
    "customerId": "test-site_2cceaf460f1a4ba5a8641730d93833c6",
    "paymentMethodId": "6d71db02-4a52-468b-9abe-3654530b8d88"
}

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 Sample:
{
    "siteId": "test-site",
    "customerId": "test-site_16695396023274150885",
    "paymentMethodId": "d383cea0-71fe-4311-9f32-3c91947009f6"
}

The default payment method cannot be removed using this mutation.

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

Customer Wallets

Add Customer Wallet

To add a new wallet to your customer, you need to use the following Mutation:

mutation AddCustomerWallet($siteId: String!, $customerId: String!, $currency: String!, $balance: Long!) {
    customer(siteId: $siteId, customerId: $customerId) {
        wallets {
            add(currency: $currency, balance: $balance) {
                isSuccess
                message
            }
        }
    }
}

// Variables Sample:
{
    "siteId": "Your Site Id",
    "customerId": "<your siteId>_6113eee4a4a44499b7bcf03b4c94cab3",
    "currency":"egp",
    "balance": 1000
}

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

Top Up Customer Wallet

To top up your customer wallet, you need to use the following Mutation:

mutation Topup Customer Wallet(
    $siteId: String!
    $customerId: String!
    $currency: String!
    $amount: Decimal!
) {
    customer(siteId: $siteId, customerId: $customerId) {
        wallet(currency: $currency) {
            topUp(amount: $amount) {
                isSuccess
                message
            }
        }
    }
}

// Variables Sample:
{
    "siteId": "Your Site Id",
    "customerId": "<your siteId>_6113eee4a4a44499b7bcf03b4c94cab3",
    "currency":"egp",
    "amount": 100
}

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

Release Customer Wallet On Hold Amount

To release an on hold amount in the customer wallet, you need to use the following Mutation:

mutation ReleaseCustomerWalletOnHoldAmount(
    $siteId: String!
    $customerId: String!
    $currency: String!
    $onHoldAmountId: String!
) {
    customer(siteId: $siteId, customerId: $customerId) {
        wallet(currency: $currency) {
            releaseOnHold(onHoldAmountId: $onHoldAmountId) {
                isSuccess
                message
            }
        }
    }
}

// Variables Sample:
{
    "siteId": "Your Site Id",
    "customerId": "<your siteId>_6113eee4a4a44499b7bcf03b4c94cab3",
    "currency":"egp",
    "onHoldAmountId": "06403622-95C9-445A-BE59-3BCB63717644"
}

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

Mark Invoice As Paid With Wallet

To mark an invoice as paid using the customer wallet, you need to use the following Mutation:

mutation MarkInvoiceAsPaidWithWallet($siteId: String!, $invoiceId: String!, $amount: Decimal!) {
    invoice(siteId: $siteId, invoiceId: $invoiceId) {
        markAsPaidWithWallet(amount: $amount) {
            isSuccess
            message
        }
    }
}

// Variables Sample:
{
    "siteId": "Your Site Id",
    "invoiceId": "invoice id",
    "amount":  500 //amount to be deducted from the wallet
}

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

Transafer Wallet Balance

To transfer funds from a wallet to another, you need to use the following Mutation:

mutation TransaferWalletBalance(
$siteId: String!,
$currency: String!, 
$amount: Decimal!,
$customerId: String!,
$comment: String,
$toCustomerId: String!,
$toCurrencyCode: String!,
$conversionRate: Decimal)
{
customer(siteId: $siteId, customerId: $customerId) {
    wallet(currency: $currency) {
      transfer(
        toCustomerId:  $toCustomerId,
        toCurrencyCode: $toCurrencyCode,
        conversionRate: $conversionRate,
      amount: $amount,
      comment:$comment) 
      {
        isSuccess
        message
      }
    }
  }
}

Api And WebhooksAuthentication

Api And WebhooksSubscriptions API