Order management

Order is the main object used in a load delivery flow. The regular flow starts with order creation. When an order is ready to dispatch, you send a load offer to Carrier TMS (CTMS). A carrier who receives the load offer accepts it and then picks up and delivers the load to its destination. All order status changes by carrier are automatically synchronized with the corresponding order in STMS.

The flow described above is a regular flow. However, sometimes you may want to update the order status manually before the carrier. For example, you may know that the order has already been picked up or delivered, but the driver hasn’t updated the order status yet. In such cases, you can change the order status manually. Later the carrier can update the order status, and the flow will continue as usual. This flow is called semi-manual flow.

Finally, there is a third type of flow called fully manual flow. In fully manual flow, you don’t send a load offer to Carrier TMS. Instead, you assign the order directly to a carrier and change the order status all by yourself. You can even create a new carrier profile inside STMS and assign orders to it. If the carrier exists in Carrier TMS, the order still won’t be synchronized. The fully manual flow’s purpose is to store historical orders created outside of STMS or orders delivered by carriers who don’t use Carrier TMS. Normally you don’t want to use the fully manual.

Table of Contents

Creating an order

You can create order using the following endpoint

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107

curl -X POST 'https://api.shipper.superdispatch.com/v1/public/orders' \
-h 'Authorization: Bearer <access_token>' \
-h 'Content-Type: application/json;charset=UTF-8' \
-d '{
    "number": "TST1267",
    "transport_type": "OPEN",
    "inspection_type": "standard",
    "instructions": "Testing instructions for ABC",
    "loadboard_instructions": "Testing Loadboard instructions",
    "price": 200,
    "dispatcher_name": "Vin Diesel",
    "sales_representative": "Wilson Horn",
    "broker_fee": 50,
    "purchase_order_number": "PO-TST1267",
    "payment": {
        "terms": "other"
    },
    "customer_payment": {
        "cod_cop_amount": 0,
        "tariff": 250,
        "deposit": 100,
        "terms": "cash_on_pickup",
        "received_date": "2021-03-01T09:00:00.000-0600",
        "reference_number": "123"
    },
    "customer": {
        "address": "14757 Sherman Way",
        "name": "ABC",
        "notes": null,
        "state": "CA",
        "zip": "91405",
        "city": "Van Nuys",
        "business_type": "BUSINESS",
        "email": "[email protected]",
        "phone": null,
        "counterparty_guid": "7a71584f-9087-4e91-a9c5-202a537e27f6",
        "save_as_new": false,
        "contact_title": null,
        "contact_email": "[email protected]",
        "contact_name": "Ross Bradley Quinn",
        "contact_phone": "+1234567890",
        "contact_mobile_phone": null
    },
    "pickup": {
        "date_type": "estimated",
        "counterparty_guid": "3a7772a7-c3d3-4222-9741-1d969e706bd4",
        "notes": null,
        "first_available_pickup_date": "2021-03-01T09:00:00.000-0600",
        "scheduled_at_by_customer": "2021-03-01T09:00:00.000-0600",
        "scheduled_ends_at_by_customer": "2021-03-02T18:00:00.000-0600",
        "scheduled_at": "2021-03-01T09:00:00.000-0600",
        "scheduled_ends_at": "2021-03-02T18:00:00.000-0600",
        "counterparty_guid": "5b5cf726-ded4-4f3d-8aa8-91b54b5bf61a",
        "venue": {
            "address": "3501 Lancaster Hutchins Rd",
            "name": "AD Dallas",
            "notes": null,
            "state": "TX",
            "zip": "75141",
            "city": "Hutchins",
            "business_type": "AUCTION",
            "contact_title": "Manager",
            "contact_email": null,
            "contact_name": "John Marston",
            "contact_phone": "+1234567890",
            "contact_mobile_phone": null
        }
    },
    "delivery": {
        "date_type": "estimated",
        "counterparty_guid": "ee058e99-4c0e-4527-9943-7af1ce2605b1",
        "notes": null,
        "scheduled_at_by_customer": "2021-03-05T09:00:00.000-0600",
        "scheduled_ends_at_by_customer": "2021-03-05T18:00:00.000-0600",
        "scheduled_at": "2021-03-05T09:00:00.000-0600",
        "scheduled_ends_at": "2021-03-05T18:00:00.000-0600",
        "counterparty_guid": "bad0a6c5-3b93-40ef-9672-4e8cba3964d6",
        "venue": {
            "address": "2108 Ferguson Ln",
            "name": "AD Austin",
            "notes": null,
            "state": "TX",
            "zip": "78754",
            "city": "Austin",
            "business_type": "AUCTION",
            "contact_title": "Gate Manager",
            "contact_email": null,
            "contact_name": "Arthur Morgan",
            "contact_phone": "+1234567890",
            "contact_mobile_phone": null
        }
    },
    "vehicles": [
        {
            "vin": "JT3GM84R4Y0061930",
            "curb_weight": 3440,
            "curb_weight_unit": "lbs",
            "make": "Toyota",
            "model": "4Runner",
            "color": null,
            "type": "suv",
            "year": 2000,
            "price": 200,
            "tariff": 250
        }
    ]
}'

