4WS Suite
Home
API Reference
  • Data mangement API
  • Documents API
Home
API Reference
  • Data mangement API
  • Documents API
Fourwayshop
  1. Orchestrated Orders
  • Document Manager
    • Orders
      • Save Sale Order
      • Save Return Order
    • Orchestrated Orders
      • Orchestrated Order
        POST
      • Orchestrated Return order
        POST
      • Orchestrated Update order
        POST
    • Cart
      • Cart Validation
      • Cart Full Validation
    • Sales
      • Save receipt
      • Salve only Order
      • Replace or update sale
      • Get last digital order
    • Warehouse
      • Save Entry from supplier
      • Save Transfer document
      • Save Free Entry
    • Purchase
      • Save Purchase
    • Get Document
      GET
    • Update Document external references
      POST
  • Customer
    • Get Customer
      GET
    • Set Customer Opt-in
      POST
  • Loyalty vouchers
    • Get customer loyalty vouchers
      GET
    • Get loyalty vouchers at a time interval
      GET
    • Get last loyalty vouchers
      GET
  • Giftcard
    • Get Giftcard
      GET
    • Update Giftcard
      POST
    • Generate Gift Card Barcode
      POST
    • Gift Card PDF Generation
      POST
  • Stock
    • Get Stock
      POST
    • Get last stock
      GET
    • Insert Stock
      POST
  1. Orchestrated Orders

Orchestrated Update order

Tested
POST
/api
Last modified:2025-10-08 09:33:18
Available from release:3.2.1

Update An Existing Sale Order#

This API allows external systems to update an existing sale order identified by a unique transactionId.
The API checks whether the provided transactionId exists.
If the order is found, it is updated with the new details provided in the request payload.
If the transactionId does not exist, the API returns an error indicating that no matching order was found.
This integration ensures data consistency across systems (e.g., POS, CRM, eCommerce) by enabling reliable updates to existing transactions.
Document date
All Date information within the API is expressed in the GMT time zone.
API users are therefore responsible for converting dates to their desired time zone if needed.
Please refer to Date Handling

Actors#

API Client: The system or user initiating the request.
4ws.trade: The backend system that processes the request.

Preconditions#

The external system must have the necessary permissions and access to the document creation service, please refer to Authentication.
The transactionId must exist in the system for the update to succeed.
The callback URL must be functional and ready to receive POST requests.

Main Success Scenario#

1.
The caller sends a POST request with a valid transactionId and updated sale order data.
2.
The API validates authentication and request payload.
3.
The system checks if the transactionId exists.
4.
If found, the sale order is updated successfully.
5.
The callback URL provided in the request (callback) is invoked with the updated order status and confirmation.
external system and transactionId
It is strongly recommended that the external system store the unique doc ID 02931b8a-a6c8-4e47-b3f1-041ffb1e432q.
Request example

Removing or Replacing an Item#

Removing an Item
To remove an item, simply send the original validated order JSON while removing the specific row from the items array that should no longer be orchestrated.
Replacing an Item
To replace an item, keep the same rowId and update the values of the row (e.g., price, description, etc.).
If you need to replace a product with another one, you only need to keep the rowId and change the product’s barcode, then call the Cart Full Validation API again, followed by the product update API.
Important:
it is considered a best practice to always invoke Cart Full Validation before performing any update.

Field receiptType#

The receiptType field defines the type of administrative document that will be generated when creating a sales order.
The following values are allowed:
TICKET → the issued document will be a fiscal receipt.
INVOICE → the issued document will be a sales invoice. In this case, the invoiceClient field must also be provided, containing the tax and personal details of the customer requesting the invoice.
The invoiceClient field is a JSON object that may include information such as address, tax code, VAT number, legal nature, and contact details.
Note:
the invoiceClient data is not validated by the Four Way Shop api. It is the caller’s responsibility to ensure the correctness and completeness of the provided information.
`receiptType = INVOICE`

Callback#

The callback url will be called in POST when the request has ended. In case of success the callback reuqest body is the following JSON:
{
    "success": true,
    "barcode": "123456789012",
    "documentNumber": "1",
    "payload": "request payload"
}
otherwise:
{
    "success": false,
    "message": "Error message"
}

Alternate Flows#

