Developer Guide

Invoices

Returns a list of Invoices linked to a specific customer, subject to paging as defined in pagination section

URL

GET https://api.billagain.com/v1/customers/{customerID}/invoices

URL PARAMETERS (3 Fields)

Parameter Format Description
customerID req Numeric Unique customer identifier
page Numeric Current page number
page_size Numeric Amount of items on requested page

OUTPUT PARAMETERS (33 Fields)

Parameter Format Description
invoiceID Numeric Unique Invoice identifier
Customer Object The customer the invoice has been made out to
customerID Numeric Unique customer identifier
Reference Alpha Numeric Unique customer reference
Name Alpha Numeric The customers name if individual or the company name if customer is company
LastName Alpha Numeric The customers last name if individual
ActiveSubs Numeric Number of active subscriptions
invoiceNum Numeric The account unique sequential automatically generated invoice number
Reference Alpha Numeric Unique invoice reference
poNumber Numeric Purchase order number
CurrencyCode Alpha 3 letter currency code, eg. ZAR, USD
InvoiceDate Date The date the invoice is made out for
DueDate Date The date when the invoice is due by
DateSent Date The date when the invoice was sent
isDraft Boolean An indicator to indicate if invoice is draft
isCancelled Boolean An indicator to indicate if invoice is cancelled
CollectionMethod Alpha The method in which the invoice is collected, possible values:
  • cash
  • credit_card
  • debit_order
  • eft
  • hpp
gatewayID Numeric Gateway type identifier, required if collection method set to debit_order or credit_card
customerPaymentMethodID Numeric The customers payment method's identifier, required if gatewayID is selected above, has to match what gateway supports, i.e. if the gateway supports only bank accounts then a bank account or if the gateway supports only credit card then a credit card
NumTries Numeric Number of times an attempt was made to collect on invoice
NextTryDate Date The next date an attempt will be made to collect on this invoice
LastUpdated Date The last date the invoice was updated
Notes Alpha Any additional invoice note, will be the default note if unset during add
Terms Alpha Any invoice terms, will be the default term if unset during add
Status Alpha status the invoice is in, eg. Cancelled, Draft, Paid, Pending, Due, Past Due
customerID Numeric Unique customer identifier
Name Alpha Numeric The customers name if individual or the company name if customer is company
LastName Alpha Numeric The customers last name if individual
Total Alpha Numeric Total Amount of the invoice
TotalActualPaid Alpha Numeric Total amount of the invoice that the customer has actually paid and is not pending
TotalPendingPaid Alpha Numeric Total amount of the invoice that the customer has paid but is pending
TotalNegativeAdjs Alpha Numeric Total amount of Negative Adjustments applied on this invoice
Balance Alpha Numeric Total amount that is still due on invoice, pending payments are also subtracted from the invoice total to get this value
ActualBalance Alpha Numeric Total amount that is still due on invoice minus negative adjustments and payments that are not pending
Taxes List of Objects List of taxes applied on invoice
invoiceTaxID Numeric The invoice tax identifier
invoiceID Numeric The invoice identifier
Name Alpha Numeric The name of the tax
Perc Decimal The percentage of tax, a value between 0 and 1
Charges List of Objects List of charges (lines) on invoice
chargeID Numeric The charge identifier
invoiceID Numeric The invoice identifier
Line Alpha Numeric The line item
Descrip Alpha Numeric The items description
Qty Numeric The line quantity
UnitCostEx Decimal The cost of a unit excluding any taxes
AmountEx Decimal The total line cost excluding any taxes (AmountEx = UnitCostEx x Qty)
AmountInc Decimal The total line cost including any taxes (AmountInc = AmountEx + Taxes)
DisplayOrder Numeric Sequential order of how the invoice lines should appear on invoice
PaymentsApplied List of Objects List of payments applied on invoice
allocationID Numeric The allocations identifier
invoiceID Numeric The invoice identifier
paymentID Numeric The payment identifier
amountApplied Decimal The amount that was payed for by the payment
NegativeAdjustmentsApplied List of Objects List of negative adjustments applied on invoice
allocationID Numeric The allocations identifier
objectID Numeric The invoice identifier
NegativeAdjustmentID Numeric The negative adjustment identifier
amountApplied Decimal The amount that was applied on the invoice by the credit

EXAMPLES

JSON Output