To create an order only number field is required. However there are other required fields that will be needed for posting the order to Super Loadboard. Detailed description of order fields can be found in API reference for the endpoint.

Customer contact

The customer field stores the contact information of the load’s owner. If you want to link this customer contact with the customer profile in STMS, you can specify the customer’s GUID in counterparty_guid field. This allows uniquely identify the customer. If the customer has access to the customer portal, she can monitor the load’s status directly in the system. If you specified customer GUID in counterparty_guid and omitted all other information, all contact information will be automatically filled by the system. If the customer doesn’t exist in the system and you want to save its profile to use it in other loads, you can set save_as_new to true.

Pickup and delivery

Pickup and delivery fields contain information about the origin and destination of the load. The pickup scheduled date should be earlier than the delivery scheduled date. If you use the estimated date type, you can also specify pickup and delivery end dates. These date ranges are used in Super Loadboard for load requests. If the preferred carrier picks a date outside of these ranges, he can’t instantly book a load and only request it. Refer to Super Loadboard documentation for further information about load requests.

As with customer contact information, you set counterparty_guid for both pickup and delivery. However, besides the customer profile, you can also use a terminal GUID for pickup and delivery. If you specified counterparty_guid and omitted all other information, then all contact information will be automatically filled by the system. If the terminal doesn’t exist in the system and you want to save it to use it in other loads, you can set save_as_new to true.

Vehicles

Order’s vehicles are specified as an array. Make and model fields are required. However, it’s possible to automatically decode vehicle fields from VIN. If VIN is set while year, make, and model fields are left empty, the system automatically decodes and fills empty fields. For example, if VIN is 1FTFW1ET8CKD25036 then vehicle will be saved with the following field values:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "vin": "1FTFW1ET8CKD25036",
  "curb_weight": null,
  "curb_weight_unit": null,
  "make": "Ford",
  "model": "F-150",
  "color": null,
  "type": "pickup_4_doors",
  "year": 2014
}

Notice that not all fields were filled since the VIN decoder may not have full information about the vehicle.

Updating an order

There are two main endpoints to update existing orders: full and partial update. The full order update endpoint expects the whole order body as a payload. Each changed field should contain a new value while the rest should remain as is. For the partial order update endpoint you can pass only changed fields.

Full order update

You can update order using the following endpoint:

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

