> ## 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 customer and looking to send orders to your suppliers.
Throughout this guide you will learn how to send new orders 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](/en/api/v2/overview).
## Process
These are usually the steps taken when sending an order to Procuros:
1. Check, if this document should be sent via Procuros (see: [Enabled Trade Partners](/en/api/v2/features-enabled-trade-partners))
2. Verify this document has not already been sent (see: [Tracking Document Status](/en/api/v2/features-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](/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.
## Send Orders
The API call [Send transaction](/en/api/v2/outgoing-transactions/send-transaction) is used to create transactions, including orders.
The following fields are required:
* `type` (Transaction type. In this case `ORDER`)
* `content` (The details of the order items.)
Inside the `content` you will need to build all order items. All details can be found in the `ORDER` schema as described in the [API reference](/en/api/v2/outgoing-transactions/send-transaction).
The example below shows commonly used fields. The Order schema supports many additional optional fields including:
* **Header level**: `deliveryInformation`, `purchasingInformation`, `legalInformation`, `attachments`, `finalRecipient` party, `technicalRecipient` party, `technicalSender` party
* **Item level**: `size`, `dimension`, `hsCode`, `colorCode`, `colorName`, `fscNumber`, `deliveryGracePeriodInDays`, `certificationsRequired`, `attachments`
**Date format**: All date fields (e.g. `orderDate`, `requestedDeliveryDate`) must use ISO 8601 format: `YYYY-MM-DD` (e.g. `2023-12-06`).
For the complete list of available fields, refer to the OpenAPI schema documentation.
An example request would look like:
```php php theme={null}
// install dependency
// $ composer require guzzlehttp/guzzle
'ORDER',
'content' => [
'header' => [
'orderIdentifier' => 'bestellung-20231203-012',
'orderDate' => '2023-12-03',
'currency' => 'EUR',
'requestedDeliveryDate' => '2023-12-06',
'type' => 'STANDARD',
'comments' => 'Please deliver to loading dock 3',
'contractReference' => 'CONTRACT-2023-ABC',
'buyer' => [
'identifiers' => [
['domain' => 'GS1', 'identifier' => '3220010000010']
]
],
'supplier' => [
'identifiers' => [
['domain' => 'GS1', 'identifier' => '3220010000003']
]
],
'billTo' => [
'identifiers' => [
['domain' => 'GS1', 'identifier' => '3220010000010']
]
],
'shipTo' => [
'identifiers' => [
['domain' => 'GS1', 'identifier' => '3220010000011']
]
],
'technicalRecipient' => [
'identifiers' => [
['domain' => 'GS1', 'identifier' => '3220010000010']
]
],
'technicalSender' => [
'identifiers' => [
['domain' => 'GS1', 'identifier' => '3220010000012']
]
],
'AdditionalOrderIdentifiers' => [
'supplierOrderIdentifier' => 'SUP-ORDER-789',
'shipToOrderIdentifier' => 'SHIP-REF-456'
],
'paymentTerms' => [
[
'payInNumberOfDays' => 30,
'percentage' => 5
]
]
],
'items' => [
[
'identifiers' => [
['domain' => 'GS1', 'identifier' => '2330000000083']
],
'lineNumber' => 1,
'quantity' => 10,
'isDepositItem' => false,
'unitOfMeasure' => 'EA',
'description' => 'Premium Organic Coffee Beans 1kg',
'comments' => 'Please handle with care - fragile packaging',
'requestedDeliveryDate' => null,
'requestedEarliestDeliveryDate' => '2023-12-05',
'requestedLatestDeliveryDate' => '2023-12-08',
'minimumRemainingShelfLifeInDays' => 90,
'unitPrice' => 1.23,
'pricingUnitOfMeasure' => 'CT',
'pricingUnitQuantity' => 100,
'recommendedRetailPrice' => 1.85,
'netWeight' => 1000,
'grossWeight' => 1050,
'originCountryCode' => 'BR',
'tax' => [
'percentage' => 7,
'description' => 'Umsatzsteuer'
],
'brand' => 'kela',
'assortment' => 'ME_GEN',
'consumerGroup' => 'Unisex',
'category' => '1008',
'subCategory' => 'Beverages',
'organicControlPointNumber' => 'DE-ÖKO-006',
'certificationsRequired' => [
'fairtrade' => true,
'supplierQa' => false,
'eudr' => true
],
'contractReference' => 'ITEM-CONTRACT-XYZ',
'promotionCode' => 'WINTER2023',
'attachments' => [
[
'fileName' => 'technical_datasheet.pdf',
'url' => 'https://example.com/attachments/technical_datasheet.pdf',
'mimeType' => 'application/pdf',
'type' => 'TECHNICAL_DATASHEET'
],
[
'fileName' => 'product_label.pdf',
'url' => 'https://example.com/attachments/product_label.pdf',
'mimeType' => 'application/pdf',
'type' => 'PRODUCT_LABEL'
]
],
'modificationGroups' => [
[
'basis' => 12.30,
'level' => 1,
'modifications' => [
[
'type' => 'ALLOWANCE',
'calculationType' => 'RELATIVE',
'reasonCode' => 'DISCOUNT',
'description' => 'Contract trade discount',
'percentage' => 7
]
]
]
]
]
]
]
];
$response = $client->request('POST', 'https://api.procuros.io/v2/transactions', [
'headers' => [
'Accept' => 'application/json',
'Authorization' => 'Bearer ',
],
'json' => $transaction,
]);
```
## Mark Document Status
Finally, as per the instructions mentioned under [Tracking Document Status](/en/api/v2/features-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](/en/api/v2/features-tracking-document-status#retrying-documents).
For example:
```php php theme={null}
$statusCode = $response->getStatusCode();
$responseBody = json_decode($response->getBody()->getContents(), true);
if ($statusCode == 201) {
$document->updateProcurosStatus("TRANSMITTED");
$document->updateProcurosTransactionId($responseBody['procurosTransactionId']);
} else if ($statusCode == 202) {
$document->updateProcurosStatus("NO_ACTION");
$document->updateProcurosTransactionId($responseBody['procurosTransactionId']);
} else {
// No need to do anything if it's not accepted, in an error case the document should be retried.
}
```