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.