Authentication Error: If the client does not provide valid credentials, an error response is returned.
Authentication Error Example
Invalid TransactionId Error: If the client does not provide valid transactionId an error response is returned.
Invalid TransactionId Error Example
Invalid Product or Barcode Code: If an invalid itemCode o barcode is provided, the API returns an error.
Invalid Product or Barcode Code Example
Update order not allowed for channel Code: If the sales channelchannelis IN STORE or DIGITAL, order updates are not permitted.
Invalid Product or Barcode Code Example
Manually managed order cannot be updated: If the order is managed manually by the head office, updating is not permitted.
Invalid Product or Barcode Code Example

Sequence Diagram (Mermaid)#

Code Examples in Node.js#

Request

Query Params

Header Params

Body Params application/json

Example
{
    "seller": "Filippo Giacomelli",
    "zReportNumber": "20220621",
    "clientName": "DANIEL",
    "pointsUsed": "0400",
    "docNumber": 11,
    "endDate": "2022-06-21 13:13:44",
    "goodsVoucher": [],
    "payments": [
        {
            "paymentType": "E",
            "paymentCode": "CC",
            "paymentDescription": "Carta di credito",
            "paymentImg": "carte-ok.png",
            "paymentCash": 368,
            "channel": "IN_STORE",
            "paymentProgr": "70AE705B-147F-4E46-8569-F9441DEA128C",
            "paymentRoundingAmount": 0,
            "paymentAmount": 368,
            "paymentChange": 0,
            "paymentDone": "Y"
        },
        {
            "paymentType": "C",
            "paymentCode": "CONTANTI",
            "paymentDescription": "Contanti",
            "paymentImg": "contanti-euro.png",
            "paymentCash": 150,
            "channel": "IN_STORE",
            "paymentProgr": "9090BAEE-0C8E-4E88-A955-8A9194093DA6",
            "paymentRoundingAmount": 0,
            "paymentAmount": 122,
            "paymentChange": 28,
            "paymentDone": "Y"
        }
    ],
    "masterRegister": "N",
    "clientDenomination": "GIACOMELLI DANIEL",
    "clientSurname": "GIACOMELLI",
    "deviceId": "5327E23B-CB96-4BAF-AC01-88E978267021",
    "pointsCode": "OK",
    "printerCode": "LUNGO_501_501_1070_TM-m30II-NT",
    "pointsEarned": 980,
    "sellerId": "777",
    "movementType": "V",
    "pointsPrevious": 720,
    "barcodeInfo": "10701070222062100011",
    "currency": "EUR",
    "discountsManualCumulative": "Y",
    "deliveryDate": "2022-06-28 15:07:12",
    "registerCode": "10702",
    "clientBarcode": "8966",
    "delivery": [],
    "entityCode": "501",
    "clientId": 47109,
    "ticket": 11,
    "clientEmail": "scazdaniel@gmail.com",
    "pointsBalance": 1300,
    "pointsMessage": "OK",
    "currencySymbol": "€",
    "rounding": 2,
    "totals": {
        "totalDiscount": 10,
        "totalDiscountType": "N",
        "totalDiscountReasonDescription": "LOYALTY - Sconto con scelta fasce",
        "totalDiscountAmount": 10,
        "total": 490,
        "vat": 0,
        "grandTotal": 490,
        "inStoreGrandTotal": 490,
        "digitalGrandTotal": 0,
        "totalDeposits": 0,
        "totalDepositsVat": 0,
        "allowance": 0,
        "alreadyPayed": 0,
        "taxableIncome": 490,
        "autoTotalDiscountType": "PROMO"
    },
    "transactionId": "1fe0a4f9-a1ce-4963-9f18-94eb5fbf16a4",
    "branchCode": "1070",
    "onlineValidation": "Y",
    "filling": "FIRST",
    "appliedPromotions": [
        {
            "idPromozione": "50120220505104019",
            "description": "LOYALTY - Sconto con scelta fasce",
            "multipleDiscount": 1,
            "discounts": [
                {
                    "vantaggio": 10,
                    "consumedPoints": 400
                }
            ],
            "barcode": "13061360122101101",
            "status": "ACCEPTED",
            "discountType": "TOTAL",
            "callbackAction": 10609,
            "vantaggio": "10",
            "consumedPoints": "400"
        }
    ],
    "ticketRT": 11,
    "candidatePromos": [
        {
            "idPromozione": "50120220505104019",
            "description": "LOYALTY - Sconto con scelta fasce",
            "multipleDiscount": 1,
            "discounts": [
                {
                    "vantaggio": 10,
                    "consumedPoints": 400
                }
            ],
            "barcode": "13061360122101101",
            "status": "ACCEPTED",
            "discountType": "TOTAL",
            "callbackAction": 10609,
            "vantaggio": "10",
            "consumedPoints": "400"
        }
    ],
    "items": [
        {
            "rowId": "B59FAFB3-6265-4EAD-B3AD-B4B2B0582425",
            "rowType": "ITEM",
            "barcode": "13061360122101101",
            "barcodeType": "BARCODE_ARTICOLO",
            "unitPrice": 500,
            "qty": 1,
            "qtyType": "N",
            "itemState": "SERVER_OK",
            "seller": "Filippo Giacomelli",
            "sellerId": "777",
            "taxRate": 0,
            "vatCode": "4",
            "rowTaxableIncome": 490,
            "rowVat": 0,
            "rowTotal": 490,
            "itemType": "PRODUCT",
            "movementType": "V",
            "havingTailoring": "N",
            "priceList": "1070",
            "channel": "IN_STORE",
            "addTimestamp": 1655816803158,
            "itemCode": "SA1VX0009 P4517",
            "currencySymbol": "€",
            "currency": "EUR",
            "rounding": 2,
            "shopDescription": "PORTACARTE",
            "description": "PORTACARTE",
            "dimensionDescription1": "TU",
            "dimensionDescription2": "T8013 - BLACK",
            "attributeLevel1": "1",
            "hierarchyLevel1": "30",
            "attributeLevel2": "1",
            "hierarchyLevel2": "3063",
            "attributeLevel3": "360",
            "hierarchyLevel3": "61",
            "dimension1": "TU",
            "dimension2": "T8013#@#BLACK",
            "dimensionType1": "TAGLIA",
            "dimensionType2": "COLORE",
            "dimensionGroup1": "TAUN",
            "dimensionGroup2": "360",
            "discountTotalAmount": 10,
            "discountRowTotalAmount": 10,
            "originalUnitPrice": 180,
            "priceForcingReason": "FORZA",
            "rowOrder": 1
        }
    ],
    "transactionState": 1,
    "startDate": "2022-06-21 13:06:43",
    "printerSerial": "NOFISCAL",
    "printerTaxation": "NOFISC"
}

