Entry of a Direct Sales Invoice for a Partially Shipped Sales Order

A point-of-sale (POS) system can create and process a direct sales invoice that contains both of the following types of lines:
  • Lines for which a sales order has been created and a shipment has been created (but the shipment does not include all items of the sales order
  • Lines that have not been linked to any sales order or shipment

To process an invoice of this type, the POS system performs the following steps:

  1. Creates a new sales order of the SO type with multiple items.
  2. Creates a payment.
  3. Creates a sales invoice and adds detail lines for some (but not all) items from the sales order and the new items.
  4. Applies the payment to the invoice.
  5. Releases the invoice. At this moment, not all lines of the sales order are shipped. The sales order has the Open status in MYOB Acumatica. On the Shipments tab of the Sales Orders (SO301000) form, for the sales order lines added to the invoice, a dummy shipment is created with the link to the invoice.
  6. Creates the second payment.
  7. Applies the second payment to the sales order.
  8. Creates a shipment or multiple shipments for the remaining (not shipped) lines of the sales order and confirms each shipment.
  9. Creates a sales invoice for each shipment and releases each invoice. As a result of the release of the invoice or invoices, the sales order gets the Completed status in MYOB Acumatica.
Note: The sales order may not be completed if it was closed by the sales invoice partially (that is, if some lines of the sales order are not shipped or billed).

In this topic, you will implement HTTP requests for the following user scenario. A customer comes to the store and uses a self-service terminal to create a sales order to buy a small jar of apple jam and 10 boxes of larger jars of apple jam. Then the customer picks up a large jar of cherry jam from the store shelves. The customer would like to buy the jar of apple jam (from the sales order) and the selected jar of cherry jam, and to have the 10 boxes shipped to the customer’s home. In a POS system, one sales invoice is created for the purchase in the store and another invoice is created for the boxes to be shipped.

Testing of the Requests

Before you test the code below, you need to do the following to configure your client application and the MYOB Acumatica instance to be used:
  1. Deploy a new MYOB Acumatica instance with the U100 dataset. For details on deploying an instance, see To Deploy an MYOB Acumatica Instance.
  2. 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.
  3. 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.
  4. On the Enable/Disable Features (CS100000) form, make sure that the Inventory and Order Management, Lot and Serial Tracking, and Advanced SO Invoices features are enabled.
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 Sales Order

You use the following example of an HTTP request to create a sales order to sell a small jar of apple jam and 10 boxes of larger jars of apple jam to the FRUITICO customer.

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

{
    "CustomerID": { "value": "FRUITICO" },
    "Details": [
        {
            "Branch": { "value": "HEADOFFICE" },
            "InventoryID": { "value": "APJAM08" },
            "OrderQty": { "value": 1 },
            "UOM": { "value": "PIECE" },
            "WarehouseID": { "value": "WHOLESALE" }
        },
        {
            "Branch": { "value": "HEADOFFICE" },
            "InventoryID": { "value": "APJAM32" },
            "OrderQty": { "value": 10 },
            "UOM": { "value": "BOX" },
            "WarehouseID": { "value": "WHOLESALE" }
        }
    ]
}

Step 2: Create a Payment

You use the following example of an HTTP request to create a payment for the purchase of a jar of apple jam (from the sales order) and a jar of cherry jam.

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

{
    "CashAccount": {"value": "10250ST"},
    "CustomerID": {"value": "FRUITICO"},
    "Hold": {"value": false},
    "PaymentAmount": {"value": 22.91},
    "Type": {"value": "Payment"}
}

Step 3: Release the Payment

You use the following example of an HTTP request to release the payment that you created in the previous step (whose number is assumed to be 000078).

POST /ReleasePayment HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/23.200.001/Payment
Accept: application/json
Content-Type: application/json

{
  "entity" : {
      "ReferenceNbr": {"value": "000078"},
      "Type": {"value": "Payment"}
      },
  "parameters" : {}
}

You would then check the status of this operation (as well as the statuses of other operations in this topic) by performing actions similar to those described in Execute an Action That Is Present in an Endpoint. For simplicity, the checking requests are not provided here.

Step 4: Create a Sales Invoice

You use the following example of an HTTP request to create a sales invoice containing the items for which the payment was created in Step 2. The payment will be applied to the invoice by this request.

PUT ?$expand=ApplicationsInvoice,Details HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/23.200.001/SalesInvoice
Accept: application/json
Content-Type: application/json

{
    "CustomerID": { "value": "FRUITICO" },
    "Type": {"value": "Invoice"},
    "Hold": {"value": false},
    "Details": [
        {
            "Branch": { "value": "HEADOFFICE" },
            "OrderNbr": { "value": "000073" },
            "OrderType": { "value": "SO" },
            "OrderLineNbr": { "value": 1 },
            "Location": { "value": "MAIN" }
        },
        {
            "Branch": { "value": "HEADOFFICE" },
            "InventoryID": { "value": "CHERJAM32" },
            "UOM": { "value": "PIECE" },
            "Qty": { "value": 1 },
            "LotSerialNbr": { "value": "JM2302150000" },
            "Location": { "value": "MAIN" }
        }
    ],
    "ApplicationsInvoice":
    [
        {
            "DocType": {"value": "Payment"},
            "AdjustingDocReferenceNbr": {"value": "000078"},
            "AmountPaid": {"value": 22.91}
        }
    ]
}

Step 5: Release the Sales Invoice

You use the following example of an HTTP request to release the sales invoice that you created in the previous step.

POST /ReleaseSalesInvoice HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/23.200.001/SalesInvoice    
Accept: application/json
Content-Type: application/json

{
  "entity" : {
      "ReferenceNbr": {"value": "000133"},
      "Type": {"value": "Invoice"}
      },
  "parameters" : {}
}

Step 6: Create a Second Payment

You use the following example of an HTTP request to create a payment for the purchase of boxes of apple jam from the sales order that you created in Step 1.

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

{
    "CashAccount": {"value": "10250ST"},
    "CustomerID": {"value": "FRUITICO"},
    "Hold": {"value": false},
    "PaymentAmount": {"value": 1084.4},
    "Type": {"value": "Payment"}
}

Step 7: Release the Payment

You use the following example of an HTTP request to release the payment that you created in the previous step (whose reference number is assumed to be 000079).

POST /ReleasePayment HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/23.200.001/Payment
Accept: application/json
Content-Type: application/json

{
  "entity" : {
      "ReferenceNbr": {"value": "000079"},
      "Type": {"value": "Payment"}
      },
  "parameters" : {}
}

Step 8: Apply the Second Payment to the Sales Order

You use the following example of an HTTP request to apply the payment that you created in Step 6 to the sales order.

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

{
    "OrderNbr": { "value": "000073" },
    "OrderType": { "value": "SO" },
    "Payments": [
        {
            "DocType": { "value": "Payment" },
            "ReferenceNbr": { "value": "000079" },
            "AppliedToOrder": { "value": 1084.4 }
        }
    ]
}

Step 9: Create a Shipment for the Sales Order

You use the following example of an HTTP request to create a shipment for the sales order.

POST /SalesOrderCreateShipment HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/23.200.001/SalesOrder
Accept: application/json
Content-Type: application/json

{
  "entity":{
    "OrderNbr": {"value": "000073"},
    "OrderType":  {"value": "SO"}
  },
  "parameters": {
    "ShipmentDate":  {"value": "2023-02-15T00:00:00+03:00"},
    "WarehouseID":  {"value": "WHOLESALE"}
  }
}

Step 10: Retrieve the Shipment Number

You use the following example of an HTTP request to learn the number of the shipment that you created for the sales order.

GET /SO/000073?$expand=Shipments&$select=OrderNbr,Shipments/ShipmentNbr HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/23.200.001/SalesOrder
Accept: application/json
Content-Type: application/json

Step 11: Confirm the Shipment

You use the following example of an HTTP request to confirm the shipment that you created in Step 9.

POST /ConfirmShipment HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/23.200.001/Shipment
Accept: application/json
Content-Type: application/json

{
  "entity":{
    "ShipmentNbr": {"value": "000071"},
    "ShipmentType":  {"value": "Shipment"}
  },
  "parameters": { }
}

Step 12: Prepare a Sales Invoice for the Shipment

You use the following example of an HTTP request to prepare a sales invoice for the shipment that you created in Step 9.

POST /PrepareInvoice HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/23.200.001/Shipment
Accept: application/json
Content-Type: application/json

{
  "entity":{
    "ShipmentNbr": {"value": "000071"},
    "ShipmentType":  {"value": "Shipment"}
  },
  "parameters": { }
}

Step 13: Retrieve the Sales Invoice Number That Is Referenced in the Shipment

You use the following example of an HTTP request to learn the sales invoice number referenced in the shipment that you created in Step 9.

GET ?$expand=Orders&$select=ShipmentNbr,Orders/InvoiceNbr&
    $filter=ShipmentNbr eq '000071' HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/23.200.001/Shipment
Accept: application/json
Content-Type: application/json

Step 14: Release the Sales Invoice

You use the following example of an HTTP request to release the sales invoice that you prepared in Step 12.

POST /ReleaseSalesInvoice HTTP/1.1
Host: [<Acumatica ERP instance URL>]/entity/Default/23.200.001/SalesInvoice
Accept: application/json
Content-Type: application/json

{
  "entity" : {
      "ReferenceNbr": {"value": "000126"},
      "Type": {"value": "Invoice"}
      },
  "parameters" : {}
}