curl -X PUT 'https://api.shipper.superdispatch.com/v1/public/orders/<guid>' \
-h 'Authorization: Bearer <access_token>' \
-h 'Content-Type: application/json;charset=UTF-8' \
-d '{
    "number": "TST1267",
    "transport_type": "OPEN",
    "inspection_type": "standard",
    "instructions": "Testing instructions for ABC",
    "loadboard_instructions": "Testing Loadboard instructions",
    "price": 400,
    "dispatcher_name": "Vin Diesel",
    "sales_representative": "Wilson Horn",
    "broker_fee": 50,
    "purchase_order_number": "PO-TST1267",
    "payment": {
        "terms": "other"
    },
    "customer_payment": {
        "cod_cop_amount": 0,
        "tariff": 500,
        "deposit": 100,
        "terms": "cash_on_pickup",
        "received_date": "2021-03-01T09:00:00.000-0600",
        "reference_number": "123"
    },
    "customer": {
        "address": "14757 Sherman Way",
        "name": "ABC",
        "notes": null,
        "state": "CA",
        "zip": "91405",
        "city": "Van Nuys",
        "business_type": "BUSINESS",
        "email": "[email protected]",
        "phone": null,
        "counterparty_guid": "7a71584f-9087-4e91-a9c5-202a537e27f6",
        "save_as_new": false,
        "contact_title": null,
        "contact_email": "[email protected]",
        "contact_name": "Ross Bradley Quinn",
        "contact_phone": "+1234567890",
        "contact_mobile_phone": null
    },
    "pickup": {
        "date_type": "estimated",
        "counterparty_guid": "3a7772a7-c3d3-4222-9741-1d969e706bd4",
        "notes": null,
        "first_available_pickup_date": "2021-03-01T09:00:00.000-0600",
        "scheduled_at_by_customer": "2021-03-01T09:00:00.000-0600",
        "scheduled_ends_at_by_customer": "2021-03-02T18:00:00.000-0600",
        "scheduled_at": "2021-03-01T09:00:00.000-0600",
        "scheduled_ends_at": "2021-03-02T18:00:00.000-0600",
        "counterparty_guid": "5b5cf726-ded4-4f3d-8aa8-91b54b5bf61a",
        "venue": {
            "address": "3501 Lancaster Hutchins Rd",
            "name": "AD Dallas",
            "notes": null,
            "state": "TX",
            "zip": "75141",
            "city": "Hutchins",
            "business_type": "AUCTION",
            "contact_title": "Manager",
            "contact_email": null,
            "contact_name": "John Marston",
            "contact_phone": "+1234567890",
            "contact_mobile_phone": null
        }
    },
    "delivery": {
        "date_type": "estimated",
        "counterparty_guid": "ee058e99-4c0e-4527-9943-7af1ce2605b1",
        "notes": null,
        "scheduled_at_by_customer": "2021-03-05T09:00:00.000-0600",
        "scheduled_ends_at_by_customer": "2021-03-05T18:00:00.000-0600",
        "scheduled_at": "2021-03-05T09:00:00.000-0600",
        "scheduled_ends_at": "2021-03-05T18:00:00.000-0600",
        "counterparty_guid": "bad0a6c5-3b93-40ef-9672-4e8cba3964d6",
        "venue": {
            "address": "2108 Ferguson Ln",
            "name": "AD Austin",
            "notes": null,
            "state": "TX",
            "zip": "78754",
            "city": "Austin",
            "business_type": "AUCTION",
            "contact_title": "Gate Manager",
            "contact_email": null,
            "contact_name": "Arthur Morgan",
            "contact_phone": "+1234567890",
            "contact_mobile_phone": null
        }
    },
    "vehicles": [
        {
            "guid": "86251882-1cb1-4198-a272-4aae36228c97",
            "vin": "JT3GM84R4Y0061930",
            "curb_weight": 3440,
            "curb_weight_unit": "lbs",
            "make": "Toyota",
            "model": "4Runner",
            "color": null,
            "type": "suv",
            "year": 2000,
            "price": 200,
            "tariff": 250
        },
        {
            "vin": "WAULC68EX5A103903",
            "curb_weight": 3406,
            "curb_weight_unit": "lbs",
            "make": "Audi",
            "model": "A4",
            "color": null,
            "type": "sedan",
            "year": 2005,
            "price": 200,
            "tariff": 250
        }
    ]
}'

Order fields are described in API reference for the endpoint.

Partial order update

For the full order update endpoint, you have to send the whole order body as a payload even if you need to modify a single field. Unlike the full update endpoint, the partial update allows updating orders with the partial payload. The partial update is implemented according to the JSON Merge Patch standard proposed in RFC 7396.

To perform the partial update, you should send a payload with a set of fields that needs to be updated as an HTTP PATCH request. The content type of the request should be application/merge-patch+json. Field values that are included in the payload replace old values. Fields that aren’t included in the payload remain untouched.

Notice that according to the standard, it is not possible to patch part of an array. For example, if you send a nested vehicles array field in a payload, the order’s vehicle list will be completely overwritten by the content of this array.

You can partially update the order using the following endpoint:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

curl -X PATCH 'https://api.shipper.superdispatch.com/v1/public/orders/<guid>' \
-h 'Authorization: Bearer <access_token>' \
-h 'Content-Type: application/merge-patch+json;charset=UTF-8' \
-d '{
        "price": 400,
        "customer_payment": {
            "tariff": 500
        },
        "vehicles": [
            {
                "guid": "86251882-1cb1-4198-a272-4aae36228c97",
                "vin": "JT3GM84R4Y0061930",
                "curb_weight": 3440,
                "curb_weight_unit": "lbs",
                "make": "Toyota",
                "model": "4Runner",
                "color": null,
                "type": "suv",
                "year": 2000,
                "price": 200,
                "tariff": 250
            },
            {
                "vin": "WAULC68EX5A103903",
                "curb_weight": 3406,
                "curb_weight_unit": "lbs",
                "make": "Audi",
                "model": "A4",
                "color": null,
                "type": "sedan",
                "year": 2005,
                "price": 200,
                "tariff": 250
            }
        ]
    }'