Request Code Samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location -g --request POST '/api?applicationId={{APPLICATION_ID}}&appId={{APPLICATION_ID}}&cmd=updateOrder_v1' \
--header 'applicationId: {{APPLICATION_ID}}' \
--header 'appId: {{APPLICATION_ID}}' \
--header 'namespace: {{NAMESPACE}}' \
--header 'languageId: {{LANGUAGE}}' \
--header 'username: {{USERNAME}}' \
--header 'password: {{PASSWORD}}' \
--header 'companyId: {{COMPANY_ID}}' \
--header 'siteId: {{SITE_ID}}' \
--header 'loadRoles: Y' \
--header 'Content-Type: application/json' \
--data-raw '{
    "seller": "Filippo Giacomelli",
    "zReportNumber": "20220621",
    "clientName": "DANIEL",
    "pointsUsed": "0400",
    "docNumber": 11,
    "endDate": "2022-06-21 13:13:44",
    "goodsVoucher": [],
    "payments": [
        {
            "paymentType": "E",
            "paymentCode": "CC",
            "paymentDescription": "Carta di credito",
            "paymentImg": "carte-ok.png",
            "paymentCash": 368,
            "channel": "IN_STORE",
            "paymentProgr": "70AE705B-147F-4E46-8569-F9441DEA128C",
            "paymentRoundingAmount": 0,
            "paymentAmount": 368,
            "paymentChange": 0,
            "paymentDone": "Y"
        },
        {
            "paymentType": "C",
            "paymentCode": "CONTANTI",
            "paymentDescription": "Contanti",
            "paymentImg": "contanti-euro.png",
            "paymentCash": 150,
            "channel": "IN_STORE",
            "paymentProgr": "9090BAEE-0C8E-4E88-A955-8A9194093DA6",
            "paymentRoundingAmount": 0,
            "paymentAmount": 122,
            "paymentChange": 28,
            "paymentDone": "Y"
        }
    ],
    "masterRegister": "N",
    "clientDenomination": "GIACOMELLI DANIEL",
    "clientSurname": "GIACOMELLI",
    "deviceId": "5327E23B-CB96-4BAF-AC01-88E978267021",
    "pointsCode": "OK",
    "printerCode": "LUNGO_501_501_1070_TM-m30II-NT",
    "pointsEarned": 980,
    "sellerId": "777",
    "movementType": "V",
    "pointsPrevious": 720,
    "barcodeInfo": "10701070222062100011",
    "currency": "EUR",
    "discountsManualCumulative": "Y",
    "deliveryDate": "2022-06-28 15:07:12",
    "registerCode": "10702",
    "clientBarcode": "8966",
    "delivery": [],
    "entityCode": "501",
    "clientId": 47109,
    "ticket": 11,
    "clientEmail": "scazdaniel@gmail.com",
    "pointsBalance": 1300,
    "pointsMessage": "OK",
    "currencySymbol": "€",
    "rounding": 2,
    "totals": {
        "totalDiscount": 10,
        "totalDiscountType": "N",
        "totalDiscountReasonDescription": "LOYALTY - Sconto con scelta fasce",
        "totalDiscountAmount": 10,
        "total": 490,
        "vat": 0,
        "grandTotal": 490,
        "inStoreGrandTotal": 490,
        "digitalGrandTotal": 0,
        "totalDeposits": 0,
        "totalDepositsVat": 0,
        "allowance": 0,
        "alreadyPayed": 0,
        "taxableIncome": 490,
        "autoTotalDiscountType": "PROMO"
    },
    "transactionId": "1fe0a4f9-a1ce-4963-9f18-94eb5fbf16a4",
    "branchCode": "1070",
    "onlineValidation": "Y",
    "filling": "FIRST",
    "appliedPromotions": [
        {
            "idPromozione": "50120220505104019",
            "description": "LOYALTY - Sconto con scelta fasce",
            "multipleDiscount": 1,
            "discounts": [
                {
                    "vantaggio": 10,
                    "consumedPoints": 400
                }
            ],
            "barcode": "13061360122101101",
            "status": "ACCEPTED",
            "discountType": "TOTAL",
            "callbackAction": 10609,
            "vantaggio": "10",
            "consumedPoints": "400"
        }
    ],
    "ticketRT": 11,
    "candidatePromos": [
        {
            "idPromozione": "50120220505104019",
            "description": "LOYALTY - Sconto con scelta fasce",
            "multipleDiscount": 1,
            "discounts": [
                {
                    "vantaggio": 10,
                    "consumedPoints": 400
                }
            ],
            "barcode": "13061360122101101",
            "status": "ACCEPTED",
            "discountType": "TOTAL",
            "callbackAction": 10609,
            "vantaggio": "10",
            "consumedPoints": "400"
        }
    ],
    "items": [
        {
            "rowId": "B59FAFB3-6265-4EAD-B3AD-B4B2B0582425",
            "rowType": "ITEM",
            "barcode": "13061360122101101",
            "barcodeType": "BARCODE_ARTICOLO",
            "unitPrice": 500,
            "qty": 1,
            "qtyType": "N",
            "itemState": "SERVER_OK",
            "seller": "Filippo Giacomelli",
            "sellerId": "777",
            "taxRate": 0,
            "vatCode": "4",
            "rowTaxableIncome": 490,
            "rowVat": 0,
            "rowTotal": 490,
            "itemType": "PRODUCT",
            "movementType": "V",
            "havingTailoring": "N",
            "priceList": "1070",
            "channel": "IN_STORE",
            "addTimestamp": 1655816803158,
            "itemCode": "SA1VX0009 P4517",
            "currencySymbol": "€",
            "currency": "EUR",
            "rounding": 2,
            "shopDescription": "PORTACARTE",
            "description": "PORTACARTE",
            "dimensionDescription1": "TU",
            "dimensionDescription2": "T8013 - BLACK",
            "attributeLevel1": "1",
            "hierarchyLevel1": "30",
            "attributeLevel2": "1",
            "hierarchyLevel2": "3063",
            "attributeLevel3": "360",
            "hierarchyLevel3": "61",
            "dimension1": "TU",
            "dimension2": "T8013#@#BLACK",
            "dimensionType1": "TAGLIA",
            "dimensionType2": "COLORE",
            "dimensionGroup1": "TAUN",
            "dimensionGroup2": "360",
            "discountTotalAmount": 10,
            "discountRowTotalAmount": 10,
            "originalUnitPrice": 180,
            "priceForcingReason": "FORZA",
            "rowOrder": 1
        }
    ],
    "transactionState": 1,
    "startDate": "2022-06-21 13:06:43",
    "printerSerial": "NOFISCAL",
    "printerTaxation": "NOFISC"
}'

Responses

🟢200Save cart - success
application/json
Body

Example
{
    "success": true
}
🟠422Unique constraint error
Modified at 2025-10-08 09:33:18
Previous
Orchestrated Return order
Next
Cart Validation
Built with