Stock Receipts

Stock receipts are records of stock received at a cinema from vendors. Use our API to create and manage stock receipts in Vista Cloud.

With our API, you can create stock receipts to optimise your inventory management processes.

Requirements

Vendor Receipts

If you're not creating purchase orders in Vista, create a Vendor Receipt to document the items you expect to receive so that you can add them to your inventory when they arrive.

The /vendor-receipts API endpoint allows you to create up to 50 vendor receipts for a site in a single API call. Each request must include a unique clientRequestId, which is echoed back in the response but is not stored in the database.

Example request

Below is a high-level overview of the key workflows and data fields. For full details, refer to the API reference documentation.

Note: The pricesAreTaxInclusive property in a receipt request object does not determine the tax mode of the created receipt. Instead, it indicates whether item prices in the request are inclusive or exclusive, allowing the system to accurately calculate the final amount.

To create a batch of vendor receipts, use:

Sample Request Body (Abbreviated)

{
  "siteId": "1",
  "requests": [
    {
      "clientRequestId": "update-request-1",
      "vendorId": "1",
      "invoiceNumber": "INV-1234",
      "pricesAreTaxInclusive": true,
      "lines": [...],
      ...
    },
    {
      "clientRequestId": "update-request-2",
      "vendorId": null,
      "invoiceNumber": "INV-1235",
      "pricesAreTaxInclusive": true,
      "lines": [...],
      ...
    }
  ]

Response Handling

The API returns a JSON response containing initial processing results for each request. The response includes the original clientRequestId values, allowing you to correlate them with the corresponding requests

The API responds with 202 Accepted if the requests pass initial validation, even if some requests are rejected at later stages of processing. Ensure you inspect the success and errors properties of each response object individually.

{
  "responses": [
    {
      "clientRequestId": "update-request-1",
      "success": true,
      "errors": null,
      "operationResultToken": "<An Operation Result Token>"
    },
    {
      "clientRequestId": "update-request-2",
      "success": false,
      "errors": {
        "StockReceiptMustHaveValidVendor": [
          "The stock receipt vendor must have a valid vendor ID."
        ]
      },
      "operationResultToken": null
    }
  ]
}

For each successfully validated request, the operationResultToken property contains a temporary token that can be used to retrieve the final processing result in a subsequent API call.

Please refer to Operation Result Token for more details.