Developer Guide

Adjustments

Returns all positive and negative adjustments in a single list for a specific customer

URL

GET https://api.billagain.com/v1/adjustment/list

URL PARAMETERS (4 Fields)

Parameter Format Description
type req Alpha Used to determine which adjustments to fetch (Options : negative, positive, all)
customerID req Numeric Unique customer identifier
page Numeric Current page number
page_size Numeric Amount of items on requested page

OUTPUT PARAMETERS (10 Fields)

Parameter Format Description
adjustmentID Numeric Unique adjustment identifier
customerID Numeric Unique customer identifier
Date Date The date of adjustment
DueDate Date The duedate of adjustment. (Only applies to Positive Adjustments)
CurrencyCode Alpha 3 letter currency code, eg. ZAR, USD
Amount Numeric The Amount of the adjustment
Ref Alpha The Adjustment Ref
Memo Alpha Numeric Adjustment Memo
AdjustmentType Alpha Shows what type of adjustment it is. (Options : refund, opening_balance, credit_note)
Type Alpha Shows whether adjustment is negative or positive

EXAMPLES

JSON Output

HTTP CODE: 200 OK
{
  "isSuccess": true,
  "adjustments": [
    {
      "adjustmentID": 10011,
      "customerID": 20644,
      "Date": "2017-08-16T00:00:00+02:00",
      "DueDate": "2017-08-19T00:00:00+02:00",
      "CurrencyCode": "ZAR",
      "Amount": 240,
      "Ref": "Balance for Customer X",
      "Memo": "",
      "AdjustmentType": "opening_balance",
      "Type": "positive"
    },
    {
      "adjustmentID": 40116,
      "customerID": 20644,
      "Date": "2017-04-12T00:00:00+02:00",
      "DueDate": null,
      "CurrencyCode": "ZAR",
      "Amount": 79.8,
      "Ref": "",
      "Memo": "Cancellation Prorata Credit",
      "AdjustmentType": "credit_note",
      "Type": "negative"
    },
    {
      "adjustmentID": 10008,
      "customerID": 20644,
      "Date": "2017-08-17T00:00:00+02:00",
      "DueDate": "2017-08-21T00:00:00+02:00",
      "CurrencyCode": "ZAR",
      "Amount": 111,
      "Ref": "MY REFUND",
      "Memo": "Refund is treated as a positive adjustment",
      "AdjustmentType": "refund",
      "Type": "positive"
    }
  ]
}

Get a list of adjustments account related

URL

GET https://api.billagain.com/v1/adjustment/list

INPUT PARAMETERS (3 Fields)

Parameter Format Description
type req Alpha Used to determine which adjustments to fetch (Options : negative, positive, all)
page Numeric Current page number
page_size Numeric Amount of items on requested page

OUTPUT PARAMETERS (10 Fields)

Parameter Format Description
adjustmentID Numeric Unique adjustment identifier
customerID Numeric Unique customer identifier
Date Date The date of adjustment
DueDate Date The duedate of adjustment. (Only applies to Positive Adjustments)
CurrencyCode Alpha 3 letter currency code, eg. ZAR, USD
Amount Numeric The Amount of the adjustment
Ref Alpha The Adjustment Ref
Memo Alpha Numeric Adjustment Memo
AdjustmentType Alpha Shows what type of adjustment it is. (Options : refund, opening_balance, credit_note)
Type Alpha Shows whether adjustment is negative or positive

EXAMPLES

JSON Output

HTTP CODE: 200 OK
{
  "isSuccess": true,
  "adjustments": [
    {
      "adjustmentID": 50125,
      "customerID": 20601,
      "Date": "2017-06-06T00:00:00+02:00",
      "DueDate": null,
      "CurrencyCode": "ZAR",
      "Amount": 20,
      "Ref": "1254 ",
      "Memo": null,
      "AdjustmentType": "credit_note",
      "Type": "negative"
    },
    {
      "adjustmentID": 20013,
      "customerID": 41244,
      "Date": "2017-08-23T00:00:00+02:00",
      "DueDate": "2017-08-23T00:00:00+02:00",
      "CurrencyCode": "ZAR",
      "Amount": 15000,
      "Ref": "Opening Balance",
      "Memo": "An opening balances for outstanding balances from a previous system",
      "AdjustmentType": "opening_balance",
      "Type": "positive"
    },
    {
      "adjustmentID": 10008,
      "customerID": 20644,
      "Date": "2017-08-17T00:00:00+02:00",
      "DueDate": "2017-08-21T00:00:00+02:00",
      "CurrencyCode": "ZAR",
      "Amount": 111,
      "Ref": "MY REFUND",
      "Memo": "Refund is treated as a positive adjustment",
      "AdjustmentType": "refund",
      "Type": "positive"
    }
  ]
}

