Developer Guide

Credits

Get a list of customer's credit notes

URL

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

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 (9 Fields)

Parameter Format Description
creditNoteID Numeric Unique credit identifier
customerID Numeric Unique customer identifier
Status Alpha The payment status (Options : Pending, Allocated, Partial, Unallocated, Failed )
Date Date The date of payment
CurrencyCode Alpha 3 letter currency code, eg. ZAR, USD
Amount Numeric The Amount paid by customer
CreditNumber Alpha Numeric Credit card number
Memo Alpha Numeric Payment Memo
Allocations Object List
allocationID Numeric Unique Allocation identifier
amountApplied Numeric Portion of the Payment used to pay invoice
invoiceID Numeric Unique Invoice identifier

EXAMPLES

JSON Output

HTTP CODE: 200 OK
[
  {
    "creditNoteID": 10083,
    "customerID": 269,
    "Status": "Allocated",
    "Date": "2016-04-04T22:00:00Z",
    "CurrencyCode": "ZAR",
    "Amount": 100,
    "CreditNumber": "424242424242424",
    "Memo": "",
    "Allocations": [
      {
        "allocationID": 10331,
        "invoiceID": 11343,
        "creditNoteID": 0,
        "amountApplied": 100
      }
    ]
  },
  {
    "creditNoteID": 10095,
    "customerID": 269,
    "Status": "Allocated",
    "Date": "2016-04-04T22:00:00Z",
    "CurrencyCode": "ZAR",
    "Amount": 200,
    "CreditNumber": "424242424242424",
    "Memo": "payment to invoices",
    "Allocations": [
      {
        "allocationID": 10355,
        "invoiceID": 11352,
        "creditNoteID": 10095,
        "amountApplied": 150
      },
      {
        "allocationID": 10358,
        "invoiceID": 11380,
        "creditNoteID": 10095,
        "amountApplied": 50
      }
    ]
  }
]

Get a list of credit notes account related

URL

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

INPUT PARAMETERS (2 Fields)

Parameter Format Description
page Numeric Current page number
page_size Numeric Amount of items on requested page

OUTPUT PARAMETERS (9 Fields)

Parameter Format Description
creditNoteID Numeric Unique credit identifier
customerID Numeric Unique customer identifier
Status Alpha The payment status (Options : Pending, Allocated, Partial, Unallocated, Failed )
Date Date The date of payment
CurrencyCode Alpha 3 letter currency code, eg. ZAR, USD
Amount Numeric The Amount paid by customer
CreditNumber Alpha Numeric Credit card number
Memo Alpha Numeric Payment Memo
Allocations Object List
allocationID Numeric Unique allocation identifier
amountApplied Numeric Portion of the payment used to pay invoice
invoiceID Numeric Unique invoice identifier

EXAMPLES

JSON Output

HTTP CODE: 200 OK
[
  {
    "creditNoteID": 10081,
    "customerID": 222,
    "Status": "Allocated",
    "Date": "2016-04-04T22:00:00Z",
    "CurrencyCode": "ZAR",
    "Amount": 200,
    "CreditNumber": "424242424242424",
    "Memo": "",
    "Allocations": [
      {
        "allocationID": 10327,
        "invoiceID": 11343,
        "creditNoteID": 0,
        "amountApplied": 200
      }
    ]
  },
  {
    "creditNoteID": 10095,
    "customerID": 269,
    "Status": "Allocated",
    "Date": "2016-04-04T22:00:00Z",
    "CurrencyCode": "ZAR",
    "Amount": 200,
    "CreditNumber": "424242424242424",
    "Memo": "payment to invoices",
    "Allocations": [
      {
        "allocationID": 10355,
        "invoiceID": 11352,
        "creditNoteID": 0,
        "amountApplied": 150
      },
      {
        "allocationID": 10358,
        "invoiceID": 11380,
        "creditNoteID": 0,
        "amountApplied": 50
      }
    ]
  }
]

Get specific credit note

URL

GET https://api.billagain.com/v1/credits/{creditNoteID}

URL PARAMETERS (1 Field)

Parameter Format Description
creditNoteID req Numeric Unique credit identifier

OUTPUT PARAMETERS (9 Fields)

Parameter Format Description
creditNoteID Numeric Unique credit identifier
customerID Numeric Unique customer identifier
Amount Numeric The Amount paid by customer
CurrencyCode Alpha 3 letter currency code, eg. ZAR, USD
Date Date The date of payment
Memo Alpha Numeric Payment Memo
CreditNumber Alpha Numeric Credit card number
Status Alpha The payment status (Options : Pending, Allocated, Partial, Unallocated, Failed )
Allocations Object List
allocationID Numeric Unique allocation identifier
amountApplied Numeric Portion of the payment used to pay invoice
invoiceID Numeric Unique Invoice identifier

EXAMPLES

JSON Output

HTTP CODE: 200 OK
{
  "creditNoteID": 10095,
  "customerID": 269,
  "Status": "Allocated",
  "Date": "2016-04-04T22:00:00Z",
  "CurrencyCode": "ZAR",
  "Amount": 200,
  "CreditNumber": "424242424242424",
  "Memo": "payment to invoices",
  "Allocations": [
    {
      "allocationID": 10355,
      "invoiceID": 11352,
      "creditNoteID": 10095,
      "amountApplied": 150
    },
    {
      "allocationID": 10358,
      "invoiceID": 11380,
      "creditNoteID": 10095,
      "amountApplied": 50
    }
  ]
}