HTTP CODE: 200 OK
[
  {
    "invoiceID": 11343,
    "Customer": {
      "customerID": 269,
      "Reference": "CO001",
      "isCompany": true,
      "Name": "Ashtonio",
      "LastName": "Doe",
      "RegistrationNumber": null,
      "Company": null,
      "Email": null,
      "EmailCC": null,
      "Cell": null,
      "Tel": null,
      "Fax": null,
      "VatNo": null,
      "Address1": null,
      "Address2": null,
      "City": null,
      "State": null,
      "Country": "",
      "countryID": null,
      "CountryState": "",
      "countryStateID": null,
      "ZipCode": null,
      "PrimaryGatewayID": 97,
      "CurrencyCode": "ZAR",
      "CreatedDate": "2015-08-07T15:54:49.1616425+02:00",
      "isSuspended": false,
      "isActive": true,
      "comp_status": "Active",
      "isWaiveTaxes": false,
      "SuspendedDate": null,
      "PaymentMethod": null,
      "ActiveSubs": 3,
      "Balance": 69689918.85
    },
    "invoiceNum": 920,
    "Reference": null,
    "poNumber": null,
    "CurrencyCode": "ZAR",
    "InvoiceDate": "2016-01-15T15:00:00+00:00",
    "DueDate": "2016-01-15T15:00:00+00:00",
    "DateSent": null,
    "isDraft": false,
    "isCancelled": false,
    "Source": "Auto",
    "CollectionMethod": null,
    "gatewayID": 97,
    "customerPaymentMethodID": null,
    "NumTries": 0,
    "NextTryDate": null,
    "LastUpdated": "2016-04-07T11:04:44.293",
    "Notes": null,
    "Terms": null,
    "Status": null,
    "Total": 69687500,
    "TotalActualPaid": 876.25,
    "TotalPendingPaid": 321.25,
    "TotalNegativeAdjs": 470,
    "Balance": 69685832.5,
    "ActualBalance": 69686153.75,
    "Charges": [
      {
        "chargeID": 12590,
        "invoiceID": 11343,
        "Line": "Paid-01 (1 months)",
        "Descrip": "> 500 users",
        "Qty": 1,
        "UnitCostEx": 0,
        "AmountEx": 0,
        "AmountInc": 0,
        "DisplayOrder": 1
      },
      {
        "chargeID": 12591,
        "invoiceID": 11343,
        "Line": "Parts",
        "Descrip": "25000 units @ tiered pricing",
        "Qty": 1,
        "UnitCostEx": 31250000,
        "AmountEx": 31250000,
        "AmountInc": 69687500,
        "DisplayOrder": 2
      }
    ],
    "Taxes": [
      {
        "invoiceTaxID": 11008,
        "invoiceID": 11343,
        "Name": "VAT",
        "Perc": 0.23
      },
      {
        "invoiceTaxID": 11009,
        "invoiceID": 11343,
        "Name": "Bad Tax",
        "Perc": 1
      }
    ],
    "PaymentsApplied": [
      {
        "allocationID": 10256,
        "invoiceID": 11343,
        "paymentID": 10727,
        "amountApplied": 76.75
      },
      {
        "allocationID": 10285,
        "invoiceID": 11343,
        "paymentID": 10756,
        "amountApplied": 58
      },
      {
        "allocationID": 10286,
        "invoiceID": 11343,
        "paymentID": 10757,
        "amountApplied": 5
      },
      {
        "allocationID": 10287,
        "invoiceID": 11343,
        "paymentID": 10758,
        "amountApplied": 5
      },
      {
        "allocationID": 10288,
        "invoiceID": 11343,
        "paymentID": 10759,
        "amountApplied": 5
      }
    ],
    "NegativeAdjustmentsApplied": [
      {
        "allocationID": 10327,
        "objectID": 11343,
        "NegativeAdjustmentID": 10081,
        "amountApplied": 200
      },
      {
        "allocationID": 10328,
        "objectID": 11343,
        "NegativeAdjustmentID": 10082,
        "amountApplied": 200
      },
      {
        "allocationID": 10331,
        "objectID": 11343,
        "NegativeAdjustmentID": 10083,
        "amountApplied": 10
      },
      {
        "allocationID": 10334,
        "objectID": 11343,
        "NegativeAdjustmentID": 10085,
        "amountApplied": 10
      },
      {
        "allocationID": 10359,
        "objectID": 11343,
        "NegativeAdjustmentID": 10096,
        "amountApplied": 50
      }
    ]
  },
  {
    "invoiceID": 11351,
    "Customer": {
      "customerID": 269,
      "Reference": "CO001",
      "isCompany": true,
      "Name": "Ashtonio",
      "LastName": "Doe",
      "RegistrationNumber": null,
      "Company": null,
      "Email": null,
      "EmailCC": null,
      "Cell": null,
      "Tel": null,
      "Fax": null,
      "VatNo": null,
      "Address1": null,
      "Address2": null,
      "City": null,
      "State": null,
      "Country": "",
      "countryID": null,
      "CountryState": "",
      "countryStateID": null,
      "ZipCode": null,
      "PrimaryGatewayID": 97,
      "CurrencyCode": "ZAR",
      "CreatedDate": "2015-08-07T15:54:49.1616425+02:00",
      "isSuspended": false,
      "isActive": true,
      "comp_status": "Active",
      "isWaiveTaxes": false,
      "SuspendedDate": null,
      "PaymentMethod": null,
      "ActiveSubs": 3,
      "Balance": 69689918.85
    },
    "invoiceNum": 928,
    "Reference": null,
    "poNumber": "",
    "CurrencyCode": "ZAR",
    "InvoiceDate": "2016-03-23T00:00:00+02:00",
    "DueDate": "2016-05-11T00:00:00+02:00",
    "DateSent": null,
    "isDraft": false,
    "isCancelled": false,
    "Source": "App",
    "CollectionMethod": "eft",
    "gatewayID": null,
    "customerPaymentMethodID": null,
    "NumTries": 0,
    "NextTryDate": "2016-05-11T00:00:00+02:00",
    "LastUpdated": "2016-04-07T08:21:40.023",
    "Notes": "terms",
    "Terms": "terms",
    "Status": null,
    "Total": 114,
    "TotalActualPaid": 0,
    "TotalPendingPaid": 0,
    "TotalNegativeAdjs": 0,
    "Balance": 114,
    "ActualBalance": 114,
    "Charges": [
      {
        "chargeID": 12600,
        "invoiceID": 11351,
        "Line": "MyProduct",
        "Descrip": "This is my product",
        "Qty": 1,
        "UnitCostEx": 100,
        "AmountEx": 100,
        "AmountInc": 114,
        "DisplayOrder": 1
      }
    ],
    "Taxes": [
      {
        "invoiceTaxID": 11021,
        "invoiceID": 11351,
        "Name": "Vat",
        "Perc": 0.14
      }
    ],
    "PaymentsApplied": [],
    "NegativeAdjustmentsApplied": []
  }

]

Returns a list of Invoices linked to this account, subject to paging as defined in pagination section and optional date parameters

URL

GET https://api.billagain.com/v1/invoices

URL PARAMETERS (2 Fields)