Order fields are described in API reference for the endpoint.

Updating vehicles

Since order vehicles are included as an array, you can delete or update existing vehicles as well as add new ones while updating the order. Existing vehicles are distinguished from new vehicles by including vehicle GUID. In the above example, there are two vehicles in the vehicles array field. The first vehicle has GUID, while the second doesn’t have it. Therefore the first vehicle will be updated while the second one added as a new one. If you omit vehicles from the payload, the missing ones will be removed from the order.

Sending a load offer

To dispatch a load, you should send a load offer to a carrier in Carrier TMS. You can send a load offer either to an existing (registered) or not yet registered carrier. In the former case, the carrier is identified by GUID; in the latter case, by USDOT number.

Sending a load offer to an existing carrier

You can send offer to an existing carrier using the following endpoint:

1
2
3
4
5
6

curl -X POST 'https://api.shipper.superdispatch.com/v1/public/orders/<guid>/offers' \
-h 'Authorization: Bearer <access_token>' \
-h 'Content-Type: application/json;charset=UTF-8' \
-d '{
    "carrier_guid": "512cb41f-45f3-4996-83a5-83687bf0cc0b"
}'

The carrier_guid should contain the existing carrier GUID. This call generates a dispatch sheet, attaches it to the order, and changes the order status to pending. The carrier will get email and SMS notifications. Once the carrier accepts the offer, the order status will be changed to accepted.

The load offer details become available in the order’s active_offer field. The load offer details can also be fetched using the following endpoint

1
2
3

curl -X GET 'https://api.shipper.superdispatch.com/v1/public/orders/<guid>/offers/active' \
-h 'Authorization: Bearer <access_token>' \
-h 'Content-Type: application/json;charset=UTF-8'

Sending a load offer to a not registered carrier

You can send a load offer to a not registered carrier using the following endpoint:

1
2
3
4
5
6
7
8

curl -X POST 'https://api.shipper.superdispatch.com/v1/public/orders/<guid>/offers' \
-h 'Authorization: Bearer <access_token>' \
-h 'Content-Type: application/json;charset=UTF-8' \
-d '{
    "carrier_usdot": 12345,
    "carrier_email": "[email protected]",
    "carrier_phone": "+18123456789"
}'

Since this carrier isn’t registered in CTMS, the payload includes carrier_email and carrier_phone. If you don’t specify either of these fields, they will be fetched from FMCSA database. Notice, however, that FMCSA may not contain this information, or it may be outdated.

This call generates a dispatch sheet, attaches it to the order, and changes the order status to pending. The carrier will get email and SMS notifications. Once the carrier accepts the offer the order status will be changed to accepted and the carrier will be automatically registered in CTMS. In the future, you can send load offers to this carrier using GUID.

Cancel a load offer

Sometimes after sending a load offer, you may want to change order information or send a load offer to another carrier. Although the dispatch sheet is regenerated after each order update and reflects these changes in the revision section, some brokers still prefer to cancel and resend a new offer with a new dispatch sheet. In these cases, it’s possible to cancel a load offer that was sent to a carrier. After canceling an offer, you send another offer later.

You can cancel a load offer using the following endpoint:

1
2
3

curl -X PUT 'https://api.shipper.superdispatch.com/v1/public/orders/<guid>/cancel' \
-h 'Authorization: Bearer <access_token>' \
-h 'Content-Type: application/json;charset=UTF-8'

This call sets the order status to canceled and the active_offer field to null.

Fetching all offers

It’s possible to fetch the list of all offers which were sent for particular order. An order may have only one active offer but many canceled or declined offers. You can get the list of all load offers using the following endpoint:

1
2
3

curl -X GET 'https://api.shipper.superdispatch.com/v1/public/orders/<guid>/offers' \
-h 'Authorization: Bearer <access_token>' \
-h 'Content-Type: application/json;charset=UTF-8'

