What you can automate

Automate the following actions using Order API: order creation featuring all order details, order status change (such as approving or rejecting an order), and more.  Refer to the Order object model for the complete list.

Order object model

Receive an order from EduMS

Before you begin: subscribe to webhooks

In order to get updated about new orders, it is highly recommended to subscribe to our webhooks. Refer to the details in the Webhook section.

Create an order

1. Obtain the Bearer token. You are now able to create orders for the account with the ID:  account-id50757d0c-0b56-4ff7-a3a9-115fdc18ffc3.

2. Verify that you are subscribed to the appropriate order webhook for your provider ID.

3. Go to the POST Order endpoint in the Order API, with it you can generate orders. See the example of a valid request body below.

4. Generate an order. After the order is generated, EduMS performs a so-called slow validation process to verify the validity of the order details. This typically takes a few seconds. You can proceed to the next step in the meantime.

5. Copy the order ID from the response and use it in the GET order details endpoint. If the order status is "PendingProvider", then the order has passed the validations and was successfully created. If the order status is "Invalid", there was an issue. Check the errors object to debug.

   ☝️Make sure to use the order id (guid, XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX) and not the order number (8 numbers).

6. To test your workflow, you can accept the order or check the provided callback URL to test the webhook.

Body request example

{ 
   "accountReference": "50757d0c-0b56-4ff7-a3a9-115fdc18ffc3", 
   "productReference": "{productId}", 
   "OrderType": "Course", 
   "name": "Test course for testing orders", 
   "customer": { 
      "firstName": "Test", 
      "middleName": null, 
      "surname": "User", 
      "birthDate": "1990-01-01", 
      "birthCity": "Hilversum", 
      "birthCountryCode": "NL", 
      "email": "testuser@eduMS.nl", 
      "phoneNumber": "+31612345678", 
      "company": "EduMS", 
      "department": null, 
      "address": { 
         "street": "Marathon", 
         "houseNumber": 7, 
         "houseNumberAdditive": "", 
         "postalCode": "1213PD", 
         "city": "Hilversum", 
         "countryCode": "NL" 
         } 
      }, 
   "customAttributes": { 
      "FirstChoiceStartmomentId": "{startmomentId}" 
      } 
}

Properties

Update an order

Whether the order can be updated depends on its status.

• Orders in the following statuses can be updated: PendingAccount, PendingProvider, AcceptedProvider, PendingInvoice, Invoiced, Paid, Invalid.

• Orders in the following statuses cannot be updated: PendingValidation, RejectedAccount, RejectedProvider, CancelledAccount, PendingCredited, Credited.

  ☝️When referring to the order, make sure to use the order id (guid, XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX) and not the order number (8 numbers).

Depending on the status, some properties cannot be updated. Here is an overview:

Approve an order

In the order process, accounts initially accept the order internally (e.g., managers approving student requests). Then, providers review and accept the order before it is invoiced. When an order is in the status “PendingProvider”, your action is required.

Step1. Update financial information.

First, provide EduMS with the relevant financial information used for invoicing. Do this per invoice item on the order (you can find them at the order lines). Update the following properties via the PATCH order lines endpoint:

• invoiceOnBehalfOfVatNumber

• invoiceOnBehalfOfName

  ☝️When referring to the order, make sure to use the order id (guid, XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX) and not the order number (8 numbers).

Step 2. Accept the order.

To accept the order, use the POST order status transition endpoint and send a request with the status "AcceptedByProvider". Refer to the "Example request payloads" for an example body payload.

When approving the order for the second or another start moment, you will have to update the Accepted Startmoment on the order. The following scenarios apply:

• Approving the first start moment: You do not need to do anything. EduMS will automatically update the accepted startmoment to the first startmoment saved on the order.

• Approving the second start moment: Accept the order, and use the second startmoment id on the order to update the accepted startmoment. You can do this via the PATCH order operation after accepting the order. EduMS will treat it as the first start moment and notify the student. 

• Approving another start moment: Coordinate with the student, accept the order, and use the startmoment id to update the accepted startmoment. You can do this via the PATCH order operation(same as above). EduMS will treat it as the first start moment and inform the student. 

You can also update the start moment after the initial approval (in the status "ApprovedProvider"). For a full list of properties that can be patched per status, refer to Update an order.

Updating the accepted startmoment with other values then the first or second startmoment will trigger a slow validation. This means your order will temporarily get the status “Pending Validation”. If the patched accepted start moment is one of the current start moments (first or second choice), slow validation will not be triggered.

Step 3. Next steps.

Congratulations on accepting the order! The order is now ready for invoicing in due time.

Please note the following situations:

• An account can still change the start moment of an order after it has been accepted by the provider. This will change the order status back to "PendingProvider," requiring a new approval by the provider.

• An EduMS admin can cancel the order at any point in the flow, resulting in the status "CancelledByAdmin."

• An account can still cancel the order before it is invoiced.

Reject an order

When rejecting the order, a simpler flow than for accepting the order is followed:

• Use the POST order status transition endpoint and send a request with the status "RejectedProvider". 

• Provide a cancellation reason in your request, which can be chosen from the options listed in the Enumerations across all APIs.

Refer to the "Example request payloads" for an example body payload.

Order statuses

The order status flow accommodates various scenarios. The simplified version, known as the 'happy flow,' is as follows: Post Order > Pending Validation > Pending Account > Pending Provider > Accepted by Provider > Pending Invoice > Invoiced.

Here are the possible order statuses and their descriptions.

Order status flow

Check the complete order flow (opens in new tab).