None - optional paging values and optional date parameters (as shown below) can be passed through
Parameter Format Description
startDate Date The start date of the invoice date (inclusive)
endDate Date The end date of the invoice date (inclusive)

OUTPUT PARAMETERS (33 Fields)

Parameter Format Description
invoiceID Numeric Unique Invoice identifier
Customer Object The customer the invoice has been made out to
customerID Numeric Unique customer identifier
Reference Alpha Numeric Unique customer reference
Name Alpha Numeric The customers name if individual or the company name if customer is company
LastName Alpha Numeric The customers last name if individual
ActiveSubs Numeric Number of active subscriptions
invoiceNum Numeric The account unique sequential automatically generated invoice number
Reference Alpha Numeric Unique invoice reference
poNumber Numeric Purchase order number
CurrencyCode Alpha 3 letter currency code, eg. ZAR, USD
InvoiceDate Date The date the invoice is made out for
DueDate Date The date when the invoice is due by
DateSent Date The date when the invoice was sent
isDraft Boolean An indicator to indicate if invoice is draft
isCancelled Boolean An indicator to indicate if invoice is cancelled
CollectionMethod Alpha The method in which the invoice is collected, possible values:
  • cash
  • credit_card
  • debit_order
  • eft
  • hpp
gatewayID Numeric Gateway type identifier, required if collection method set to debit_order or credit_card
customerPaymentMethodID Numeric The customers payment method's identifier, required if gatewayID is selected above, has to match what gateway supports, i.e. if the gateway supports only bank accounts then a bank account or if the gateway supports only credit card then a credit card
NumTries Numeric Number of times an attempt was made to collect on invoice
NextTryDate Date The next date an attempt will be made to collect on this invoice
LastUpdated Date The last date the invoice was updated
Notes Alpha Any additional invoice note, will be the default note if unset during add
Terms Alpha Any invoice terms, will be the default term if unset during add
Status Alpha status the invoice is in, eg. Cancelled, Draft, Paid, Pending, Due, Past Due
customerID Numeric Unique customer identifier
Name Alpha Numeric The customers name if individual or the company name if customer is company
LastName Alpha Numeric The customers last name if individual
Total Alpha Numeric Total Amount of the invoice
TotalActualPaid Alpha Numeric Total amount of the invoice that the customer has actually paid and is not pending
TotalPendingPaid Alpha Numeric Total amount of the invoice that the customer has paid but is pending
TotalNegativeAdjs Alpha Numeric Total amount of Negative Adjustments applied on this invoice
Balance Alpha Numeric Total amount that is still due on invoice, pending payments are also subtracted from the invoice total to get this value
ActualBalance Alpha Numeric Total amount that is still due on invoice minus negative adjustments and payments that are not pending
Taxes List of Objects List of taxes applied on invoice
invoiceTaxID Numeric The invoice tax identifier
invoiceID Numeric The invoice identifier
Name Alpha Numeric The name of the tax
Perc Decimal The percentage of tax, a value between 0 and 1
Charges List of Objects List of charges (lines) on invoice
chargeID Numeric The charge identifier
invoiceID Numeric The invoice identifier
Line Alpha Numeric The line item
Descrip Alpha Numeric The items description
Qty Numeric The line quantity
UnitCostEx Decimal The cost of a unit excluding any taxes
AmountEx Decimal The total line cost excluding any taxes (AmountEx = UnitCostEx x Qty)
AmountInc Decimal The total line cost including any taxes (AmountInc = AmountEx + Taxes)
DisplayOrder Numeric Sequential order of how the invoice lines should appear on invoice
PaymentsApplied List of Objects List of payments applied on invoice
allocationID Numeric The allocations identifier
invoiceID Numeric The invoice identifier
paymentID Numeric The payment identifier
amountApplied Decimal The amount that was payed for by the payment
NegativeAdjustmentsApplied List of Objects List of negative adjustments applied on invoice
allocationID Numeric The allocations identifier
objectID Numeric The invoice identifier
NegativeAdjustmentID Numeric The negative adjustment identifier
amountApplied Decimal The amount that was applied on the invoice by the credit

EXAMPLES

JSON Output

