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

query GetCustomerWallets($siteId: String!, $customerId: String!) {
    customer(siteId: $siteId,customerId: $customerId) {
        wallets {
            availableAmount
            onHoldAmount
            totalAmount
            unit
        }
    }
}

### variables
{
    "siteId": "Your Site Id",
    "customerId": "<your siteId>_6113eee4a4a44499b7bcf03b4c94cab3"
}

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

Customer Wallet Movements Query

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

### variables
{
    "siteId": "Your Site Id",
    "customerId": "<your siteId>_6113eee4a4a44499b7bcf03b4c94cab3",
    "currency":"egp"
}

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

Customer Wallet On Hold Movements

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

### variables
{
    "siteId": "Your Site Id",
    "customerId": "<your siteId>_6113eee4a4a44499b7bcf03b4c94cab3",
    "currency":"egp"
}

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

Customer Attachments Query

query GetCustomerAttachments($siteId: String!, $customerId: String!) {
              customer(siteId: $siteId, customerId: $customerId) {
                attachments {
                  fileName
                  externalFileName
                  createdAtUtc
                  fileSizeKb
                  canBeDeleted
                }
              }
            }

Returns an array of 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
     }
   }
}
}

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

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

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

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

Api And WebhooksAuthentication

Api And WebhooksSubscriptions API