Ordering

Ordering is the process of taking one or more material requirements and formally requesting them from the supplier. An order is created in the draft state, and when the user is happy they would place it, which transfers it to the supplier. Suppliers can then either confirm or cancel the order, and the user may also be able to cancel the order after placement if the supplier permits it, depending on their cancelation policy.

Let's create a draft order for the single material requirement we created in the last section:

POST /api/v2/orders
Content-Type: application/json

{ "order": { "material_requirement_ids": ["c727467d-83ff-4711-9ddc-9f84eaa7af71"] } }

HTTP 201 Created
{
  "id": "6baeb914-1174-51a8-a9b3-4d09f01f510a",
  "state": "draft",
  "pricing": {
    "accuracy": "in_verification",
    "total_net_price": "215600.0",
    "total_gross_price": "0.0",
    "net_handling_fee": null,
    "net_shipping_fee": null,
    "taxes": "0.0",
    "taxes_on_fees": null
  },
  "delivery": {
    "accuracy": "in_verification",
    "date": "2022-05-29",
    "desired_delivery_date": "2023-01-01",
    "address": {
      "id": "a060f862-fde7-5ba4-bb60-04ef3d6849ae",
      "addition": null,
      "addressee": "Doe Print Services @ Zaikio",
      "country_code": "DE",
      "county": null,
      "kind": "shipping",
      "location": null,
      "number": null,
      "state": null,
      "street": "Emmerich-Josef-Straße 1A",
      "text": "Emmerich-Josef-Straße 1A, 55116 Mainz",
      "town": "Mainz",
      "zip_code": "55116",
    }
  },
  "order_line_items": [
    {
      "references": ["COL/XTRUAA"],
      "amount": 10000,
      "amount_in_base_unit": 10000,
      "base_unit": "sheet",
      "confirmed_delivery_at": null,
      "description": "Smith Papers Magno Volume",
      "order_number": "BS-5041487395",
      "pricing": {
        "unit_net_price": "21.56",
        "total_net_price": "215600.0",
        "tax_rate": null,
        "taxes": "0.0",
        "total_gross_price": "215600.0"
      },
      "sku": {
        "id": "0c9af85b-1cab-590a-905e-038acd9bdfe3",
        "amount": 1,
        "amount_in_base_unit": 1,
        "environmental_certification": null,
        "order_number": "MAGVOL|115|92.0|65.0|0250|000000||S|SH||v1",
        "palletized": false,
        "unit": "sheet"
      },
      "created_at": "2022-03-29T12:16:41.544Z",
      "updated_at": "2022-03-29T12:16:41.544Z"
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "/api/v2/orders/6baeb914-1174-51a8-a9b3-4d09f01f510a"
    }
  ],
  ...
}

Note: you can also specify multiple requirements to combine into an order. The only rule for combination is that each requirement must be for the same site and supplier. You can express these using order.material_requirement_ids = [id_1, id_2, ...].

This response includes all of the information we have about the order. Pretty much everything here is going to be passed on to the supplier, so it's a good opportunity to verify that the delivery address, items and quantities are correct. Just like material requirements, the accuracy of the pricing/delivery information may update shortly if the value is "in_verification".

If any of the data is wrong, you will need to delete the order, update the material requirement that it came from and then re-create it. For example, if the address is wrong:

DELETE /api/v2/orders/c727467d-83ff-4711-9ddc-9f84eaa7af71

PATCH /api/v2/material_requirements/c727467d-83ff-4711-9ddc-9f84eaa7af71
Content-Type: application/json
{ "material_requirement": { "site_id": ... } }

POST /api/v2/orders
...

If we're happy with this order however, we can go ahead and call the /place endpoint:

POST /api/v2/orders/6baeb914-1174-51a8-a9b3-4d09f01f510a/place

Placed orders will then be transferred to the supplier as soon as possible. Typically suppliers will respond to orders within minutes, but occasionally this can take a bit longer. Any changes to order state will emit Loom events, for example if the supplier confirms it you can listen for procurement_consumer.order_confirmed, and if they reject it you can listen for procurement_consumer.order_canceled. You can also query the orders API at any time to check the status. For more information about order states, please check out the schema.