HTTP CODE: 200 OK
[
  {
    "invoiceID": 11343,
    "Customer": {
      "customerID": 269,
      "Reference": "CO001",
      "isCompany": true,
      "Name": "Ashtonio",
      "LastName": "Doe",
      "RegistrationNumber": null,
      "Company": null,
      "Email": null,
      "EmailCC": null,
      "Cell": null,
      "Tel": null,
      "Fax": null,
      "VatNo": null,
      "Address1": null,
      "Address2": null,
      "City": null,
      "State": null,
      "Country": "",
      "countryID": null,
      "CountryState": "",
      "countryStateID": null,
      "ZipCode": null,
      "PrimaryGatewayID": 97,
      "CurrencyCode": "ZAR",
      "CreatedDate": "2015-08-07T15:54:49.1616425+02:00",
      "isSuspended": false,
      "isActive": true,
      "comp_status": "Active",
      "isWaiveTaxes": false,
      "SuspendedDate": null,
      "PaymentMethod": null,
      "ActiveSubs": 3,
      "Balance": 69689918.85
    },
    "invoiceNum": 920,
    "Reference": null,
    "poNumber": null,
    "CurrencyCode": "ZAR",
    "InvoiceDate": "2016-01-15T15:00:00+00:00",
    "DueDate": "2016-01-15T15:00:00+00:00",
    "DateSent": null,
    "isDraft": false,
    "isCancelled": false,
    "Source": "Auto",
    "CollectionMethod": null,
    "gatewayID": 97,
    "customerPaymentMethodID": null,
    "NumTries": 0,
    "NextTryDate": null,
    "LastUpdated": "2016-04-07T11:04:44.293",
    "Notes": null,
    "Terms": null,
    "Status": null,
    "Total": 69687500,
    "TotalActualPaid": 876.25,
    "TotalPendingPaid": 321.25,
    "TotalNegativeAdjs": 470,
    "Balance": 69685832.5,
    "ActualBalance": 69686153.75,
    "Charges": [
      {
        "chargeID": 12590,
        "invoiceID": 11343,
        "Line": "Paid-01 (1 months)",
        "Descrip": "> 500 users",
        "Qty": 1,
        "UnitCostEx": 0,
        "AmountEx": 0,
        "AmountInc": 0,
        "DisplayOrder": 1
      },
      {
        "chargeID": 12591,
        "invoiceID": 11343,
        "Line": "Parts",
        "Descrip": "25000 units @ tiered pricing",
        "Qty": 1,
        "UnitCostEx": 31250000,
        "AmountEx": 31250000,
        "AmountInc": 69687500,
        "DisplayOrder": 2
      }
    ],
    "Taxes": [
      {
        "invoiceTaxID": 11008,
        "invoiceID": 11343,
        "Name": "VAT",
        "Perc": 0.23
      },
      {
        "invoiceTaxID": 11009,
        "invoiceID": 11343,
        "Name": "Bad Tax",
        "Perc": 1
      }
    ],
    "PaymentsApplied": [
      {
        "allocationID": 10256,
        "invoiceID": 11343,
        "paymentID": 10727,
        "amountApplied": 76.75
      },
      {
        "allocationID": 10285,
        "invoiceID": 11343,
        "paymentID": 10756,
        "amountApplied": 58
      },
      {
        "allocationID": 10286,
        "invoiceID": 11343,
        "paymentID": 10757,
        "amountApplied": 5
      },
      {
        "allocationID": 10287,
        "invoiceID": 11343,
        "paymentID": 10758,
        "amountApplied": 5
      },
      {
        "allocationID": 10288,
        "invoiceID": 11343,
        "paymentID": 10759,
        "amountApplied": 5
      }
    ],
    "NegativeAdjustmentsApplied": [
      {
        "allocationID": 10327,
        "objectID": 11343,
        "NegativeAdjustmentID": 10081,
        "amountApplied": 200
      },
      {
        "allocationID": 10328,
        "objectID": 11343,
        "NegativeAdjustmentID": 10082,
        "amountApplied": 200
      },
      {
        "allocationID": 10331,
        "objectID": 11343,
        "NegativeAdjustmentID": 10083,
        "amountApplied": 10
      },
      {
        "allocationID": 10334,
        "objectID": 11343,
        "NegativeAdjustmentID": 10085,
        "amountApplied": 10
      },
      {
        "allocationID": 10359,
        "objectID": 11343,
        "NegativeAdjustmentID": 10096,
        "amountApplied": 50
      }
    ]
  },
  {
    "invoiceID": 11351,
    "Customer": {
      "customerID": 269,
      "Reference": "CO001",
      "isCompany": true,
      "Name": "Ashtonio",
      "LastName": "Doe",
      "RegistrationNumber": null,
      "Company": null,
      "Email": null,
      "EmailCC": null,
      "Cell": null,
      "Tel": null,
      "Fax": null,
      "VatNo": null,
      "Address1": null,
      "Address2": null,
      "City": null,
      "State": null,
      "Country": "",
      "countryID": null,
      "CountryState": "",
      "countryStateID": null,
      "ZipCode": null,
      "PrimaryGatewayID": 97,
      "CurrencyCode": "ZAR",
      "CreatedDate": "2015-08-07T15:54:49.1616425+02:00",
      "isSuspended": false,
      "isActive": true,
      "comp_status": "Active",
      "isWaiveTaxes": false,
      "SuspendedDate": null,
      "PaymentMethod": null,
      "ActiveSubs": 3,
      "Balance": 69689918.85
    },
    "invoiceNum": 928,
    "Reference": null,
    "poNumber": "",
    "CurrencyCode": "ZAR",
    "InvoiceDate": "2016-03-23T00:00:00+02:00",
    "DueDate": "2016-05-11T00:00:00+02:00",
    "DateSent": null,
    "isDraft": false,
    "isCancelled": false,
    "Source": "App",
    "CollectionMethod": "eft",
    "gatewayID": null,
    "customerPaymentMethodID": null,
    "NumTries": 0,
    "NextTryDate": "2016-05-11T00:00:00+02:00",
    "LastUpdated": "2016-04-07T08:21:40.023",
    "Notes": "terms",
    "Terms": "terms",
    "Status": null,
    "Total": 114,
    "TotalActualPaid": 0,
    "TotalPendingPaid": 0,
    "TotalNegativeAdjs": 0,
    "Balance": 114,
    "ActualBalance": 114,
    "Charges": [
      {
        "chargeID": 12600,
        "invoiceID": 11351,
        "Line": "MyProduct",
        "Descrip": "This is my product",
        "Qty": 1,
        "UnitCostEx": 100,
        "AmountEx": 100,
        "AmountInc": 114,
        "DisplayOrder": 1
      }
    ],
    "Taxes": [
      {
        "invoiceTaxID": 11021,
        "invoiceID": 11351,
        "Name": "Vat",
        "Perc": 0.14
      }
    ],
    "PaymentsApplied": [],
    "NegativeAdjustmentsApplied": []
  }

]

Returns a specific invoice

URL

GET https://api.billagain.com/v1/invoices/{invoiceID}

URL PARAMETERS (1 Field)

Parameter Format Description
invoiceID req Numeric Unique Invoice identifier

OUTPUT PARAMETERS (30 Fields)

