Invoices

Our billing APIs give insight into the accrued usage and amounts due on a per-user basis. There are three relevant queries: invoice, invoicePreview and profiles.

Examples

Authentication is required for these queries. If you do not have your credentials, please contact our ecosystem team directly.

Listing profiles

A profile represents an identity which has usage in the current billing period. This example selects the first 100 profiles with usage for January 2019, where $startDate is "2019-01-01T00:00:00Z" and $endDate is "2019-01-01T23:59:59Z"

{
  profiles(first: 100, withUsage:{start:$startDate end:$endDate}){
    pageInfo {
      endCursor
      hasNextPage
    }
    edges {
      cursor
      node {
        id
        subject
      }
    }
  }
}

Invoice Previews

An invoicePreview is the object that shares the current estimated usage for a given user, where $subject is retrieved from one of the records returned from the profiles query:

{
  profile(id: $subject) {
    invoicePreview {
      cost
      start
      end
      // other invoice fields
    }
  }
}

Invoice Detail

An invoice is composed of lineItems which are composed of subLineItems. The invoice is the overall summary. Each lineItem represents the breakdown by provisioned resource. Each subLineItem represents the breakdown by feature and plan of a lineItem.

{
 invoice(id: $invoiceId) {
   id
   cost
   start
   end
   lineItems(first: 10) {
     pageInfo {
       endCursor
       hasNextPage
     }
     edges {
       node {
         id
         cost
         chargeTime
         duration
         renewalPoint
         resource {
           displayName
         }
         subLineItems(first: 10) {
           pageInfo {
             endCursor
             hasNextPage
           }
           edges {
             node {
               currency
               calculationType
               description
               start
               item
               cost
               plan {
                 displayName
                 product {
                   label
                   displayName
                   provider {
                     displayName
                   }
                 }
               }
             }
           }
         }
       }
     }
   }
 }
}

Updating Invoice Status

An invoice should be updated when its payment status has changed. There are two supported actions: ATTEMPT and COLLECTED. Marking an invoice with a action of ATTEMPT also requires a reason.

mutation updateInvoiceStatus {
   updateInvoiceStatus(
      input: { 
         id: "123"
         action: ATTEMPT
         reason: "Insufficient funds"
      }
   ) {
     id
   }
}

Sample Data

Platforms that are starting the integration process but haven’t generated billing data can query the GraphQL API with the Manifold sample data header:

X-Manifold-Sample: "Platform"

The sample data generated allows exploring the types of data and starting to build your integration. It is static and is not meant to cover all the data edge cases.

Note: The sample data mode cannot be used when sending the Authorization header.