Invoices API

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

Invoice Queries

Invoices Query

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

Request Variables Sample:

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

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

Invoice Query

query GetInvoice($siteId: String!,$invoiceId: String!) { 
    invoice (siteId: $siteId,invoiceId: $invoiceId) {
        siteId
        id
        number
        #All properties are found in the InvoiceGQLType
    } 

### variables
{"siteId":"","invoiceId":""}

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

Invoices by Id

query GetInvoicesById($siteId: String!,$ids: [String]!,$pagination: PaginationGQLInputType,$sorting: [SortingGQLInputType]) { 
    invoicesById (siteId: $siteId,ids: $ids,pagination: $pagination,sorting: $sorting) {
        isSuccess
        pagination
        data{
            id
            #All properties are found in the InvoiceGQLType
        }
        message
    } 
}

### variables
{"siteId":"","ids":"","pagination":"","sorting":""}

Return an array of invoices by Id.
You can specify any of the fields detailed in the Invoice Type Definition.
For details about Pagination, Sorting, and Filtering Input Types, please check out PaginationGQLInputType, SortingGQLInputType, FilteringGQLInputType.

Download Proforma Invoice

query DownloadProformaInvoice($siteId: String!, $billingCycleId: Guid!) {
    downloadProformaInvoice(siteId: $siteId, billingCycleId: $billingCycleId) {
        isSuccess
        message
        value {
            id
            billedOn
            paidOn
            createdOn
            dueOn
            url
            relatedEntity
            data
            attachments {
                fileName
                externalFileName
                createdAtUtc
                fileSizeKb
                canBeDeleted
            }
            transactions {
                id
                amount
                type
                currency
                referenceNumber
                paymentMethod {
                    displayText
                    type
                }
                status
                timestamp
                utcTimestamp
            }
            details {
                currency
                comments
                header
                footer
                lineItems {
                    item
                    quantity
                    unitPrice
                    total
                }
                discounts {
                    amount
                    description
                    order
                }
                taxes {
                    amount
                    description
                    order
                }
                extraFees {
                    amount
                    description
                    order
                }
                paymentDetails
                terms
            }
            paymentInfo {
                paymentAttempts {
                    succeeded
                    transactionId
                    utcTimestamp
                }
            }
            number
            status
            subTotal
            outstandingBalance
            total
            customer {
                customerId
            }
        }
    }
}

### variables

{
  "siteId": "test-site",
  "billingCycleId": "a64f4100-b99b-423e-abc1-85998b983d1e"
}

Downloads a specific proforma invoice on demand.

Download Tax Invoice

query DownloadTaxInvoice($siteId: String!,$invoiceId: String!) { 
    downloadTaxInvoice (siteId: $siteId,invoiceId: $invoiceId) {
        isSuccess
        value {
            name
            #All properties are found in the TaxInvoiceDataGQLType
        }
        message
    } 
}

### variables
{"siteId":"","invoiceId":""}

Downloads a specific tax invoice.
You can specify any of the fields detailed in the Tax Invoice Data Type Definition.

Invoice Mutations

Create Invoice From Draft

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

mutation CreateInvoiceFromDraft(
    $siteId: String!
    $invoiceFromDraft: InvoiceFromDraftGQLInputType!
) {
    invoice(siteId: $siteId) {
        createFromDraft(invoiceFromDraft: $invoiceFromDraft) {
            isSuccess
            message
            value {
                id
                #All properties are found in the InvoiceGQLType
            }
        }
    }
}

### variables
{
    "siteId": "test-site",
    "invoiceFromDraft": {
        "draftInvoiceId": "745c906e-88e3-4812-b79a-5701f4ac0ac0",
        "billedOn": "2023-06-06T21:00:00.000Z",
        "dueOn": "2023-06-06T21:00:00.000Z"
    }
}

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

Mark Invoice as Paid

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

mutation MarkInvoiceAsPaid($siteId: String!, $invoiceId: String!, $sitePaymentMethodId: String!, $amount: Decimal, $conversionRate: Decimal, $currencyCode: String, $date: DateTime) {
  invoice(siteId: $siteId, invoiceId: $invoiceId) {
    markAsPaid(
      sitePaymentMethodId: $sitePaymentMethodId
      amount: $amount
      conversionRate: $conversionRate
      currencyCode: $currencyCode
      date: $date
    ) {
      isSuccess
      message
    }
  }
}

### variables

{
  "siteId": "test-site",
  "invoiceId": "f04890d6-d8b6-48d5-b85d-2b4131b31749",
  "sitePaymentMethodId": "15614fae-98d6-4247-8f48-3bfaedb65adf",
  "amount": 100,
  "conversionRate": 50,
  "currencyCode": "usd",
  "date": "2024-08-11T00:00:00.000Z"
}

Returns a result with a success message:

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

Split Invoice Payments

To split an invoice into scheduled payments, use the following mutation:

mutation SplitInvoicePayments(
              $siteId: String!
              $invoiceId: String!
              $selectedPaymentMethodId: String
              $scheduledPayments: [ScheduledPaymentGQLInputType]
            ) {
              invoice(invoiceId: $invoiceId, siteId: $siteId) {
                splitPayments(
                  selectedPaymentMethodId: $selectedPaymentMethodId
                  scheduledPayments: $scheduledPayments
                ) {
                  isSuccess
                  message
                }
              }
            }

### variables
{
  "siteId": "yourSiteId",
  "invoiceId": "yourInvoiceId",
  "selectedPaymentMethodId": "paymentMethodId123",
  "scheduledPayments": [
    {
      "amount": 100.0,
      "dueDate": "2024-01-01",
      "paymentMethodId": "paymentMethodId123"
    },
    {
      "amount": 200.0,
      "dueDate": "2024-02-01",
      "paymentMethodId": "paymentMethodId456"
    }
  ]
}

Settle Invoices

To automatically settles all invoices that can be settled using wallet balances for each currency, with separate wallets handling different currencies, you need to use the following Mutation:

mutation SettleCustomerInvoicesFromWallet($siteId: String!, $customerId: String!) {
              customer(siteId: $siteId, customerId: $customerId) {
                invoices {
                  settleFromWallet {
                    isSuccess
                    message
                  }
                }
              }
            }

### variables
{
  "siteId": "yourSiteId",
  "customerId": "c2758725-4739-44bb-9f30-53f8a3a0376d"
}

Void an Invoice

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

mutation VoidInvoice($siteId: String!, $invoiceId: String!) {
    invoice(siteId: $siteId, invoiceId: $invoiceId) {
        void {
            isSuccess
            message
        }
    }
}   

### variables
{
  "siteId": "test-site",
  "invoiceId": "9db16591-3a97-45f6-8f77-de462736efaf"
}

Push Invoice

To manually push an invoice to one of the 3rd parties Subsbase is integrating with, such as tax invoicing or accounting platforms, you need to use the following Mutation:

mutation PushInvoice(
    $siteId: String!
    $invoiceId: String!
    $category: String!
) {
    invoice(siteId: $siteId, invoiceId: $invoiceId) {
        pushTo(category: $category) {
            isSuccess
            message
        }
    }
}

### variables
{
  "siteId": "test-site",
  "invoiceId": "9db16591-3a97-45f6-8f77-de462736efaf",
  "category": "tax-invoicing"
}

Request Invoice Payment

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

mutation RequestInvoicePayment(
    $siteId: String!
    $invoiceId: String!
    $paymentMethodId: String
) {
    invoice(siteId: $siteId, invoiceId: $invoiceId) {
        requestPaymentUsing(paymentMethodId: $paymentMethodId) {
            isSuccess
            message
        }
    }
}

### variables
{
  "siteId": "test-site",
  "invoiceId": "ea41dbb8-0133-44f3-8370-28c13c7d3011"
}

Send Payment Link

To send a payment link for an invoice, you need to use the following Mutation:

mutation SendPaymentLink($siteId: String!, $invoiceId: String!) {
    invoice(siteId: $siteId, invoiceId: $invoiceId) {
        sendPaymentLink {
            isSuccess
            message
        }
    }
}

### variables
{
  "siteId": "test-site",
  "invoiceId": "ea41dbb8-0133-44f3-8370-28c13c7d3011"
}

Add Discount

To add a discount to an invoice, you need to use the following Mutation:

mutation AddDiscount($siteId: String!, $invoiceId: String!, $amount: Decimal!) {
    invoice(siteId: $siteId, invoiceId: $invoiceId) {
        discounts {
            add(amount: $amount) {
                isSuccess
                message
            }
        }
    }
}

### variables
{
  "siteId": "test-site",
  "invoiceId": "c2758725-4739-44bb-9f30-53f8a3a0376d",
  "amount": -14.76
}

Remove Discounts

To remove a discount from an invoice, you need to use the following Mutation:

mutation RemoveDiscount($siteId: String!, $invoiceId: String!, $amount: Decimal!) {
    invoice(siteId: $siteId, invoiceId: $invoiceId) {
        discounts {
            remove(amount: $amount) {
                isSuccess
                message
            }
        }
    }
}

### variables
{
  "siteId": "test-site",
  "invoiceId": "c2758725-4739-44bb-9f30-53f8a3a0376d",
  "amount": -14.76
}

Update Discounts

To update a discount in an invoice, you need to use the following Mutation:

mutation UpdateDiscount($siteId: String!, $invoiceId: String!, $amounts: [Decimal]!) {
    invoice(siteId: $siteId, invoiceId: $invoiceId) {
        discounts {
            update(amounts: $amounts) {
                isSuccess
                message
            }
        }
    }
}

### variables
{
  "siteId": "test-site",
  "invoiceId": "28d8718d-93fc-4621-990b-6bf2b291ffbd",
  "amounts": [
    -22
  ]
}

Draft Invoice Queries

Draft Invoices Query

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

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

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

Draft Invoice Query

query GetDraftInvoice($siteId: String!,$draftInvoiceId: String!) { 
    draftInvoice (siteId: $siteId,draftInvoiceId: $draftInvoiceId) {
        siteId
        id
        #All properties are found in the DraftInvoiceGQLType
    }

### variables
{"siteId":"","draftInvoiceId":""}

Returns the specific draft invoice.
You can specify any of the fields detailed in the Draft Invoice Type Definition.

Draft Invoice Mutations

Create Draft Invoice

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

mutation CreateDraftInvoice(
    $siteId: String!
    $draftInvoice: DraftInvoiceGQLInputType!
) {
    draftInvoices(siteId: $siteId) {
        create(draftInvoice: $draftInvoice) {
            isSuccess
            message
            value{
                id
                #All properties are found in the DraftInvoiceGQLType
            }
        }
    }
}

### variables
{
  "siteId": "test-site",
  "draftInvoice": {
    "siteId": "test-site",
    "customerId": "4ba83e86-caa5-498b-aaa6-b0d209f62396",
    "billedOn": "2023-06-06T21:00:00.000Z",
    "dueOn": "2023-06-06T21:00:00.000Z",
    "details": {
      "terms": null,
      "currency": "egp",
      "lineItems": [
        {
          "item": "item1",
          "quantity": 1,
          "unitPrice": 50,
          "total": 50,
          "data": "{\"sku\":\"\"}"
        }
      ],
      "discounts": [],
      "taxes": [],
      "extraFees": [],
      "billingInfo": {
        "email": "johnsmith@mail.com",
        "lastName": "Smith",
        "firstName": "John",
        "address": {
          "countryCode": "US",
        "city": "New York",
        "province": "New York",
        "postalCode": "10001",
        "line1": "123 Main Street",
        "line2": "Apartment 456"
        }
      }
    },
    "data": null
  }
}

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

Create Draft Invoice From Template

To create a draft invoice from template, you need to use the following Mutation:

mutation CreateDraftInvoiceFromTemplate(
    $siteId: String!
    $draftFromInvoice: DraftFromInvoiceGQLInputType!
) {
    draftInvoices(siteId: $siteId) {
        createFromInvoice(draftFromInvoice: $draftFromInvoice) {
            isSuccess
            message
            value{
                id
                #All properties are found in the DraftInvoiceGQLType
            }
        }
    }
}

### variables
{
  "siteId": "test-site",
  "draftInvoiceId": "f7f7cb6a-a51c-4afb-9d07-14beac13e817",
  "draftInvoice": {
    "siteId": "test-site",
    "customerId": "0008c2e2-584d-4346-b4f0-ff7831b2c0a5",
    "billedOn": "2023-02-28T22:00:00.000Z",
    "dueOn": "2023-03-20T22:00:00.000Z",
    "details": {
      "terms": null,
      "comments": null,
      "currency": "egp",
      "lineItems": [
        {
          "item": "test",
          "quantity": 4,
          "unitPrice": 10,
          "total": 40,
          "data": "{\"sku\":\"\"}"
        }
      ],
      "discounts": [],
      "taxes": [],
      "extraFees": [],
      "billingInfo": {
        "email": "johnsmith@mail.com"
      }
    },
    "data": null
  }
}

Update Draft Invoice

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

mutation UpdateDraftInvoice(
    $siteId: String!
    $draftInvoiceId: String!
    $draftInvoice: DraftInvoiceGQLInputType!
) {
    draftInvoice(siteId: $siteId, draftInvoiceId: $draftInvoiceId) {
        update(draftInvoice: $draftInvoice) {
            isSuccess
            message
        }
    }
}

### variables
{
  "siteId": "test-site",
  "draftInvoiceId": "745c906e-88e3-4812-b79a-5701f4ac0ac0",
  "draftInvoice": {
    "siteId": "test-site",
    "billedOn": "2023-06-05T21:00:00.000Z",
    "dueOn": "2023-06-05T21:00:00.000Z",
    "details": {
      "terms": null,
      "comments": null,
      "currency": "egp",
      "lineItems": [
        {
          "item": "item1",
          "quantity": 1,
          "unitPrice": 501,
          "total": 501,
          "data": "{\"sku\":\"\"}"
        }
      ],
      "discounts": [],
      "taxes": [],
      "extraFees": [],
      "billingInfo": {
        "email": "email@email.com"
      }
    },
    "data": null
  }
}

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

Delete Draft Invoice

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

mutation DeleteDraftInvoice(
    $siteId: String!
    $draftInvoiceId: String!
) {
    draftInvoice(siteId: $siteId, draftInvoiceId: $draftInvoiceId) {
        delete {
            isSuccess
            message
        }
    }
}

### variables
{
  "siteId": "test-site",
  "draftInvoiceId": "8bd04bf3-6c69-4c7c-ab5d-924a9078b085"
}

One-Time Payments Query

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

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

Returns an array of 'one-time payment' links.
You can specify any of the fields detailed in the One Time Payment Type Definition.
For details about Pagination, Sorting, and Filtering Input Types, please check out PaginationGQLInputType, SortingGQLInputType, FilteringGQLInputType.

One-Time Payment Mutations

Create One-Time Payment

mutation CreateOneTimePayment(
    $siteId: String!
    $oneTimePayment: OneTimePaymentGQLInputType!
) {
    oneTimePayments(siteId: $siteId) {
        create(oneTimePayment: $oneTimePayment) {
            isSuccess
            message
            value {
                id
                #All properties are found in the OneTimePaymentGQLType
            }
        }
    }
}

### variables
{
  "siteId": "test-site",
  "oneTimePayment": {
    "siteId": "test-site",
    "name": "test11",
    "code": "test11",
    "currencyCode": "egp",
    "info": {
      "discounts": null,
      "taxes": null,
      "extraFees": null,
      "infoFields": [
        {
          "label": "Full Name",
          "name": "name",
          "validation": ".*\\s+.+",
          "required": true,
          "type": "Full Name",
          "editable": false
        },
        {
          "label": "Email",
          "name": "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,
          "type": "Email",
          "editable": false
        }
      ],
      "lineItems": []
    },
    "status": "Active",
    "data": null
  }
}

Update One-Time Payment

mutation UpdateOneTimePayment(
    $siteId: String!
    $id: String!
    $oneTimePayment: OneTimePaymentGQLInputType!
) {
    oneTimePayment(siteId: $siteId, id: $id) {
        update(oneTimePayment: $oneTimePayment) {
            isSuccess
            message
        }
    }
}

### variables
{
  "siteId": "test-site",
  "id": "371d5650-e6c4-42b4-821a-ea5b94085cbc",
  "oneTimePayment": {
    "siteId": "test-site",
    "name": "test11",
    "code": "test11",
    "currencyCode": "egp",
    "info": {
      "discounts": null,
      "taxes": [
        {
          "type": "FixedAmount",
          "name": "",
          "value": 0
        }
      ],
      "extraFees": [
        {
          "type": "FixedAmount",
          "name": "",
          "value": 0
        }
      ],
      "infoFields": [
        {
          "name": "name",
          "label": "Full Name",
          "type": "Full Name",
          "validation": ".*\\s+.+",
          "required": true,
          "editable": 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
        }
      ],
      "lineItems": [
        {
          "item": "item1",
          "pricingModel": "Fixed",
          "fixedPricing": {
            "price": 12,
            "required": false
          },
          "variablePricing": null,
          "perUnitPricing": null,
          "data": "{\"sku\":\"\"}"
        }
      ]
    },
    "status": "Active",
    "data": null
  }
}

Delete One-Time Payment

mutation DeleteOneTimePayment($siteId: String!, $oneTimePaymentId: String!){
  oneTimePayment(siteId: $siteId, id: $oneTimePaymentId){
    delete{
      isSuccess
      message
    }
  }
}

### variables
{
  "siteId": "test-site",
  "oneTimePaymentId": "7176b10a-a035-4e09-8361-5afcf2c1f235"
}

Api And WebhooksCampaigns API

Api And WebhooksTransactions API