Parameter Format Description
invoiceID Numeric Unique Invoice identifier
Customer Object The customer the invoice has been made out to
customerID Numeric Unique customer identifier
Reference Alpha Numeric Unique customer reference
Name Alpha Numeric The customers name if individual or the company name if customer is company
LastName Alpha Numeric The customers last name if individual
ActiveSubs Numeric Number of active subscriptions
invoiceNum Numeric The account unique sequential automatically generated invoice number
Reference Alpha Numeric Unique invoice reference
poNumber Numeric Purchase order number
CurrencyCode Alpha 3 letter currency code, eg. ZAR, USD
InvoiceDate Date The date the invoice is made out for
DueDate Date The date when the invoice is due by
DateSent Date The date when the invoice was sent
isDraft Boolean An indicator to indicate if invoice is draft
isCancelled Boolean An indicator to indicate if invoice is cancelled
CollectionMethod Alpha The method in which the invoice is collected, possible values:
  • cash
  • credit_card
  • debit_order
  • eft
  • hpp
gatewayID Numeric Gateway identifier
customerPaymentMethodID Numeric The customers payment method's identifier
NumTries Numeric Number of times an attempt was made to collect on invoice
NextTryDate Date The next date an attempt will be made to collect on this invoice
LastUpdated Date The last date the invoice was updated
Notes Alpha Any additional invoice note, will be the default note if unset during add
Terms Alpha Any invoice terms, will be the default term if unset during add
Status Alpha status the invoice is in, eg. Cancelled, Draft, Paid, Pending, Due, Past Due
Total Alpha Numeric Total Amount of the invoice
TotalActualPaid Alpha Numeric Total amount of the invoice that the customer has actually paid and is not pending
TotalPendingPaid Alpha Numeric Total amount of the invoice that the customer has paid but is pending
TotalNegativeAdjs Alpha Numeric Total amount of Negative Adjustments applied on this invoice
Balance Alpha Numeric Total amount that is still due on invoice, pending payments are also subtracted from the invoice total to get this value
ActualBalance Alpha Numeric Total amount that is still due on invoice minus negative adjustments and payments that are not pending
Taxes List of Objects List of taxes applied on invoice
invoiceTaxID Numeric The invoice tax identifier
invoiceID Numeric The invoice identifier
Name Alpha Numeric The name of the tax
Perc Decimal The percentage of tax, a value between 0 and 1
Charges List of Objects List of charges (lines) on invoice
chargeID Numeric The charge identifier
invoiceID Numeric The invoice identifier
Line Alpha Numeric The line item
Descrip Alpha Numeric The items description
Qty Numeric The line quantity
UnitCostEx Decimal The cost of a unit excluding any taxes
AmountEx Decimal The total line cost excluding any taxes (AmountEx = UnitCostEx x Qty)
AmountInc Decimal The total line cost including any taxes (AmountInc = AmountEx + Taxes)
DisplayOrder Numeric Sequential order of how the invoice lines should appear on invoice
PaymentsApplied List of Objects List of payments applied on invoice
allocationID Numeric The allocations identifier
invoiceID Numeric The invoice identifier
paymentID Numeric The payment identifier
amountApplied Decimal The amount that was payed for by the payment
NegativeAdjustmentsApplied List of Objects List of negative adjustments applied on invoice
allocationID Numeric The allocations identifier
objectID Numeric The invoice identifier
NegativeAdjustmentID Numeric The negative adjustment identifier
amountApplied Decimal The amount that was applied on the invoice by the credit

EXAMPLES

JSON Output

HTTP CODE: 200 OK
{
    "invoiceID": 11343,
    "Customer": {
      "customerID": 269,
      "Reference": "CO001",
      "isCompany": true,
      "Name": "Ashtonio",
      "LastName": "Doe",
      "RegistrationNumber": null,
      "Company": null,
      "Email": null,
      "EmailCC": null,
      "Cell": null,
      "Tel": null,
      "Fax": null,
      "VatNo": null,
      "Address1": null,
      "Address2": null,
      "City": null,
      "State": null,
      "Country": "",
      "countryID": null,
      "CountryState": "",
      "countryStateID": null,
      "ZipCode": null,
      "PrimaryGatewayID": 97,
      "CurrencyCode": "ZAR",
      "CreatedDate": "2015-08-07T15:54:49.1616425+02:00",
      "isSuspended": false,
      "isActive": true,
      "comp_status": "Active",
      "isWaiveTaxes": false,
      "SuspendedDate": null,
      "PaymentMethod": null,
      "ActiveSubs": 3,
      "Balance": 69689918.85
    },
    "invoiceNum": 920,
    "Reference": null,
    "poNumber": null,
    "CurrencyCode": "ZAR",
    "InvoiceDate": "2016-01-15T15:00:00+00:00",
    "DueDate": "2016-01-15T15:00:00+00:00",
    "DateSent": null,
    "isDraft": false,
    "isCancelled": false,
    "Source": "Auto",
    "CollectionMethod": null,
    "gatewayID": 97,
    "customerPaymentMethodID": null,
    "NumTries": 0,
    "NextTryDate": null,
    "LastUpdated": "2016-04-07T11:04:44.293",
    "Notes": null,
    "Terms": null,
    "Status": null,
    "Total": 69687500,
    "TotalActualPaid": 876.25,
    "TotalPendingPaid": 321.25,
    "TotalNegativeAdjs": 470,
    "Balance": 69685832.5,
    "ActualBalance": 69686153.75,
    "Charges": [
      {
        "chargeID": 12590,
        "invoiceID": 11343,
        "Line": "CU-Agent-Paid-01 (1 months)",
        "Descrip": "> 500 parts (R1250.00 p/15 000 parts)",
        "Qty": 1,
        "UnitCostEx": 0,
        "AmountEx": 0,
        "AmountInc": 0,
        "DisplayOrder": 1
      },
      {
        "chargeID": 12591,
        "invoiceID": 11343,
        "Line": "Parts",
        "Descrip": "25000 units @ tiered pricing",
        "Qty": 1,
        "UnitCostEx": 31250000,
        "AmountEx": 31250000,
        "AmountInc": 69687500,
        "DisplayOrder": 2
      }
    ],
    "Taxes": [
      {
        "invoiceTaxID": 11008,
        "invoiceID": 11343,
        "Name": "Test",
        "Perc": 0.23
      },
      {
        "invoiceTaxID": 11009,
        "invoiceID": 11343,
        "Name": "Jameson Tax",
        "Perc": 1
      }
    ],
    "PaymentsApplied": [
      {
        "allocationID": 10256,
        "invoiceID": 11343,
        "paymentID": 10727,
        "amountApplied": 76.75
      },
      {
        "allocationID": 10285,
        "invoiceID": 11343,
        "paymentID": 10756,
        "amountApplied": 58
      },
      {
        "allocationID": 10286,
        "invoiceID": 11343,
        "paymentID": 10757,
        "amountApplied": 5
      },
      {
        "allocationID": 10287,
        "invoiceID": 11343,
        "paymentID": 10758,
        "amountApplied": 5
      },
      {
        "allocationID": 10288,
        "invoiceID": 11343,
        "paymentID": 10759,
        "amountApplied": 5
      }
    ],
    "NegativeAdjustmentsApplied": [
      {
        "allocationID": 10327,
        "objectID": 11343,
        "NegativeAdjustmentID": 10081,
        "amountApplied": 200
      },
      {
        "allocationID": 10328,
        "objectID": 11343,
        "NegativeAdjustmentID": 10082,
        "amountApplied": 200
      },
      {
        "allocationID": 10331,
        "objectID": 11343,
        "NegativeAdjustmentID": 10083,
        "amountApplied": 10
      },
      {
        "allocationID": 10334,
        "objectID": 11343,
        "NegativeAdjustmentID": 10085,
        "amountApplied": 10
      },
      {
        "allocationID": 10359,
        "objectID": 11343,
        "NegativeAdjustmentID": 10096,
        "amountApplied": 50
      }
    ]
  }