Get specific negative adjustment

URL

GET https://api.billagain.com/v1/adjustment/get

URL PARAMETERS (3 Fields)

Parameter Format Description
type req Alpha Used to determine the type of adjustment to fetch (Options : negative, *positive)
adjustmentID req Numeric Unique adjustment identifier
customerID req Numeric Unique customer identifier

OUTPUT PARAMETERS (13 Fields)

Parameter Format Description
customerID Numeric Unique customer identifier
PositiveAdjustmentID Numeric Unique Positive Adjustment identifier
PositiveAdjustmentType Alpha Positive Adjustment Type (Options : opening_balance, refund, interest)
Date Date The date of payment
DueDate Date The date of payment
Amount Numeric The Adjustment Amount
CurrencyCode Alpha 3 letter currency code, eg. ZAR, USD
Status Alpha The Positive Adjustment status (Options : Paid, Partially Paid, Unpaid)
isActive Boolean Is Positive Adjustment Active
isSuccess Boolean Is Positive Adjustment Success
Ref Alpha Numeric Positive Adjustment Ref
Memo Alpha Numeric Positive Adjustment Memo
Allocations Object List
allocationID Numeric Unique allocation identifier
objectID Numeric If isAdjustment is true then objectID refers to unique NegativeAdjustmentID other wise refers to unique paymentID
amountApplied Numeric Portion of the adjustment used to pay
isAdjustment Boolean Determines whether objectID belongs to an Negative adjustment or an payment

EXAMPLES

JSON Output

HTTP CODE: 200 OK
{
    "isSuccess": true,
    "adjustment": {
        "customerID": 20644,
        "positiveAdjustmentID": 10005,
        "positiveAdjustmentType": "opening_balance",
        "Date": "2017-08-09T00:00:00+02:00",
        "DueDate": "2017-08-15T00:00:00+02:00",
        "Amount": 1500,
        "CurrencyCode": null,
        "Status": "Past Due",
        "isActive": true,
        "isSuccess": true,
        "Ref": "Opening Balance 2",
        "Memo": "",
        "allocations": [
            {
                "allocationID": 62372,
                "objectID": 50142,
                "Amount": 997.73,
                "isAdjustment": false
            }
        ]
    },
    "type": "positive"
}

Add specific adjustment

URL

POST https://api.billagain.com/v1/adjustment/add

INPUT PARAMETERS (8 Fields)

Parameter Format Description
AdjustmentType req Alpha Type of positive Adjustment (Options : opening_balance, refund, interest)
customerID req Numeric Unique customer identifier
Type req Alpha Type of adjustment (Must be set to 'positive' to add positive adjustment)
Amount req Numeric The Adjustment amount
Date req Date The date of adjustment
DateDue req Date The duedate of adjustment
Ref req Alpha Numeric Adjustment reference
Memo Alpha Numeric Adjustment Memo

OUTPUT PARAMETERS (3 Fields)

Parameter Format Description
isSuccess Boolean Unique credit identifier
AdjustmentID Numeric Unique Positive Adjustment identifier
Type Alpha The Type of adjustment

EXAMPLES

JSON Input

{
  "AdjustmentType": "opening_balance",
  "customerID": 20644,
  "Type": "positive",
  "Amount": 1250,
  "Date": "2017-08-21T12:08:16.9810617+00:00",
  "DueDate": "2017-08-21T12:08:16.9810617+00:00",
  "Ref": "Opening Balance 2",
  "Memo": "Api Test Edit Opening Balance"
}

JSON Output

HTTP CODE: 201 Created
{
    "isSuccess": true,
    "AdjustmentID": 20014,
    "Type": "positive"
}

Edit specific Positive Adjustment

URL

PUT https://api.billagain.com/v1/adjustment/edit

INPUT PARAMETERS (11 Fields)

Parameter Format Description
AdjustmentID req Numeric Unique Positive Adjustment identifier
AdjustmentType req Alpha Positive Adjustment identifier
customerID req Numeric Unique customer identifier
Amount req Numeric The Adjustment Amount
Date req Date The date of Adjustment
DueDate req Date The duedate of Adjustment
Ref Alpha Numeric Adjustment Ref
Memo Alpha Numeric Adjustment Memo
Type req Alpha Numeric Adjustment Type (Options : negative, *positive)
isAutoApply req Boolean Auto Apply Adjustments - default set to false
LinkedAllocations req Object List List of adjustment allocations - options:
  • Add - by posting a nested Allocation object and excluding the {allocationID}
  • Edit- by posting a nested Allocation object and including existing {allocationID} connected to the this {AllocationID}
  • Delete - by not including the existing Allocation object from the adjustment list
