> ## Documentation Index
> Fetch the complete documentation index at: https://docs.procuros.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Orders

This is the right section for you if you are acting as a supplier and looking to receive orders from your customers.

Throughout this guide you will learn how to pull new orders from the Procuros API, as well as how to paginate over them, mark them as processed, or report errors with the orders.

It is important to mark the orders as processed (either successfully or not) so that the Procuros network can communicate this to your trade partners. This will also prevent them from re-appearing in future `GET` requests for transactions data, as well as trigger the error management process in case you mark any documents as "processing failed".\*\*\*\*

PHP examples are included but you will likely also want to look at the relevant API calls in the [API reference](/en/api/v2/incoming-transactions/list-incoming-transactions).

<Note>
  Trade partners may send updated versions of a document. Always check the `isLatestVersion` field before importing — if it is `false`, a newer version exists and this one should be skipped. See [Document Versioning](/en/api/v2/features-document-versioning) for full details.
</Note>

## Process

Incoming orders retrieved from the Procuros API can be imported into the ERP System.

These are usually the steps taken:

1. Uniquely identify customer (see [Trade Partner + Party Identification](/en/api/v2/features-trade-partner-party-identification))
2. Uniquely identify every product ordered (see [Product Identification](/en/api/v2/features-product-identification))
3. Handle Bottle Deposits (see [Bottle Deposits](/en/api/v2/features-bottle-deposits))
4. Resolve customer-specific prices for products (if not done automatically by ERP-System)

### Rules

As a general rule of thumb: An order retrieved from Procuros and one manually entered by a user should be exactly the same. One exception could be some way to indicate the “source” of the order being “Procuros” instead of “Manual”, “Shopify”, or something else.

## 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](/en/api/v2/concept-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](/en/api/v2/concept-error-handling) section of our API reference for a detailed description plus examples of how to handle them.

## Pull New Orders

The API call [List incoming Transactions](/en/api/v2/incoming-transactions/list-incoming-transactions) is used to fetch all incoming transactions.

<Note>
  The Order response includes all header and item level fields, including:

  * **Header level**: `attachments`, `finalRecipient` party, `technicalRecipient` party, `technicalSender` party, and other party information
  * **Item level**: `attachments`, product specifications, dimensions, certifications, and other item details

  Refer to the OpenAPI schema documentation for the complete list of available fields.
</Note>

<CodeGroup>
  ```php php theme={null}
  // install dependency
  // $ composer require guzzlehttp/guzzle

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

  $client = new \GuzzleHttp\Client();

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

  $body = json_decode((string) $response->getBody());

  $items = $body->items;
  ```
</CodeGroup>

### Pagination

The response body has a `hasMore` flag. If it's `true` not all items are in the response.

You will then want to fetch the other items as well. Therefore, you can use the `nextPageUrl` flag from the response body and perform the same request with the new URL again.

<CodeGroup>
  ```php php theme={null}
  if ($body->hasMore) {
  	$response = $client->request('GET', $body->nextPageUrl, [
      'headers' => [
        'Accept' => 'application/json',
        'Authorization' => 'Bearer <your-api-token>',
      ],
    ]);

    ... // don't forget to check for errors

    $body = json_decode((string) $response->getBody());

    $items = array_merge($items, $body->items);
  }
  ```
</CodeGroup>

<Info>
  If you are running your code only once a day or so, we recommend to perform the request with the new URL until `hasMore` is false. When doing so you can be sure to fetch all currently available items.
</Info>

Please read the [Pagination](/en/api/v2/concept-pagination) section of our API reference for a detailed description.

## Mark Orders as Processed

To mark an order as processed, use the API call [Mark transaction processed](/en/api/v2/incoming-transactions/mark-transaction-processed).

On the happy path of a transaction being processed successfully, you can make an API call such as:

<CodeGroup>
  ```php php theme={null}
  require_once('vendor/autoload.php');

  $client = new \GuzzleHttp\Client();

  $transaction_id = 'abc-123'; // Get the transaction ID from the original `GET /v2/transactions` call
  $response = $client->request('POST', "https://api.procuros.io/v2/transactions/{$transaction_id}", [
    'headers' => [
      'Accept' => 'application/json',
      'Authorization' => 'Bearer <your-api-token>',
    ],
    'json' => [
      'success' => true
    ]
  ]);

  ... // Remember to check the request was successful
  ```
</CodeGroup>

### Mark Multiple Orders as Processed

In addition to the above, you can specify a list of items that should be marked as processed in a single API call, via the [Bulk mark transactions processed](/en/api/v2/incoming-transactions/bulk-mark-transactions-processed) endpoint.

<CodeGroup>
  ```php php theme={null}
  require_once('vendor/autoload.php');

  $client = new \GuzzleHttp\Client();

  // You can find the IDs from the original `GET /v2/transactions` call
  $items = [
    [
      'procurosTransactionId' => 'abc-123',
      'success' => true
    ],
    [
      'procurosTransactionId' => 'def-456',
      'success' => true
    ]
  ];

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

  ... // Remember to check the request was successful
  ```
</CodeGroup>

## Report an Error Processing Orders

In the event an order was not able to be processed, you can use the same 2 API calls listed above ([Mark transaction processed](/en/api/v2/incoming-transactions/mark-transaction-processed) and [Bulk mark transactions processed](/en/api/v2/incoming-transactions/bulk-mark-transactions-processed)) to mark these orders as "failed to process".

In this case you must set the `success` flag to `false`. Additionally you should (but are not required to) add a `reason` for the order not being processed, which will be used for solving the issue.

### Single Order

<CodeGroup>
  ```php php theme={null}
  $transaction_id = 'abc-123';
  $response = $client->request('POST', "https://api.procuros.io/v2/transactions/{$transaction_id}", [
    'headers' => [
      'Accept' => 'application/json',
      'Authorization' => 'Bearer <your-api-token>',
    ],
    'json' => [
      'success' => false,
      'reason' => 'Missing shipping details in order'
    ]
  ]);
  ```
</CodeGroup>

### Bulk Error Reporting

<CodeGroup>
  ```php php theme={null}
  $items = [
    [
      'procurosTransactionId' => 'abc-123',
      'success' => false,
      'reason' => 'Missing shipping details in order'
    ],
    [
      'procurosTransactionId' => 'def-456',
      'success' => true
    ],
  ];

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