Adds an invoice to your account

URL

POST https://api.billagain.com/v1/invoices

INPUT PARAMETERS (14 Fields)

Parameter Format Description
customerID req Numeric Unique customer identifier
Reference Alpha Numeric Unique invoice reference
poNumber Numeric Purchase order number
CurrencyCode req Alpha 3 letter currency code, eg. ZAR, USD
InvoiceDate req Date The date the invoice is made out for
DueDate req Date The date when the invoice is due by
isDraft req Boolean Indicates if you would like to finalise invoice or save it as draft, true implies it should be saved as draft invoice
CollectionMethod req Alpha The method in which the invoice is collected, possible values:
  • cash
  • credit_card
  • debit_order
  • eft
  • hpp
gatewayID Numeric Gateway identifier, required if collection method set to debit_order or credit_card
customerPaymentMethodID Numeric The customers payment method's identifier, required if gatewayID is selected above, has to match what gateway supports, i.e. if the gateway supports only bank accounts then a bank account or if the gateway supports only credit card then a credit card
Notes Alpha Any additional invoice note, will be the default note if unset during add
Terms Alpha Any invoice terms, will be the default term if unset during add
Taxes List of Objects List of taxes applied on invoice
Name req Alpha Numeric The name of the tax
Perc req Decimal The percentage of tax, a value between 0 and 1
Charges List of Objects List of charges (lines) on invoice
Line req Alpha Numeric The line item
Descrip Alpha Numeric The items description
Qty req Numeric The line quantity
UnitCostEx req Decimal The cost of a unit excluding any taxes
DisplayOrder req Numeric Sequential order of how the invoice lines should appear on invoice

OUTPUT PARAMETERS (30 Fields)

Parameter Format Description
invoiceID Numeric Unique Invoice identifier
Customer Object The customer the invoice has been made out to
customerID Numeric Unique customer identifier
Reference Alpha Numeric Unique customer reference
isCompany Boolean An indicator of whether a customer is an individual or a company
Name Alpha Numeric The customers name if individual or the company name if customer is company
LastName Alpha Numeric The customers last name if individual
RegistrationNumber Alpha Numeric Company registration number
VatNo Numeric Customer Value Added Tax Number
Company Alpha Numeric If individual, the company the individual belongs to
Email Email The customers email address
EmailCC Email An alternate email address for customer
Cell Alpha Numeric Mobile number
Tel Alpha Numeric Telephone number
Fax Alpha Numeric Facsimile number
Address1 Alpha Numeric First line of address
Address2 Alpha Numeric Second line of address
City Alpha Numeric Address city
State Alpha Numeric Address state / province
Country Alpha Numeric Address country
CountryState Alpha Numeric Address country tax state
countryID Numeric Billagain country identifier for taxation
countryStateID Numeric Billagain country state identifier for taxation
ZipCode Alpha Numeric Address zip or area code
PrimaryGatewayID Numeric Billagain primary gateway identifier
CurrencyCode Alpha 3 letter currency code, eg. ZAR, USD
CreatedDate Date Date added
isSuspended Numeric An indicator to indicate if customer is suspended
isActive Boolean An indicator to indicate if customer is not archived
comp_status Alpha Computed customer status
isWaiveTaxes Boolean An indicator to indicate if customer is tax exempt
SuspendedDate Date Date customer was suspended if suspended
PaymentMethod Alpha Customers payment method (Options: cash, cheque, credit_card, bank_account, eft)
ActiveSubs Numeric Number of active subscriptions
Balance Numeric Customer balance owing
invoiceNum Numeric The account unique sequential automatically generated invoice number
Reference Alpha Numeric Unique invoice reference
poNumber Numeric Purchase order number
CurrencyCode Alpha 3 letter currency code, eg. ZAR, USD
InvoiceDate Date The date the invoice is made out for
DueDate Date The date when the invoice is due by
DateSent Date The date when the invoice was sent
isDraft Boolean An indicator to indicate if invoice is draft
isCancelled Boolean An indicator to indicate if invoice is cancelled
CollectionMethod Alpha The method in which the invoice is collected, possible values:
  • cash
  • credit_card
  • debit_order
  • eft
  • hpp
