Approve invoice

The Approve invoice method is used for approving a postpaid invoice in the platform with a third-party invoice issued to an account of the reseller by a third-party ERP system (see Managing Invoices for the Postpay model by a third-party ERP system).

For accounts with several invoices within the same billing period, use another API method and specify the ID of the required invoice — see Approve invoice by ID.

As a result:

  • Optionally, you can specify the amount and currency of a third-party invoice, and then:
    • The amount and currency of the approved invoice in the platform and its linked payment do not change.
    • In the Customer Control Panel, for a payment linked to the approved invoice, a message is displayed with the amount and currency of a third-party invoice.
    • If the amount and currency of a third-party invoice differ from the amount of an invoice in the platform and the reseller currency, a customer cannot pay for it from the account balance. Only other payment methods are available, including ones based on payment gateway connectors (see Managing Payment gateway connectors). On a payment method page (see Payment methods), the specified amount of a third-party invoice is displayed to a customer. The amount of the payment in the platform does not change even after paying.
    • If the amount and currency of a third-party invoice do not differ from the amount of an invoice in the platform and the reseller currency, a customer can pay for it from the account balance or by any other payment method.
    • The specified amount and currency of a third-party invoice can be later retrieved by API from a payment linked to the approved invoice (see Get payment).
  • Optionally, you can attach to a payment linked to the postpaid invoice in the platform a receipt as a file or a link.
  • Optionally, you can specify a custom due date for the linked payment. By default, the due date is set according to the account class of the account.
  • The event handler The Invoice was approved is triggered (see Creating an Event Handler).

After receiving payment for a third-party invoice, it is necessary to approve the payment in the platform by calling the method Complete invoice.

Optionally, a manager can manually approve an invoice for the Postpay model, and approve or cancel its linked payment in the Operator Control Panel:

The platform matches a third-party invoice and invoice for the Postpay model using the start date of the billing period (billing_date). 

An API token of a manager is required for authorization. To get an API token via the Operator Control Panel, see Viewing and updating Manager's information

The manager's API token specified in an API request determines:

  • The role and access level of the manager, which determine the availability of a method.
  • The current reseller and downstream resellers accessible within a method.

POST {base_url}/api/v3/resellers/{reseller_id}/accounts/{account_id}/approve_invoices

Arguments

Name

Parameter Type

Data type

Required/Optional

Description

X-Api-TokenheaderstringRequiredAPI token of a manager that performs the operation (see Viewing and updating Manager's information)
Content-TypeheaderstringRequiredMedia type of the request. Specify the following: application/vnd.api+json
AcceptheaderstringRequired

Supported media types of the answer. Specify the following: application/vnd.api+json

base_urlpathstringRequiredActivePlatform URL
reseller_idpathnumberRequiredID of the current reseller or any of its downstream resellers (see Viewing and updating Reseller general information)
account_idpathnumberRequiredAccount ID
document_idformstringRequiredThird-party invoice name
billing_dateformstringRequiredBilling day (YYYY-MM-DD) — the start date of a billing period linked to the invoice
due_dateformstringOptionalThe payment due date (YYYY-MM-DD) — the latest date for completing a payment. On the next day, an unpaid payment gets the Expired status. Specify if it is necessary to use custom payment expiration period that differs from the account class settings (see Creating an Account Class). The date must be in the future, including the current date
amountformobjectOptionalData about the amount of a third-party invoice issued by an ERP system. Specify if its amount or currency differs from the amount of an invoice in the platform and the reseller currency (see total in Get invoice and currency in Get downstream reseller)

totalformstringOptional

The third-party invoice amount. Must be greater than 0. Required if amount is specified


currencyformstringOptional

The ISO code of the third-party invoice currency. Can be specified the code of any currency in the platform (see Get list of currency rates). Required if amount is specified

attachmentformobjectOptionalData about a receipt for a third-party invoice issued by an ERP system. Specify to attach it to a payment in the platform

typeformstringOptional

The attachment type. Possible values:

  • file — a file itself.
  • link — a link to a file.

dataformstringOptional

Data about a receipt file for a third-party invoice issued by an ERP system:

  • If type = file, specify a file in the base64 encoding.

    A receipt file must be specified using the following template: data:<MIME type>;base64,'<base64 coded string>.

    The following filetypes are supported:

    ExtensionMIME typeExample
    PDFapplication/pdf
    "data": "data:application/pdf;base64,'abc123=='"
    DOCapplication/msword
    "data": "data:application/msword;base64,'abc123=='"
    DOCXapplication/vnd.openxmlformats-officedocument.wordprocessingml.document
    "data": "data:application/vnd.openxmlformats-officedocument.wordprocessingml.document;base64,'abc123=='"
    XLSapplication/vnd.ms-excel
    "data": "data:application/vnd.ms-excel;base64,'abc123=='"
    XLSXapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet
    "data": "data:application/vnd.openxmlformats-officedocument.spreadsheetml.sheet;base64,'abc123=='"

    The maximum file size is defined by the system settings of the platform. To change the limit, contact the support team.

  • If type = link, specify a link to a file.

Required if attachment is specified


nameformstringOptional

The receipt file name for notifications to a customer. Required if attachment is specified

The file name must not contain any slashes /.

Response model

The response model is similar to Get invoice.

Errors

StatusError codeError textComment
400INVOICE-0001Required parameters are not providedSpecify all required parameters in the request
INVOICE-0013Parameter "total" cannot be less than 0 or equal to 0The specified amount of a third-party invoice total is less than or equal to 0, so the invoice cannot be approved
INVOICE-0014Parameter "currency" contains an unsupported currency by the resellerCheck the supported currency codes in Get list of currency rates
INVOICE-0015Parameter "type" contains an unsupported valueCheck the specified type value
INVOICE-0016Payment related to this invoice has been cancelled. Invoice approval is not possibleA manager manually cancelled a linked payment (see Processing a Payment linked to an invoice issued by a third-party ERP system). The invoice cannot be approved or completed
INVOICE-0018Parameter "data" contains an unsupported file formatCheck the format of a receipt file specified in data
INVOICE-0023Parameter "due_date" contains an unsupported valueCheck the format of due_date: YYYY-MM-DD
INVOICE-0024Parameter "due_date" cannot be less than the invoice approval date or equal to the invoice approval dateCheck the date in due_date: it must be in the future, starting from the current date +1 day
404INVOICE-0002Invoice for billing date {billing_date} was not found for account id {account_id}
  • The account does not have an invoice for the specified billing day billing_date.
  • An invoice for the specified billing day billing_date has the total amount equal to 0. The invoice cannot be approved because it does not have information about the linked subscriptions.
422INVOICE-0003Unable to approve invoice one more timeThe invoice is already approved

Request example

POST /api/v3/resellers/1/accounts/505/approve_invoices
Host: test.activeplatform.com
Content-Type: application/vnd.api+json
X-Api-Token: vY5fwetestK3gJXZH5uHCw
Accept: application/vnd.api+json
{
    "document_id": "NS2000015",
    "billing_date": "2020-04-01",
    "amount": {
        "total": "123.45",
        "currency": "USD"
    },
    "attachment": {
        "type": "file",
        "data": "data:application/pdf;base64,'SSBob2xkIHRoZSBwb3NpdGlvbiBvZiBhIHFhIGVuZ2luZWVyLiBRQSBlbmdpbmVlciByZXNwb25zaWJpbGl0aWVzIGluY2x1ZGUgZGVzaWduaW5nIGFuZCBpbXBsZW1lbnRpbmcgdGVzdHMsIGRlYnVnZ2luZyBhbmQgZGVmaW5pbmcgY29ycmVjdGl2ZSBhY3Rpb25zLiBJIGFsc28gcmV2aWV3IHN5c3RlbSByZXF1aXJlbWVudHMgYW5kIHRyYWNrIHF1YWxpdHkgYXNzdXJhbmNlIG1ldHJpY3MgKGUuZy4gZGVmZWN0IGRlbnNpdGllcyBhbmQgb3BlbiBkZWZlY3QgY291bnRzLikgVGhlIFFBIHRlY2huaWNpYW4gcm9sZSBwbGF5cyBhbiBpbXBvcnRhbnQgcGFydCBpbiBvdXIgY29tcGFueeKAmXMgcHJvZHVjdCBkZXZlbG9wbWVudCBwcm9jZXNzLg=='",
        "name": "Invoice NS2000015"
    }
}

Response example

{
    "data": {
        "id": "2046",
        "type": "invoices",
        "attributes": {
            "created_at": "2019-04-18T09:02:01.257560+0300",
            "updated_at": "2019-05-02T06:12:41.990713+0300",
            "document_id": "NS2000015",
            "status": "closed",
            "total": "987.65",
            "account_id": 505,
            "from_date": "2019-04-17",
            "to_date": "2019-05-01",
            "payment_model": "postpay",
            "approved": "true"
        },
        "relationships": {
            "subscriptions": {
                "data": [
                    {
                        "id": "3009839",
                        "type": "subscriptions"
                    }
                ]
            },
            "payments": {
                "data": [
                    {
                        "id": "12201",
                        "type": "payments"
                    }
                ]
            },
            "charges": {
                "data": [
                    {
                        "id": "323740",
                        "type": "charges"
                    }
                ]
            },
            "corrections": {
                "data": []
            }
        }
    }
}