Administrate

Create an Order

POST /api/v2/orders

When creating an order a new opportunity is created, with a few special distinctions. A separate state is used as an initial state when orders are created through the REST API. This allows you to differentiate between leads created by your staff or via other workflows. You can define workflows for orders that include “fully automatic” processing (for example, an order is placed and immediately books the delegate onto the course and generates an invoice) or require some manual processing.

One of the common ways clients differentiate order workflows is by using Payment Types. These need to be setup within Administrate prior to placing an order call, or the order will default to no payment method.

Order Components

An Order needs to provide the following information:

  1. An Administrate contact (contact_id).

  2. Optionally, an Administrate company (company_id). If none is provided then the API user’s company will be used, or if this does not exist then the company of lowest system ID will be used.

  3. Events (event_id), their price (price) and optionally a delegate contact_id.

  4. Optionally, Stock/Items associated with the event and delegate (in ‘children’).

    If the item contains event_id you may also optionally add students by their contact_id.

  5. Payment Details containing:
    1. Total paid (amount)
    2. Payment type (type), which is defined within the Administrate
    3. Currency (using an ISO currency code)
    4. Transaction code (provided by your payment processor)
  6. An optional external_id to synchronise orders with an external system if desired.

  7. Optional region_id to set the region for an order if desired.

  8. Optional currency_id to set the currency for an order if desired.

  9. Optional source_type_id to set the source type for an order if desired.

Note: Creating orders without any items is considered valid as some workflows could require this. Also, you can add items which don’t exist to orders, but they will be silently discarded.

Note: If you specify the payment details with the correct setup on the core app you can create a registration and invoice for the event. The api call is not preventing overbooking on the event. To check if you are not going to overbook the event please use the get private/public events endpoint.

Using Curl

curl -k -u (user):(password) https://YOUR-SUBDOMAIN/api/v2/orders \
    -H 'Content-type: application/json' \
    -d '{
        "contact_id": 47403,
        "company_id": 1,
        "region_id" : "UK",
        "currency_id" : "EUR",
        "source_type_id" : 5,
        "items": [
            {"event_id": 216, "price": 123.00},
            {"event_id": 225, "price": 234.00, "contact_id": 47838},
            {"event_id": 225, "price": 234.00, "contact_id": 47838, "students" : [
                {"contact_id": 112}
            ]},
            {"event_id": 225, "price": 234.00, "contact_id": 47838, "quantity": 2, students" : [
                {"contact_id": 112},{"contact_id": 114}
            ]},
            {"event_id": 287, "price": 123.00, "children": [
                {"item_id": 123, "price": 345.0}
            ]},
            {"event_id": 301, "price": 234.00, "contact_id": 47839, "children": [
                {"item_id": 123, "price": 456.0},
                {"item_id": 124, "price": 567.0}
            ]}
        ],
        "payment": {"amount": 1.23,
            "type": "Card",
            "currency": "GBP",
            "transaction_code": "abc123"
        },
        "external_id": "qwerty12345"
    }'

Example Response

{
    "msg": "order created",
    "order_id": 50
}