gatewayID Numeric Gateway type identifier, required if collection method set to debit_order or credit_card
customerPaymentMethodID Numeric The customers payment method's identifier, required if gatewayID is selected above, has to match what gateway supports, i.e. if the gateway supports only bank accounts then a bank account or if the gateway supports only credit card then a credit card
NumTries Numeric Number of times an attempt was made to collect on invoice
NextTryDate Date The next date an attempt will be made to collect on this invoice
LastUpdated Date The last date the invoice was updated
Notes Alpha Any additional invoice note, will be the default note if unset during add
Terms Alpha Any invoice terms, will be the default term if unset during add
Status Alpha status the invoice is in, eg. Cancelled, Draft, Paid, Pending, Due, Past Due
Total Alpha Numeric Total Amount of the invoice
TotalActualPaid Alpha Numeric Total amount of the invoice that the customer has actually paid and is not pending
TotalPendingPaid Alpha Numeric Total amount of the invoice that the customer has paid but is pending
TotalNegativeAdjs Alpha Numeric Total amount of Negative Adjustments applied on this invoice
Balance Alpha Numeric Total amount that is still due on invoice, pending payments are also subtracted from the invoice total to get this value
ActualBalance Alpha Numeric Total amount that is still due on invoice minus negative adjustments and payments that are not pending
Taxes List of Objects List of taxes applied on invoice
invoiceTaxID Numeric The invoice tax identifier
invoiceID Numeric The invoice identifier
Name Alpha Numeric The name of the tax
Perc Decimal The percentage of tax, a value between 0 and 1
Charges List of Objects List of charges (lines) on invoice
chargeID Numeric The charge identifier
invoiceID Numeric The invoice identifier
Line Alpha Numeric The line item
Descrip Alpha Numeric The items description
Qty Numeric The line quantity
UnitCostEx Decimal The cost of a unit excluding any taxes
AmountEx Decimal The total line cost excluding any taxes (AmountEx = UnitCostEx x Qty)
AmountInc Decimal The total line cost including any taxes (AmountInc = AmountEx + Taxes)
DisplayOrder Numeric Sequential order of how the invoice lines should appear on invoice
PaymentsApplied List of Objects List of payments applied on invoice
allocationID Numeric The allocations identifier
invoiceID Numeric The invoice identifier
paymentID Numeric The payment identifier
amountApplied Decimal The amount that was payed for by the payment
NegativeAdjustmentsApplied List of Objects List of negative adjustments applied on invoice
allocationID Numeric The allocations identifier
objectID Numeric The invoice identifier
NegativeAdjustmentID Numeric The negative adjustment identifier
amountApplied Decimal The amount that was applied on the invoice by the credit

EXAMPLES

JSON Input

{
    "customerID": 269,
    "Reference": null,
    "poNumber": "ORD585",
    "CurrencyCode": "ZAR",
    "InvoiceDate": "2016-01-15T15:00:00+00:00",
    "DueDate": "2016-02-15T15:00:00+00:00",
    "isDraft": false,
    "CollectionMethod": null,
    "gatewayID": null,
    "customerPaymentMethodID": null,
    "Notes": "Please contact accounts for any enquiries",
    "Terms": "30 Days to Pay",
    "Charges": [
      {
        "Line": "Product A",
        "Descrip": "A Class Product",
        "Qty": 1,
        "UnitCostEx": 50.55,
        "DisplayOrder": 1
      },
      {
        "Line": "Product B",
        "Descrip": "B Class Product",
        "Qty": 1,
        "UnitCostEx": 105,
        "DisplayOrder": 2
      }
    ],
    "Taxes": [
      {
        "Name": "VAT",
        "Perc": 0.14
      }
    ]
  }

JSON Output