The response structure is described in the API reference.

Manual order status change

After receiving and accepting a load offer, a carrier is responsible for updating the order status. Usually, the driver updates order status using the mobile app. Sometimes carrier dispatchers also update the load status using the carrier dashboard. However, as described in the introductory section above, sometimes you may want to update the order status manually before the carrier. For example, you may know that the order has already been picked up or delivered, but the driver hasn’t updated the order status yet. In such cases, you can change the order status manually.

Manually mark as accepted

You can mark a pending load offer as accepted using the following endpoint:

1
2
3

curl -X PUT 'https://api.shipper.superdispatch.com/v1/public/orders/<guid>/mark_as_accepted' \
-h 'Authorization: Bearer <access_token>' \
-h 'Content-Type: application/json;charset=UTF-8'

This call changes the order status to accepted and sets is_status_changed_manually field to true.

Manually mark as picked up

You can mark an accepted load offer as picked up using the following endpoint:

1
2
3
4
5
6

curl -X PUT 'https://api.shipper.superdispatch.com/v1/public/orders/<guid>/mark_as_picked_up' \
-h 'Authorization: Bearer <access_token>' \
-h 'Content-Type: application/json;charset=UTF-8' \
-d '{
    "adjusted_date": "2019-11-19T10:33:29.112+0000"
}'

This call changes the order status to picked_up and sets is_status_changed_manually field to true.

Manually mark as delivered

You can mark a picked up load offer as delivered using the following endpoint:

1
2
3
4
5
6

curl -X PUT 'https://api.shipper.superdispatch.com/v1/public/orders/<guid>/mark_as_delivered' \
-h 'Authorization: Bearer <access_token>' \
-h 'Content-Type: application/json;charset=UTF-8' \
-d '{
    "adjusted_date": "2019-11-19T10:33:29.112+0000"
}'

This call changes the order status to delivered and sets is_status_changed_manually field to true.

Manually mark as invoiced by carrier

You can mark a delivered load offer as invoiced by carrier using the following endpoint:

1
2
3
4
5
6

curl -X PUT 'https://api.shipper.superdispatch.com/v1/public/orders/<guid>/mark_as_carrier_invoiced' \
-h 'Authorization: Bearer <access_token>' \
-h 'Content-Type: application/json;charset=UTF-8' \
-d '{
    "adjusted_invoice_date": "2019-11-19T10:33:29.112+0000"
}'

This call changes the order status to invoiced.

Rollback manually changed status

It’s possible to rollback manually changed status to the status which was set by the carrier. For example, if the carrier accepted the order and you changed its status to delivered, then when you rollback the order status, it becomes accepted again. However, if the carrier marked the order as picked up after you manually changed the order status, rolling back would return the order to pick up status.

If the order was in pending status (i.e., the load offer wasn’t accepted by the carrier), the rollback endpoint wouldn’t return the order status back to pending. Instead, it would return it to accepted status.

You can rollback manually changed status using the following endpoint:

1
2
3

curl -X PUT 'https://api.shipper.superdispatch.com/v1/public/orders/<guid>/rollback_manual_status_change' \
-h 'Authorization: Bearer <access_token>' \
-h 'Content-Type: application/json;charset=UTF-8' \

Canceling an order

Besides canceling a load offer, it’s also possible to cancel the order itself. The difference between canceling the offer and order is that in the former case, the order returns to the list of new orders, while in the latter case, the order is moved to a separate list in UI and won’t mix with the other orders. For example, the order can be canceled because the customer no longer wants to ship a load. You still can send a load offer for canceled offer.

You can cancel an order using the following endpoint:

1
2
3

curl -X POST 'https://api.shipper.superdispatch.com/v1/public/orders/<guid>/cancel' \
-h 'Authorization: Bearer <access_token>' \
-h 'Content-Type: application/json;charset=UTF-8'

This call changes the order status to order_canceled.

Archiving an order

After delivering a load, you may no longer want to see it in your order list but retain historical data. To acheive this it’s possible to archive orders. Archived orders moved to a separate list in UI. You can unarchive the archived order if you want to.

You can archive an order using the following endpoint:

1
2
3

curl -X PUT 'https://api.shipper.superdispatch.com/v1/public/orders/<guid>/archive' \
-h 'Authorization: Bearer <access_token>' \
-h 'Content-Type: application/json;charset=UTF-8'

This call changes the order is_archived field to true.