Acknowledge a Transaction

You can explicitly acknowledge the receipt of a Transaction by sending an acknowledgement to your Trading Partner through Orderful. This can be done via a 997 Functional Acknowledgement if you are trading X12, or a JSON equivalent that Orderful offers if you are trading JSON.

📘
Acknowledgments can only be sent once. If you mark a Transaction as "Accepted" or "Rejected" this cannot be undone.

Configure

Orderful gives you the option to explicitly acknowledge any Transactions that you receive from your Trading Partners. The behavior of this acknowledgment differs slightly depending on whether you are trading X12 or JSON.

In both cases the acknowledgments are configured on the Inbound Relationship, by checking the box next to "I will send functional acknowledgements in response to inbound transactions".

Normally, your acknowledgments should be sent automatically by your system. If you are trading X12, your acknowledgments should come in the form of 997 Functional Acknowledgments sent by the backend system ingesting the X12 file. If you are trading JSON, Orderful provides the Acknowledgment API.

For testing and demonstration purposes, you can also acknowledge Transactions manually using the Orderful API.

Acknowledge using the Orderful UI

To acknowledge a Transaction using the Orderful UI, start by finding the Transaction on your Transactions page and clicking on it. This will open the Transaction details page for that Transaction.

At the top of the Transaction details page you will see the Transaction Status information:

If "Acknowledgment Status" is "Not Acknowledged" then you will be able to click on this status and select either Accepted or Rejected.

If you click on Accepted, you will be prompted to confirm that you want to accept the Transaction.

If you click on Rejected, you will be prompted to confirm that you want to reject the Transaction. Once you confirm, another prompt will appear where you can enter in an optional message to be sent along with the rejection.

Acknowledge using the API

If you indicate that you will send acknowledgments for your Inbound Relationship that trades JSON, the transactions you receive through this Relationship will have the Acknowledgment Status NOT_ACKNOWLEDGED until you explicitly acknowledge them using the Create an Acknowledgment API.

To check the Acknowledgment Status of a Transaction, you send a GET to the /transactions endpoint:

curl --request GET \
     --url https://api.orderful.com/v3/transactions/123456789/ \
     --header 'accept: application/json' \
     --header 'orderful-api-key: YOUR_API_KEY'

Orderful will then return that Transaction:

{
  "id": "123456789",
  "href": "https://api.orderful.com/v3/transactions/123456789",
  [...]
  "validationStatus": "VALID",
  "acknowledgmentStatus": "NOT_ACKNOWLEDGED",
  "createdAt": "2021-10-04T17:52:25.688Z",
  "lastUpdatedAt": "2021-11-04T21:35:08.593Z",
  "acknowledgment": {
    "href": "https://api.orderful.com/v3/transactions/123456789/acknowledgment"
  }
}

To update the Transaction's acknowledgmentStatus, create an Acknowledgment by sending a POST to the Transaction's /acknowledgment endpoint with the appropriate status:

curl --request POST \
     --url https://api.orderful.com/v3/transactions/123456789/acknowledgment \
     --header 'content-type: application/json' \
     --header 'orderful-api-key: ee82db5009394090bdae7abd81c8aeb7' \
     --data '
{
  "status": "ACCEPTED"
}
'

curl --request POST \
     --url https://api.orderful.com/v3/transactions/123456789/acknowledgment \
     --header 'content-type: application/json' \
     --header 'orderful-api-key: ee82db5009394090bdae7abd81c8aeb7' \
     --data '
{
  "status": "REJECTED"
}
'

When rejecting an inbound transaction, the Acknowledgment API allows your system to provide an error message. Currently, the API only supports freeform (00) messages at the /message path:

curl --request POST \
     --url https://api.orderful.com/v3/transactions/123456789/acknowledgment \
     --header 'content-type: application/json' \
     --header 'orderful-api-key: ee82db5009394090bdae7abd81c8aeb7' \
     --data '
{
  "status": "REJECTED",
  "errors": [
    {
      "path": "/message",
      "code": "00",
      "message": "This is an error message"
    }
  ]
}
'

The error message is then visible to you and your Trading Partner in the Orderful UI:

After a successful update, Orderful will return an HTTP 201.

For more information see: