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.

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 selecting the option "Send acknowledgment".

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:

1. Sign in to your Orderful account:

2. From the left navigation menu, click on Transactions.
3. Find your Transaction and open it.
   This will open the Transaction details page for that Transaction.
4. 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.

There are two ways to do this, depending on which version of the API your integration is built on:

Both are fully supported and do the same thing. The v4 endpoint is easier to integrate against because you never have to build the URL yourself.

Acknowledge using the v4 API

Every inbound delivery — whether Orderful pushes it to your Inbound HTTP Communication Channel or you retrieve it from the Inbox — carries the Transaction's id, plus a transaction object with the acknowledgment URL already built for you:

{
  "id": "019faa61-2fea-719b-a0f8-e6d42fbbc430",
  "integrationPayloadId": "019faa61-3053-76ef-a06c-4ff8ef1c9234",
  "transactionId": 993946486,
  "senderId": "ODFLRETAILTEST",
  "receiverId": "MosaicDemo",
  "stream": "test",
  "message": { "purpose": "original", "purchaseOrderNumber": "PO-V4TEST-006" },
  "ediTransactionType": "850_PURCHASE_ORDER",
  "simplifiedTransactionType": "PURCHASE_ORDER",
  "transaction": {
    "href": "https://{baseUrl}/transactions/019faa61-2fea-719b-a0f8-e6d42fbbc430",
    "acknowledgment": {
      "href": "https://{baseUrl}/transactions/019faa61-2fea-719b-a0f8-e6d42fbbc430/acknowledgment"
    }
  }
}

You have two equivalent ways to acknowledge it, so pick whichever suits your code:

• Use the id value as the Transaction ID in the URL you call.
• POST directly to the transaction.acknowledgment.href you were given, with no URL building at all.

To accept the Transaction, POST to that URL with the orderful-api-version header set to v4:

curl --request POST \
     --url https://{baseUrl}/transactions/019faa61-2fea-719b-a0f8-e6d42fbbc430/acknowledgment \
       // {baseUrl} is api.orderful.com (US) or api-eu.orderful.com (EU)
     --header 'content-type: application/json' \
     --header 'orderful-api-key: YOUR_API_KEY' \
     --header 'orderful-api-version: v4' \
     --data '
{
  "status": "ACCEPTED"
}
'

To reject it with an error message:

curl --request POST \
     --url https://{baseUrl}/transactions/019faa61-2fea-719b-a0f8-e6d42fbbc430/acknowledgment \
       // {baseUrl} is api.orderful.com (US) or api-eu.orderful.com (EU)
     --header 'content-type: application/json' \
     --header 'orderful-api-key: YOUR_API_KEY' \
     --header 'orderful-api-version: v4' \
     --data '
{
  "status": "REJECTED",
  "errors": [
    {
      "path": "/message",
      "code": "00",
      "message": "Purchase order references an unknown ship-to location"
    }
  ]
}
'

A successful acknowledgment returns HTTP 201. Keep these behaviors in mind:

• The orderful-api-version: v4 header is required. Without it the request returns 404.
• Only the receiver of a Transaction can acknowledge it. The sender gets a 403.
• Acknowledging a Transaction that is already ACCEPTED or REJECTED returns 400.
• Get an Acknowledgment returns 404 for a Transaction that has not been acknowledged yet. This is expected for NOT_ACKNOWLEDGED and does not indicate a problem with your integration.
• The id in the delivered payload and the last path segment of transaction.href are always the same value, so the two approaches above are interchangeable.

Acknowledge using the v3 API

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

curl --request GET \
     --url https://{baseUrl}/v3/transactions/123456789/ \
       // {baseUrl} is api.orderful.com (US) or api-eu.orderful.com (EU)
     --header 'accept: application/json' \
     --header 'orderful-api-key: YOUR_API_KEY'

Orderful will then return that Transaction:

{
  "id": "123456789",
  "href": "https://{baseUrl}/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://{baseUrl}/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://{baseUrl}/v3/transactions/123456789/acknowledgment \
           // {baseUrl} is api.orderful.com (US) or api-eu.orderful.com (EU)
     --header 'content-type: application/json' \
     --header 'orderful-api-key: ee82db5009394090bdae7abd81c8aeb7' \
     --data '
{
  "status": "ACCEPTED"
}
'

or

curl --request POST \
     --url https://{baseUrl}/v3/transactions/123456789/acknowledgment \
           // {baseUrl} is api.orderful.com (US) or api-eu.orderful.com (EU)
     --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://{baseUrl}/v3/transactions/123456789/acknowledgment \
           // {baseUrl} is api.orderful.com (US) or api-eu.orderful.com (EU)
     --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:

• Create an Acknowledgment (v4)
• Get an Acknowledgment (v4)
• Create an Acknowledgment (v3)
• Get an Acknowledgment (v3)