Creation of a Pro Forma Invoice

If you are using the contract-based REST API to integrate MYOB Acumatica with external systems, these external systems can create pro forma invoices and send them by email. For details about pro forma invoices, see Pro Forma Invoices: General Information.

For a pro forma invoice to be created from a project, the project must have Customer, BillingRule, BillingPeriod, and NextBillingDate specified, and must have the Active status. Because of data validation in the project, NextBillingDate cannot be specified for a project with the In Planning status, and you cannot change the customer in a project with the Active status. Therefore, these settings can be specified only in multiple API calls, as shown in the code examples below.

A ProFormaInvoice entity can be created through the invocation of the RunProjectBilling action of the Project entity. Because email settings are not mapped to any fields of the Project entity, you have to prepare a project template with the specified email settings on the Project Templates (PM208000) form and then use this template for the creation of the project through the API. The project template can also contain preconfigured project tasks, as is the case with the PROGRESS template, which is preconfigured in the U100 dataset and used in this example. For details about project templates, see Project Templates and Common Tasks: General Information.

Testing of the Requests

Before you test the code below, you need to configure your client application and the MYOB Acumatica instance to be used as follows:

Deploy a new MYOB Acumatica instance with the U100 dataset. For details on deploying an instance, see To Deploy an MYOB Acumatica Instance.
On the Enable/Disable Features (CS100000) form, make sure the Projects feature is enabled.
To sign in to the instance in the client application, use the tenant name (which you specified when you created the instance) and the HEADOFFICE branch.
If you use Postman as the client application for testing, in the IntegrationDevelopmentGuide.postman_collection.json collection (which is located in the IntegrationDevelopment\Help folder of the Help-and-Training-Examples repository on GitHub), make sure the collection variables have the proper values.

Tip: In the request examples below, <MYOB Acumatica instance URL> is the URL of the MYOB Acumatica instance (such as https://my.acumatica.com/MyInstance). You can omit the instance name in the URL (such as https://my.acumatica.com) if the instance is installed in the root of the website.

Step 1: Create a Project

You first need to create a project from the project template and specify the Customer, BillingRule, and BillingPeriod settings of the project as follows.

PUT / HTTP/1.1
Host: [<MYOB Acumatica instance URL>]/entity/Default/23.200.001/Project
Accept: application/json
Content-Type: application/json

{
    "ProjectID" : {"value" : "TESTPR3"},
    "ProjectTemplateID" : {"value" : "PROGRESS"},
    "Customer" : {"value" : "COFFEESHOP"},
    "BillingAndAllocationSettings" :
    {
        "BillingRule" : {"value" : "PROGRESS"},
        "BillingPeriod" : {"value" : "Month"},
    }
}

Step 2: Make the Project Active

You make the project active, as shown in the following code.

PUT / HTTP/1.1
Host: [<MYOB Acumatica instance URL>]/entity/Default/23.200.001/Project
Accept: application/json
Content-Type: application/json

{
    "ProjectID" : {"value" : "TESTPR3"},
    "Hold" : {"value" : false}
}

Step 3: Specify the Next Billing Date for the Project

You specify NextBillingDate for the project, as shown in the following code.

PUT ?$expand=BillingAndAllocationSettings HTTP/1.1
Host: [<MYOB Acumatica instance URL>]/entity/Default/23.200.001/Project
Accept: application/json
Content-Type: application/json

{
    "ProjectID" : {"value" : "TESTPR3"},
    "BillingAndAllocationSettings" : 
    {
        "NextBillingDate" : {"value" : "2021-08-15"}
    }
}

Step 4: Retrieve a Project Task

You retrieve the PHASE1 project task associated with the created project as follows.

GET ?$filter=ProjectID%20eq%20'TESTPR3'%20and%20ProjectTaskID%20eq%20'PHASE1' HTTP/1.1
Host: [<MYOB Acumatica instance URL>]/entity/Default/23.200.001/ProjectTask
Accept: application/json
Content-Type: application/json

Step 5: Activate a Project Task

You activate the project task as follows.

POST /Activate HTTP/1.1
Host: [<MYOB Acumatica instance URL>]/entity/Default/23.200.001/ProjectTask
Accept: application/json
Content-Type: application/json

{
    "entity":
    {
        "ProjectID": {
            "value": "TESTPR3"
        },
        "ProjectTaskID": {
            "value": "PHASE1"
        }
    },
    "parameters": {}
}

Step 6: Specify the Progress of the Project Task

You use the following code to specify the progress of the project task.

PUT / HTTP/1.1
Host: [<MYOB Acumatica instance URL>]/entity/Default/23.200.001/ProjectBudget
Accept: application/json
Content-Type: application/json

{
  "ProjectTaskID" : {"value" : "PHASE1"},
  "ProjectID" : {"value" : "TESTPR3"},
  "InventoryID" : {"value" : "<N/A>"},
  "Completed" : {"value" : 25},
  "PendingInvoiceAmount" : {"value" : 725}
}

Step 7: Invoke Project Billing

You invoke project billing to create a pro forma invoice as follows.

POST /RunProjectBilling HTTP/1.1
Host: [<MYOB Acumatica instance URL>]/entity/Default/23.200.001/Project
Accept: application/json
Content-Type: application/json

{
  "entity" : {
    "ProjectID": {
        "value": "TESTPR3"
    }
  }
}

HTTP/1.1 202 Accepted
Location: [/<MYOB Acumatica instance URL>]/entity/Default/23.200.001/
    Project/RunProjectBilling/status/6952c6d1-04be-4330-a26e-c6b855ba332c

Step 8: Monitor the Operation Status

You use the following code to monitor the status of the operation until the system returns the 204 No Content code.

GET /RunProjectBilling/status/6952c6d1-04be-4330-a26e-c6b855ba332c HTTP/1.1
Host: [<MYOB Acumatica instance URL>]/entity/Default/23.200.001/Project
Accept: application/json
Content-Type: application/json

HTTP/1.1 204 No Content

Step 9: Retrieve the List of Pro Forma Invoices

You obtain the list of pro forma invoices of the project (which currently contains only one pro forma invoice) by adding $expand=Invoices to the endpoint address, as shown in the following code. For details about parameters, see $expand Parameter.

GET /TESTPR3?$expand=Invoices HTTP/1.1
Host: [<MYOB Acumatica instance URL>]/entity/Default/23.200.001/Project
Accept: application/json
Content-Type: application/json

Step 10: Send the Pro Forma Invoice by Email

You use the following code to send the pro forma invoice by email.

POST /EmailProFormaInvoice HTTP/1.1
Host: [<MYOB Acumatica instance URL>]/entity/Default/23.200.001/ProFormaInvoice
Accept: application/json
Content-Type: application/json

{
  "entity" : {
    "RefNbr": {
        "value": "000019"
    }
  }
}

HTTP/1.1 202 Accepted
Location: [/<MYOB Acumatica instance URL>]/entity/Default/23.200.001/
    ProFormaInvoice/EmailProFormaInvoice/status/a4caa455-0eed-4c11-a5a9-2a8333e53db1

Step 11: Monitor the Sending Operation Status

You use the following code to monitor the status of the operation.

GET /EmailProFormaInvoice/status/a4caa455-0eed-4c11-a5a9-2a8333e53db1 HTTP/1.1
Host: [<MYOB Acumatica instance URL>]/entity/Default/23.200.001/ProFormaInvoice
Accept: application/json
Content-Type: application/json

HTTP/1.1 204 No Content