HTTP CODE: 201 Created
{
  "invoiceID": 11385,
  "Customer": {
    "customerID": 269,
    "Reference": "TCG009",
    "isCompany": true,
    "Name": "Ashtonio",
    "LastName": null,
    "RegistrationNumber": null,
    "Company": null,
    "Email": null,
    "EmailCC": null,
    "Cell": null,
    "Tel": null,
    "Fax": null,
    "VatNo": null,
    "Address1": null,
    "Address2": null,
    "City": null,
    "State": null,
    "Country": "",
    "countryID": null,
    "CountryState": "",
    "countryStateID": null,
    "ZipCode": null,
    "PrimaryGatewayID": 97,
    "CurrencyCode": "ZAR",
    "CreatedDate": "2015-08-07T15:54:49.1616425+02:00",
    "isSuspended": false,
    "isActive": true,
    "comp_status": "Active",
    "isWaiveTaxes": false,
    "SuspendedDate": null,
    "PaymentMethod": null,
    "ActiveSubs": 0,
    "Balance": 0
  },
  "invoiceNum": 962,
  "Reference": null,
  "poNumber": "ORD585",
  "CurrencyCode": "ZAR",
  "InvoiceDate": "2016-01-15T15:00:00+00:00",
  "DueDate": "2016-02-15T15:00:00+00:00",
  "DateSent": null,
  "isDraft": false,
  "isCancelled": false,
  "Source": "Api",
  "CollectionMethod": null,
  "gatewayID": null,
  "customerPaymentMethodID": null,
  "NumTries": 0,
  "NextTryDate": "2016-02-15T15:00:00+00:00",
  "LastUpdated": "2016-04-08T06:55:49.243",
  "Notes": "Please contact accounts for any enquiries",
  "Terms": "30 Days to Pay",
  "Status": null,
  "Total": 177.327,
  "TotalActualPaid": 0,
  "TotalPendingPaid": 0,
  "TotalNegativeAdjs": 0,
  "Balance": 177.327,
  "ActualBalance": 177.327,
  "Charges": [
    {
      "chargeID": 12636,
      "invoiceID": 11385,
      "Line": "Product A",
      "Descrip": "A Class Product",
      "Qty": 1,
      "UnitCostEx": 50.55,
      "AmountEx": 50.55,
      "AmountInc": 57.627,
      "DisplayOrder": 1
    },
    {
      "chargeID": 12637,
      "invoiceID": 11385,
      "Line": "Product B",
      "Descrip": "B Class Product",
      "Qty": 1,
      "UnitCostEx": 105,
      "AmountEx": 105,
      "AmountInc": 119.7,
      "DisplayOrder": 2
    }
  ],
  "Taxes": [
    {
      "invoiceTaxID": 11035,
      "invoiceID": 11385,
      "Name": "VAT",
      "Perc": 0.14
    }
  ],
  "PaymentsApplied": [],
  "NegativeAdjustmentsApplied": []
}

Updates an invoice

URL

PUT https://api.billagain.com/v1/invoices/{invoiceID}

URL PARAMETERS (1 Field)

Parameter Format Description
invoiceID req Numeric Unique Invoice identifier

INPUT PARAMETERS (15 Fields)

Parameter Format Description
invoiceID req Numeric Unique Invoice identifier
customerID req Numeric Unique customer identifier
Reference Alpha Numeric Unique invoice reference
poNumber Numeric Purchase order number
CurrencyCode req Alpha 3 letter currency code, eg. ZAR, USD
InvoiceDate req Date The date the invoice is made out for
DueDate req Date The date when the invoice is due by
isDraft req Boolean Indicates if you would like to finalise invoice or save it as draft, true implies it should be saved as draft invoice
CollectionMethod req Alpha The method in which the invoice is collected, possible values:
  • cash
  • credit_card
  • debit_order
  • eft
  • hpp
gatewayID Numeric Gateway identifier, required if collection method set to debit_order or credit_card
customerPaymentMethodID Numeric The customers payment method's identifier, required if gatewayID is selected above, has to match what gateway supports, i.e. if the gateway supports only bank accounts then a bank account or if the gateway supports only credit card then a credit card
Notes Alpha Any additional invoice note, will be the default note if unset during add
Terms Alpha Any invoice terms, will be the default term if unset during add
Taxes List of Objects List of taxes applied on invoice, if invoiceTaxID provided the values will be updated, if invoiceTaxID not provided a new entry will be added and if tax line not provided the tax line will be deleted from invoice
invoiceTaxID Numeric The invoice tax identifier
Name req Alpha Numeric The name of the tax
Perc req Decimal The percentage of tax, a value between 0 and 1
Charges List of Objects List of charges (lines) on invoice, , if chargeID provided the values will be updated, if chargeID not provided a new entry will be added and if charge line not provided the charge line will be deleted from invoice
chargeID Numeric The charge identifier
Line req Alpha Numeric The line item
Descrip Alpha Numeric The items description
Qty req Numeric The line quantity
UnitCostEx req Decimal The cost of a unit excluding any taxes
DisplayOrder req Numeric Sequential order of how the invoice lines should appear on invoice

EXAMPLES

JSON Input

{
  "invoiceID": 11386,
  "customerID": 269,
  "invoiceNum": 963,
  "Reference": null,
  "poNumber": "ORD5856",
  "CurrencyCode": "ZAR",
  "InvoiceDate": "2016-01-15T15:00:00+00:00",
  "DueDate": "2016-02-15T15:00:00+00:00",
  "DateSent": null,
  "isDraft": true,
  "CollectionMethod": null,
  "gatewayID": null,
  "customerPaymentMethodID": null,
  "NumTries": 0,
  "NextTryDate": "2016-02-15T15:00:00+00:00",
  "LastUpdated": "2016-04-08T07:00:24.5",
  "Notes": "Please contact accounts for any enquiries",
  "Terms": "30 Days to Pay",
  "Charges": [
    {
      "chargeID": 12638,
      "invoiceID": 11386,
      "Line": "Product A",
      "Descrip": "A Class Product",
      "Qty": 1,
      "UnitCostEx": 50.55,
      "AmountEx": 50.55,
      "AmountInc": 57.627,
      "DisplayOrder": 1
    },
    {
      "chargeID": 12639,
      "invoiceID": 11386,
      "Line": "Product B",
      "Descrip": "B Class Product",
      "Qty": 1,
      "UnitCostEx": 105,
      "AmountEx": 105,
      "AmountInc": 119.7,
      "DisplayOrder": 2
    }
  ],
  "Taxes": [
    {
      "invoiceTaxID": 11036,
      "invoiceID": 11386,
      "Name": "VAT",
      "Perc": 0.14
    }
  ]
}

JSON Output

HTTP CODE: 204 No Content

Deletes a draft invoice, will cancel the invoice if invoice is not a draft invoice

URL

DELETE https://api.billagain.com/v1/invoices/{invoiceID}

URL PARAMETERS (1 Field)

Parameter Format Description
invoiceID req Numeric Unique Invoice identifier

EXAMPLES

JSON Output

HTTP CODE: 204 No Content