Add specific credit note

URL

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

INPUT PARAMETERS (8 Fields)

Parameter Format Description
customerID req Numeric Unique customer identifier
Date req Date The date of payment
CurrencyCode req Alpha 3 letter currency code, eg. ZAR, USD
Amount req Numeric The Amount paid by customer
Credit ref req Alpha Numeric Credit card number reference
Memo Alpha Numeric Payment Memo
AutoApply Boolean AutoApply conditions:
  • True - the payment will be made to the earliest invoice and credit allocations is not required and will not be used
  • False - (false by default) then credit allocations is required
Allocations req Object List Alternative field options:
  • invoiceID - is required if {invoiceNumber} is empty, note {invoiceID} will always take first priority
  • invoiceNumber - is required if {invoiceID} is empty
amountApplied req Numeric Portion of the payment used to pay invoice
invoiceID req Numeric Unique Invoice identifier
invoiceNumber Numeric Unique Invoice identifier

OUTPUT PARAMETERS (8 Fields)

Parameter Format Description
creditNoteID Numeric Unique credit identifier
customerID Numeric Unique customer identifier
Amount Numeric The Amount paid by customer
CurrencyCode Alpha 3 letter currency code, eg. ZAR, USD
Date Date The date of payment
Memo Alpha Numeric Payment Memo
Status Alpha The payment status (Options : Pending, Allocated, Partial, Unallocated, Failed )
Allocations Object List
allocationID Numeric Unique allocation identifier
amountApplied Numeric Portion of the payment used to pay invoice
invoiceID Numeric Unique invoice identifier

EXAMPLES

JSON Input

{
  "customerID": 269,
  "Date": "05 Apr 2016",
  "CurrencyCode": "ZAR",
  "Amount": 150,
  "CreditNumber" : "424242424242424",
  "Memo": "",
  "AutoApply" : false,
  "Allocations": [
    {
      "invoiceID": 11351,
      "amountApplied": 50
    },
    {
      "invoiceID": 11352,
      "amountApplied": 50
    },
    {
      "amountApplied": 50,
      "invoiceNumber": 957
    }
  ]
}

JSON Output

HTTP CODE: 201 Created
{
  "creditNoteID": 10095,
  "customerID": 269,
  "Status": "Allocated",
  "Date": "2016-04-04T22:00:00Z",
  "CurrencyCode": "ZAR",
  "Amount": 150,
  "CreditNumber": "424242424242424",
  "Memo": "",
  "Allocations": [
    {
      "allocationID": 10346,
      "invoiceID": 11351,
      "creditNoteID": 10093,
      "amountApplied": 50
    },
    {
      "allocationID": 10347,
      "invoiceID": 11352,
      "creditNoteID": 10093,
      "amountApplied": 50
    },
    {
      "allocationID": 10348,
      "invoiceID": 11380,
      "creditNoteID": 10093,
      "amountApplied": 50
    }
  ]
}

Edit specific credit note

URL

PUT https://api.billagain.com/v1/credits/{creditNoteID}

URL PARAMETERS (1 Field)

Parameter Format Description
creditNoteID req Numeric Unique credit identifier

INPUT PARAMETERS (7 Fields)

Parameter Format Description
customerID req Numeric Unique customer identifier
Amount req Numeric The Amount paid by customer
Credit ref req Alpha Numeric Credit card number reference
CurrencyCode req Alpha 3 letter currency code, eg. ZAR, USD
Date req Date The date of payment
Memo Alpha Numeric Payment Memo
Allocations req Object List List of credit allocations - options:
  • Add - by posting a nested Credit Allocations object and excluding the {allocationID}
  • Edit- by posting a nested Credit Allocations object and including existing {allocationID} connected to the this {creditNoteID}
  • Delete - by not including the existing Credit Allocations object from the credit list
Alternative field options:
  • invoiceID - is required if {invoiceNumber} is empty, note {invoiceID} will always take first priority
  • invoiceNumber - is required if {invoiceID} is empty
allocationID Numeric Unique allocation identifier
amountApplied req Numeric Portion of the payment used to pay invoice
invoiceID req Numeric Unique invoice identifier
invoiceNumber Numeric Unique Invoice identifier

EXAMPLES

JSON Input

{
  "customerID": 269,
  "Date": "05 Apr 2016",
  "CurrencyCode": "ZAR",
  "Amount": 200,
  "CreditNumber" : "424242424242424",
  "Memo": "payment to invoices",
  "Allocations": [
    {
      "invoiceID": 11352,
      "amountApplied": 150
    },
    {
      "amountApplied": 50,
      "invoiceNumber": 957
    }
  ]
}

JSON Output

HTTP CODE: 204 No Content

Delete specific credit note

URL

DELETE https://api.billagain.com/v1/credits/{creditNoteID}

INPUT PARAMETERS (1 Field)

Parameter Format Description
creditNoteID req Numeric Unique credit identifier

EXAMPLES

JSON Output

HTTP CODE: 204 No Content