allocationID Numeric Unique allocation identifier
objectID Numeric If isAdjustment is true then objectID refers to unique NegativeAdjustmentID other wise refers to unique paymentID
AmtAllocated Numeric Portion of the adjustment used to pay
isAdjustment Boolean Determines whether objectID belongs to an Negative adjustment or a payment

OUTPUT PARAMETERS (3 Fields)

Parameter Format Description
isSuccess Boolean Success Boolean Notifier
adjustmentID Numeric Unique Adjustment identifier
type Alpha Adjustment Type (Options : negative, positive)

EXAMPLES

JSON Input

{
  "AdjustmentID": 10005,
  "AdjustmentType": "opening_balance",
  "customerID": 20644,
  "Type": "positive",
  "Amount": 1250,
  "Date": "2017-08-21T12:08:16.9810617+00:00",
  "DueDate": "2017-08-21T12:08:16.9810617+00:00",
  "Ref": "Opening Balance 2",
  "Memo": "Api Test Edit Opening Balance",
  "isAutoApply": false,

  "LinkedAllocations": [
    {
      "allocationID": 62372,
      "objectID": 50142,
      "AmtAllocated": 900.00,
      "isAdjustment": true
    }
  ]
}

JSON Output

HTTP CODE: 204 No Content
{
    "isSuccess": true,
    "adjustmentID": 10005,
    "type": "positive"
}

Get specific positive adjustment

URL

GET https://api.billagain.com/v1/adjustment/get

URL PARAMETERS (3 Fields)

Parameter Format Description
type req Alpha Used to determine the type of adjustment to fetch (Options : *negative, positive)
adjustmentID req Numeric Unique adjustment identifier
customerID req Numeric Unique customer identifier

OUTPUT PARAMETERS (12 Fields)

Parameter Format Description
customerID Numeric Unique customer identifier
NegativeAdjustmentID Numeric Unique negative adjustment identifier
NegativeAdjustmentType Alpha Negative Adjustment Type (Options : credit_note, bad_debt)
Date Date The date of adjustment
Amount Numeric The Amount of the adjustment
CurrencyCode Alpha 3 letter currency code, eg. ZAR, USD
Status Alpha The adjustment status (Options : Allocated, Partially Allocated, Unallocated)
isActive Boolean Is Negative Adjustment Active
isSuccess Boolean Is Negative Adjustment Success
Ref Alpha Numeric Negative Adjustment Ref
Memo Alpha Numeric Negative Adjustment Memo
Allocations Object List
allocationID Numeric Unique allocation identifier
objectID Numeric If isAdjustment is true then objectID refers to unique PositiveAdjustmentID other wise refers to unique InvoiceID
amountApplied Numeric Portion of the adjustment used to pay
isAdjustment Boolean Unique Invoice identifier

EXAMPLES

JSON Output

HTTP CODE: 200 OK
{
    "isSuccess": true,
    "adjustment": {
        "customerID": 20644,
        "NegativeAdjustmentID": 50142,
        "NegativeAdjustmentType": "credit_note",
        "Date": "2017-08-21T12:08:16.9810617+00:00",
        "Amount": 1000,
        "CurrencyCode": "ZAR",
        "Status": "Allocated",
        "isActive": true,
        "isSuccess": true,
        "Ref": "Api_001_cr",
        "Memo": "Api Test Edit Credit",
        "allocations": [
            {
                "allocationID": 62371,
                "objectID": 73747,
                "amountApplied": 2.27,
                "isAdjustment": false
            },
            {
                "allocationID": 62372,
                "objectID": 10005,
                "amountApplied": 997.73,
                "isAdjustment": true
            }
        ]
    },
    "type": "negative"
}

Add specific adjustment

URL

POST https://api.billagain.com/v1/adjustment/add

INPUT PARAMETERS (9 Fields)

