Skip to main content
This is the right section for you if you are acting as a supplier and looking to send Order Responses to your customers in response to their orders. Throughout this guide you will learn how to send Order Responses to the Procuros API. PHP examples are included but you will likely also want to look at the relevant API calls in the API reference.

​
Order Response Types

Order Responses can have one of three types:
  • ACCEPT: Use when the order is accepted exactly as ordered. No items array is required.
  • REJECT: Use when the order is fully rejected. No items array is required.
  • CHANGE: Use when part of the order is accepted but either line item quantities or delivery date are changed. The items array is required and must contain ALL order line items.

​
Process

These are usually the steps taken when sending an Order Response to Procuros:
  1. Check, if this document should be sent via Procuros (see: Enabled Trade Partners)
  2. Verify this document has not already been sent (see: Tracking Document Status)
  3. Build the transaction payload to be sent via Procuros
  4. Send the transaction payload via the Procuros API

​
Authentication

You will need an API token to authenticate. We use a bearer token which has to be included in each request you send to the API. Please read the Authentication section of our API reference for a detailed description.

​
Error Handling

The API will return a 2xx status code for successful requests. Anything else indicates an error. Please read the Errors section of our API reference for a detailed description plus examples of how to handle them.

​
Send Order Responses

The API call Send transaction is used to create transactions, including Order Responses. The following fields are required:
  • type (Transaction type. In this case ORDER_RESPONSE)
  • content (The details of the Order Response)
Inside the content you will need to build the Order Response header and optionally items. All details can be found in the ORDER_RESPONSE schema as described in the API reference.

​
Example: ACCEPT Response

Use this when accepting an order exactly as ordered: 
// install dependency
// $ composer require guzzlehttp/guzzle

<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$transaction = [
    'type' => 'ORDER_RESPONSE',
    'content' => [
        'header' => [
            'type' => 'ACCEPT',
            'buyer' => [
                'identifiers' => [
                    ['domain' => 'GS1', 'identifier' => '1100001016310']
                ]
            ],
            'supplier' => [
                'identifiers' => [
                    ['domain' => 'GS1', 'identifier' => '1100001016312']
                ]
            ],
            'orderResponseIdentifier' => 'RE-PO9383-R45',
            'orderResponseDate' => '2024-01-15',
            'orderIdentifier' => 'PO9383-R45',
            'orderDate' => '2024-01-14',
            'requestedDeliveryDate' => '2024-01-20',
            'confirmedDeliveryDate' => '2024-01-20',
            'currency' => 'EUR'
        ]
    ]
];

$response = $client->request('POST', 'https://api.procuros.io/v2/transactions', [
  'headers' => [
    'Accept' => 'application/json',
    'Authorization' => 'Bearer <your-api-token>',
  ],
  'json' => $transaction,
]);

​
Example: REJECT Response

Use this when fully rejecting an order: 
$transaction = [
    'type' => 'ORDER_RESPONSE',
    'content' => [
        'header' => [
            'type' => 'REJECT',
            'buyer' => [
                'identifiers' => [
                    ['domain' => 'GS1', 'identifier' => '1100001016310']
                ]
            ],
            'supplier' => [
                'identifiers' => [
                    ['domain' => 'GS1', 'identifier' => '1100001016312']
                ]
            ],
            'orderResponseIdentifier' => 'RE-PO9383-R45',
            'orderResponseDate' => '2024-01-15',
            'orderIdentifier' => 'PO9383-R45',
            'orderDate' => '2024-01-14',
            'currency' => 'EUR',
            'comments' => 'Order rejected due to product unavailability'
        ]
    ]
];

$response = $client->request('POST', 'https://api.procuros.io/v2/transactions', [
  'headers' => [
    'Accept' => 'application/json',
    'Authorization' => 'Bearer <your-api-token>',
  ],
  'json' => $transaction,
]);

​
Example: CHANGE Response

Use this when partially accepting an order with quantity or delivery date changes. The items array must contain ALL order line items, showing both ordered and confirmed quantities: 
$transaction = [
    'type' => 'ORDER_RESPONSE',
    'content' => [
        'header' => [
            'type' => 'CHANGE',
            'buyer' => [
                'identifiers' => [
                    ['domain' => 'GS1', 'identifier' => '1100001016310']
                ]
            ],
            'supplier' => [
                'identifiers' => [
                    ['domain' => 'GS1', 'identifier' => '1100001016312']
                ]
            ],
            'orderResponseIdentifier' => 'RE-PO9383-R45',
            'orderResponseDate' => '2024-01-15',
            'orderIdentifier' => 'PO9383-R45',
            'orderDate' => '2024-01-14',
            'requestedDeliveryDate' => '2024-01-20',
            'confirmedDeliveryDate' => '2024-01-22',
            'currency' => 'EUR',
            'comments' => 'Partial fulfillment due to limited stock'
        ],
        'items' => [
            [
                'lineNumber' => 1,
                'identifiers' => [
                    ['domain' => 'GS1', 'identifier' => '4300348765432']
                ],
                'isDepositItem' => false,
                'orderedQuantity' => 20.0,
                'confirmedQuantity' => 15.0,
                'unitOfMeasure' => 'EA',
                'description' => 'First product description',
                'unitPrice' => 0.15,
                'pricingUnitOfMeasure' => 'CT',
                'pricingUnitQuantity' => 100
            ],
            [
                'lineNumber' => 2,
                'identifiers' => [
                    ['domain' => 'GS1', 'identifier' => '4300348765433']
                ],
                'isDepositItem' => false,
                'orderedQuantity' => 19.0,
                'confirmedQuantity' => 19.0,
                'unitOfMeasure' => 'EA',
                'description' => 'Second product description',
                'unitPrice' => 1.50,
                'pricingUnitOfMeasure' => 'CT'
                'pricingUnitQuantity' => 100,              
            ]
        ]
    ]
];

$response = $client->request('POST', 'https://api.procuros.io/v2/transactions', [
  'headers' => [
    'Accept' => 'application/json',
    'Authorization' => 'Bearer <your-api-token>',
  ],
  'json' => $transaction,
]);
When using the CHANGE type, the items array must contain ALL order line items, regardless of whether orderedQuantity and confirmedQuantity are equal. This allows the buyer to see the complete picture of what will be delivered.

​
Mark Document Status

Finally, as per the instructions mentioned under Tracking Document Status you must now track the status of the document locally, based on the returned HTTP response. The document should be marked with either status TRANSMITTED or NO_ACTION. If there is an error with the document and it is not accepted, do not mark it with a status so it may be retried. For more information on retrying failed documents, please see: Retrying Documents. For example: 
$statusCode = $response->getStatusCode();

if ($statusCode == 201) {
  $document->updateProcurosStatus("TRANSMITTED");
} else if ($statusCode == 202) {
  $document->updateProcurosStatus("NO_ACTION");
} else {
  // No need to do anything if it's not accepted, in an error case the document should be retried.
}