Appearance
Orders ​
Orders represent purchase transactions placed by a customer. An order captures the full context of a transaction, including the ordered items, delivery and invoice addresses, contact details, surcharges, and attachments such as invoices or delivery notes.
Example
Wood Unlimited is a consumer of the OCP, utilizing the App4Sales application. TreeHouseBuilding Inc. places an order for 500 planks through the webshop.
The order is created in the OCP with the customer code of TreeHouseBuilding Inc., including the order lines, a delivery address, and a contact email.
Creating orders ​
When creating an order, the request is sent as a multipart form to support file uploads (attachments) alongside the order data. The order requires an external identifier and a customer code referencing an existing customer.
Order lines ​
Each order contains one or more order lines representing the individual products being ordered. An order line references an item by its item code and includes quantity, pricing, and unit of measure information.
Order lines support attributes for additional metadata.
Addresses ​
Orders can include multiple addresses, each identified by a type:
| Type | Description |
|---|---|
Delivery | The delivery/shipping address. |
Invoice | The billing/invoice address. |
Other | A general-purpose address. |
Custom | A custom type defined by the user. |
When using the Custom type, provide a custom type value to describe the address purpose.
Addresses support attributes for additional metadata.
Contacts ​
Orders can include multiple contact entries for communication purposes. Each contact is identified by a type:
| Type | Description |
|---|---|
PhoneNumber | A phone number. |
MobileNumber | A mobile phone number. |
Email | An email address. |
Custom | A custom type defined by the user. |
When using the Custom type, provide a custom type value to describe the contact purpose.
Surcharges ​
Surcharges represent additional costs applied to the order beyond the order lines, such as shipping or handling fees. Each surcharge is identified by a type:
| Type | Description |
|---|---|
Shipping | Shipping or delivery costs. |
Handling | Handling or processing fees. |
Payment | Payment-related surcharges. |
Custom | A custom type defined by the user. |
When using the Custom type, provide a custom type value to describe the surcharge.
Surcharges support attributes for additional metadata.
Attachments ​
Attachments provide files related to an order, such as invoices, delivery notes, or credit notes. Attachments can be included when creating the order or managed separately through the attachment endpoints. Each attachment is identified by a type:
| Type | Description |
|---|---|
Invoice | An invoice document. |
DeliveryNote | A delivery note document. |
CreditNote | A credit note document. |
Custom | A custom type defined by the user. |
When using the Custom type, provide a custom type value to describe the attachment.
Attachments must meet the following requirements:
- Maximum file size is 5MB.
- Attachment should be of type JPG, PNG, PDF, XLS, XLSX, DOC or DOCX.
When an attachment is uploaded, a hash (MD5) is generated and returned in the response. You can use that hash to compare if the attachment is outdated.
Attachments can be retrieved individually, listed for an order, or downloaded via the download endpoint.
Log entries ​
Orders maintain a log of notable events. Each log entry can optionally reference an attachment and includes a title, description, and the actor who performed the action.
Attributes ​
Orders, order lines, addresses, and surcharges have support for attributes usage.
Retrieving orders ​
Orders can be retrieved by their unique identifier, as a paginated list, or filtered by customer code. When retrieving orders by customer, a summary representation is returned.