Parameter Format Description
AdjustmentType req Alpha Type of negative Adjustment (Options : credit_note, bad_debt)
customerID req Numeric Unique customer identifier
Type req Alpha Type of adjustment (Must be set to 'negative' to add negative adjustment)
Amount req Numeric The Adjustment amount
Date req Date The date of adjustment
Ref req Alpha Numeric Adjustment reference
Memo Alpha Numeric Adjustment Memo
AutoApply Boolean AutoApply conditions:
  • True - the payment will be made to the earliest invoice or positive adjustment and allocations is not required and will not be used
  • False - (false by default) then allocations is required
Allocations req Object List
objectID Numeric If isAdjustment is true then objectID refers to unique PositiveAdjustmentID other wise refers to unique InvoiceID
AmtAllocated Numeric Portion of the adjustment used to pay
isAdjustment Boolean Adjustment identifier ( true - positive adjustemnt, false - invoice )

OUTPUT PARAMETERS (3 Fields)

Parameter Format Description
isSuccess Boolean Unique credit identifier
AdjustmentID Numeric Unique Positive Adjustment identifier
Type Alpha The Type of adjustment

EXAMPLES

JSON Input

{
  "AdjustmentType": "credit_note",
  "customerID": 20644,
  "Type": "negative",
  "Amount": 1250,
  "Date": "2017-08-21T12:08:16.9810617+00:00",
  "Ref": "credit_note 325",
  "Memo": "Api Test Edit Credit",
  "isAutoApply": false,
  "LinkedAllocations": [
    {
      "objectID": 62946,
      "AmtAllocated": 300.00,
      "isAdjustment": false
    },
    {
      "objectID": 10004,
      "AmtAllocated": 950.00,
      "isAdjustment": true
    }
  ]
}

JSON Output

HTTP CODE: 201 Created
{
    "isSuccess": true,
    "AdjustmentID": 50143,
    "Type": "negative"
}

Edit specific Negative Adjustment

URL

PUT https://api.billagain.com/v1/adjustment/edit

INPUT PARAMETERS (11 Fields)

Parameter Format Description
AdjustmentID req Numeric Unique Negative Adjustment identifier
AdjustmentType req Alpha Negative Adjustment Type (Options : credit_note, bad_debt)
customerID req Numeric Unique customer identifier
Amount req Numeric The Amount paid by customer
Date req Date The date of adjustment
DueDate req Date The duedate of adjustment
Ref Alpha Numeric Adjustment Ref
Memo Alpha Numeric Adjustment Memo
Type req Alpha Numeric Adjustment Type (Options : *negative, positive)
isAutoApply req Boolean Auto Apply Allocations - default set to false
Allocations req Object List List of adjustment allocations - options:
  • Add - by posting a nested Allocation object and excluding the {allocationID}
  • Edit- by posting a nested Allocation object and including existing {allocationID} connected to the this {AllocationID}
  • Delete - by not including the existing Allocation object from the adjustment list
allocationID Numeric Unique allocation identifier
objectID Numeric If isAdjustment is true then objectID refers to unique PositiveAdjustmentID other wise refers to unique invoiceID
amountApplied Numeric Portion of the adjustment used to pay
isAdjustment Boolean Determines whether objectID belongs to a Positive adjustment or an invoice

OUTPUT PARAMETERS (3 Fields)

Parameter Format Description
isSuccess Boolean Success Boolean Notifier
adjustmentID Numeric Unique Adjustment identifier
type Alpha Adjustment Type (Options : negative, positive)

EXAMPLES

JSON Input

{
  "AdjustmentID": 50131,
  "AdjustmentType": "credit_note",
  "customerID": 20644,
  "Amount": 1250,
  "Date": "2017-08-21T12:08:16.9810617+00:00",
  "Ref": "credit_note 324",
  "Memo": "Api Test Edit Credit",
  "Type": "negative",
  "isAutoApply": false,
  "LinkedAllocations": [
    {
      "allocationID": 62044,
      "objectID": 62946,
      "AmtAllocated": 300.00,
      "isAdjustment": false
    },
    {
      "allocationID": 62045,
      "objectID": 10006,
      "AmtAllocated": 900.00,
      "isAdjustment": true
    }
  ]
}

JSON Output

HTTP CODE: 204 No Content
{
    "isSuccess": true,
    "adjustmentID": 50131,
    "type": "negative"
}

Delete specific adjustment

URL

DELETE https://api.billagain.com/v1/adjustment/delete

INPUT PARAMETERS (3 Fields)

Parameter Format Description
type req Alpha Used to determine the type of adjustment to fetch (Options : negative, positive)
adjustmentID req Numeric Unique adjustment identifier
customerID req Numeric Unique customer identifier

EXAMPLES

JSON Output

HTTP CODE: 204 No Content