Introducing orders on REST
We have officially launched /orders on REST in ‘experimental’ state.
This launch marks the result of months of hard work implementing our sales documents on a much-improved codebase with a much greater focus on cross-platform alignment. The great work put in by the API team is a powerful enabler for the future of sales documents on the REST API. A big win worth mentioning here is the ability to add PDFs to a sales document. Of course, until /invoices is refactored to match /orders, this option is on /orders only.
Regarding schemas and all business logic we have followed the web-application and /invoices as close as possible and we’ve built it with the intent of reusability across sales document endpoints.
Experimental state notes: In the initial experimental state /orders does not support CREATE/UPDATE (write operations) on orders for agreements with the inventory module enabled. Web hooks are not yet implemented on /orders. As a general rule ‘experimental’ denotes we reserve the right to change any parts of the endpoint with short notice (2 weeks).
The endpoints
/drafts – Created.
/sent – Registered as sent. Locked for changes. Has an archived copy. If upgraded to invoice draft or deleted the archived copy is persisted.
/archived – Orders that were registered as sent and either upgraded to invoice or deleted.
The “Orders” view in the web-app lists both /drafts and /sent.
Available operations
The full documentation on /orders can be found in our REST documentation.
Following is a short summary of what you can do on /orders today.
POST & GET on /orders/drafts
When you want to create an order and get the collection of draft orders excluding lines.
The order PDF link is included on each object in the collection.
PUT, GET & DELETE on /orders/drafts/:orderNumber
Update an order (full document), read an order and its lines or even delete the order.
Attachments are added on the individual draft by POSTing to the /attachment/file endpoint.
POST to /orders/sent
Mark an order as sent by moving it to /orders/sent
Move it back to /drafts by POSTing it back to /drafts in order to update the order, add lines, etc. Returning a sent order to draft state will also remove it from /archived.
GET /orders/archived and /orders/archived/:orderNumber
Fetch the collection of archived orders or the individual archived order including its lines.
Archived orders are read-only.
GET /orders/drafts/:orderNumber/templates/upgrade-instructions/draftInvoice
The template for upgrade instructions will provide you with a draft invoice object that when POSTed to /invoices/drafts will upgrade the order to an invoice draft.
We’d love to get your feedback
We encourage early uptake of the endpoint and consider it production stable. This, though, does not mean that there are no bugs. We highly value your feedback on the endpoint as well as any and all bug reports of issues you may encounter. Please feel free to contact us at api@e-conomic.com if you have any feedback. Thank you.