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.

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

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

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

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

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

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

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

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!
) {
    invoice(siteId: $siteId, invoiceId: $invoiceId) {
        markAsPaid(
            sitePaymentMethodId: $sitePaymentMethodId
        ) {
            isSuccess
            message
        }
    }
}

### variables
{
  "siteId": "test-site",
  "invoiceId": "c2758725-4739-44bb-9f30-53f8a3a0376d",
  "sitePaymentMethodId": "15614fae-98d6-4247-8f48-3bfaedb65adf"
}
  • Returns a result with a success message:
{
  "data": {
    "markInvoiceAsPaid": {
      "isSuccess": true,
      "message": ""
      }
    }
  }

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

Update Narrative

  • To update narrative in an invoice, you need to use the following Mutation:
mutation UpdateNarrative(
    $siteId: String!
    $invoiceId: String!
    $header: String!
    $footer: String!
    $comments: String!
) {
    invoice(siteId: $siteId, invoiceId: $invoiceId) {
        narrative {
            update(header: $header, footer: $footer, comments: $comments) {
                isSuccess
                message
            }
        }
    }
}

### variables
{
  "siteId": "test-site",
  "invoiceId": "c2758725-4739-44bb-9f30-53f8a3a0376d",
  "header": "<p>test</p>",
  "comments": "",
  "footer": ""
}

Draft Invoices

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

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

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

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
  }
}
Table of Contents