Use the Event Bus system to show alerts for when certain events occur in your DirectScale Platform. For example, an alert will send when a new enrollment occurs. There are multiple default events you can activate and custom event alerts you can create. This resource outlines the events, when they trigger, and any nuances to be considered when subscribing to them.

Sample WebHook Receiver Project

DirectScale has created a sample WebHook Receiver project available on GitHub. You can use this project to set up a service to receive events from the Bus. We've intentionally restricted the scope of this solution to basic functionality. The intent is to provide a starting point for you to use.

This sample project does not include:

Authentication for loading the swagger page
Logging
A complete API versioning strategy
Other elements typically accompanying a mature enterprise solution

✅Further Reading

View a sample WebHook Receiver on GitHub

Enabling an Event Alert

Create a custom HTTP Endpoint that can receive the alert's JSON data when it occurs. This endpoint is a URL to hit on a different server that will receive the message and then do something with it.
Log into Corporate Admin, and visit the Events page (Tools > Developer Tools > Event Subscriptions) to add endpoints to the system. This requires a certain level of access, granted by a client administrator.

📘Note

You can add specific indicator configurations for Endpoint URLs for the different Platform environments (Live or Stage), allowing you to discern between the alerts from the different environments.

Available Events

📝Parameter definitions:

OrderStatus – “Paid”, “Pending Payment”, etc.

OrderTypes – Standard=1, AutoShip=2. Learn more about Order Types.

ClientId – Your company unique identifier found in your Admin URL ({Client_ID}.directscale.com)

AssociateId vs. BackOfficeId – Learn the difference in Understanding Platform IDs

DistributorId – Refers to the Associate's numerical Associate ID (also known as the DirectScale ID).

Created Associate Event and Updated Associate Event

CreateAssociateEvent sends when you create an Associate. UpdateAssociateEvent sends when you update an Associate's account. Both of these events share the same data model.

Parameters:

AssociateId (int)
Username (string)
FirstName (string)
LastName (string)
CompanyName (string)
EmailAddress (string)
AssociateStatus (int)
AssociateType (int)
WebAliases (string[])
BackOfficeId (string)
ExternalReferenceId (string)
EventDateUtc (DateTime)

Enrollment Event

Sends any time a new customer or Associate is enrolled.

Parameters:

DistributorId (string)
DistributorType (string)
DistributorStatus (string)
DistributorCountry (string)
SponsorId (string)
EnrollmentDateUtc (DateTime)
EventDateUtc (DateTime)

Created Subscription Event and Updated Subscription Event

CreateSubscriptionEvent sends when an Associate creates a new Subscription, while UpdateSubscriptionEvent sends when a Subscription is updated. Both events share the same data model.

Parameters:

AssociateId (int)
SubscriptionId (int)
SubscriptionName (string)
IsVoid (bool)
EventDateUtc (DateTime)

Order Processed Event [Deprecated]

Currently, the OrderEvent model, used by the Order Processed Event, assigns the Order Payment’s status to the OrderStatus property. Order and payment statuses must be present in events but not at the same time. The Order Processed Event communicates incorrect data to those who subscribe to it; as a result, it will be deprecated. Use the following events instead:

Order Created Event
Order Finalized Event
Payment Created Event

Order Event

Sends when a customer or Associate creates an order, including AutoShip and incidental orders.

Parameters:

OrderId (string)
OrderDateUtc (DateTime)
DistributorId (string)
OrderType (string)
OrderTotal (double)
OrderCountry (string)
OrderCurrency (string)
OrderStatus (string)
EventDateUtc (DateTime)

Stock Level Event

Sends when an inventory item stock status changes (either in-stock to out-of-stock, or out-of-stock to in-stock).

Parameters:

ItemID (int)
WarehouseID (int)
Available (double)
Status (string)
StatusIndex (int)
EventDateUtc (DateTime)

Created Order Event

This event triggers when a customer creates a new order within the DirectScale Platform. While the order is created and the event has triggered, the order will still be pending. Additional payment and shipping processing must take place for the order to become "Finalized".

Orders created but not finalized are recorded in the ORD_Orders table but are "Void"; you can not view them within Corporate Admin.

Subscribing to this event will notify the subscriber that an order has been created but not finalized. Orders can be created through Web Office, Corporate Admin, or Public API (Create Customer Order or Import External Order).

Event Sample:

{
   "OrderNumber":1,
   "CustomerId":2,
   "OrderDateUtc":"2021-10-12T18:07:26.557768Z",
   "OrderStatus":"Pending processing",
   "OrderType":"Standard",
   "EventDateUtc":"2021-10-12T18:07:26.557768Z",
   "EventCategory":"OrderEvents",
   "EventType":"CreateOrderEvent",
}

Finalized Order Event

This event triggers when an order has completed the processing phase regardless of its source. You can view finalized orders of different order statuses in Corporate Admin.

This event can fire multiple times a given order under certain circumstances. Any time a customer attempts an order's payment, that order runs through the finalization process. A few of the scenarios where this is likely to occur include:

When an order's initial payment is pending or declined, another payment attempt must be made to pay for the order entirely.

When an order has no initial payment, and a payment attempt must be made to pay for the order entirely. This happens when "No Payment" is selected as the initial payment method within Corporate Admin.
When the Fraud Prevention module is enabled and an order's payment is "Under Review". Once a fraud decision is made, the payment will be processed to complete the order.
When the Fraud Prevention module is enabled, and an order's payment is "Declined" for fraud. If the decline is erroneous, the payment will be processed in an attempt to complete the order.

If payment was successful, and the order is paid in full, the finalization process may trigger other processes, which include:

Reserving item/inventory stock
Submitting order shipping information to configured Third-Party Logistics Providers
Recalculating the order's Associate's commissions
Subscription setup/renewal

Finalization events only happen once for Imported Orders and occur immediately after their creation event.

Event Sample:

{
   "OrderNumber":1,
   "CustomerId":2,
   "OrderDateUtc":"2021-10-12T18:07:26.497Z",
   "OrderStatus":"Paid",
   "OrderType":"Standard",
   "EventDateUtc":"2021-10-12T18:07:27.8181496Z",
   "EventCategory":"OrderEvents",
   "EventType":"FinalizeOrderEvent",
}

Updated Order Event

This event is triggered whenever you update an order’s metadata using the Edit Order page in Corporate Admin. These metadata fields include:

Commission Date
PV
QV
Bonus
Party ID
Local Invoice Number
Notes
Order Custom Fields

Thus, the Order Updated Event is not necessarily associated with status changes.

📘Note

There is currently no way to edit an order through DirectScale’s API. To learn how to edit orders, see Editing an Order.

Event Sample:

{
   "OrderNumber":1,
   "CustomerId":2,
   "OrderDateUtc":"2021-10-12T18:07:26.497Z",
   "OrderStatus":"Paid",
   "OrderType":"Standard",
   "EventDateUtc":"2021-10-12T18:11:07.3230547Z",
   "EventCategory":"OrderEvents",
   "EventType":"UpdateOrderEvent",
}

Voided Order Event

This event is triggered when an order is canceled/voided. Additional processes are triggered whenever an order cancellation occurs, such as recalculating the order’s Associate’s commissions. Order cancellation may happen through Corporate Admin or the Public API Cancel Order endpoint.

Event Sample:

{
   "VoidedDateUtc":"2021-10-12T18:17:07.8319946Z",
   "OrderNumber":1,
   "CustomerId":2,
   "OrderDateUtc":"2021-10-12T18:07:26.497Z",
   "OrderStatus":"Voided",
   "OrderType":"Standard",
   "EventDateUtc":"2021-10-12T18:17:07.8319946Z",
   "EventCategory":"OrderEvents",
   "EventType":"VoidOrderEvent",
}

Created Order Payment Event

This event triggers when an order records a new payment. Unlike new orders, which initially display as a “Pending Processing” status, new payments do not require a finalization process and can display a variety of statuses upon creation. Statuses include “Pending”, “Paid”, or “Rejected”.

A new payment creation often affects an order’s status. Order payments are created through the normal checkout process in the Web Office and Corporate Admin or the Insert Payments Public API endpoint.

Event Sample:

{
   "OrderNumber":1,
   "OrderPaymentId":1,
   "PaymentStatus":"Paid",
   "PaymentType":"Charge",
   "Amount":20.0,
   "CurrencyCode":"USD",
   "EventDateUtc":"2021-10-12T18:07:26.8794398Z",
   "EventCategory":"OrderEvents",
   "EventType":"CreateOrderPaymentEvent",
}

Refunded Order Payment Event

This event triggers when a payment is entirely (or partially) refunded. The refund process is unique because payments are never voided or removed from orders but offset by other payments creation instead.

📘Note

The order payment amount with a payment type of “Credit” is always negative.

Consider the following scenario as an example:

Order 3442 was paid for successfully by Order Payment 4172.
Order Payment 4172’s Payment Type is “Charge,” and the transaction amount was $32.00.
A refund (Order Payment 4188 and Payment Type of “Credit”) was later processed for the amount of $-18.00.
Order Payment 4172 still exists and is still marked as paid.
Order Payment 4188 has offset the total order amount by $-18.00, thereby triggering an update of Order 3442’s status to “Partial Paid”.

Payments may be refunded through Corporate Admin or the Refund Payment Public API endpoint.

Event Sample:

{
   "RefundedOrderPaymentId":1,
   "IsFullRefund":false,
   "RefundDateUtc":"2021-10-12T18:12:22.1843463Z",
   "OrderNumber":1,
   "OrderPaymentId":2,
   "PaymentStatus":"Paid",
   "PaymentType":"Credit",
   "Amount":-10.0,
   "CurrencyCode":"USD",
   "EventDateUtc":"2021-10-12T18:12:22.1843463Z",
   "EventCategory":"OrderEvents",
   "EventType":"RefundOrderPaymentEvent",
}

Submitted Order Package Event

This event triggers whenever a package is ready to be submitted to logistics providers for fulfillment. It is important to note the following:

There is no trigger event for package creation. This is by design because package creation is part of the order submission process—often created before the order is fully finalized. For this purpose, we wait until the order is finalized to send out package notifications.
This event is also triggered if a package is split. The event will not trigger for the parent package but any packages created due to the split.
This event may trigger before the package is submitted to a logistics provider. The package synchronization process occurs once every 90 minutes unless triggered manually. Because this event triggers directly after an order is finalized and runs independently of the package synchronization process, the timespan between when the event was triggered and when the package synchronization process submits the package for fulfillment may then be as long as 90 minutes.

You may submit a package during the normal order finalization process within the Web Office and Corporate Admin and the Create Customer Order Public API endpoint.

The split package process is available through the Split Package endpoint. There is currently no way to split a package via Corporate Admin.

Event Sample:

{
   "OrderNumber":2,
   "PackageId":1,
   "PackageStatus":"Submitted",
   "WarehouseId":1,
   "ShipMethodId":1,
   "TrackingNumber":null,
   "Carrier":"",
   "ShipByDateUtc":"2021-10-12T18:21:31Z",
   "ShippedDateUtc":null,
   "EventDateUtc":"2021-10-12T18:21:36.1218815Z",
   "EventCategory":"OrderEvents",
   "EventType":"SubmitOrderPackageEvent",
}

Updated Order Package Status Event

This event triggers whenever an order package updates. Typically, this occurs when an integrated logistics provider notifies DirectScale that a package’s carrier and tracking information has been updated. This event may happen multiple times for a given order package. Please note that any change in the status of an order package will also trigger this event as carrier and tracking info and shipping dates are often updated alongside the status.

Package updates are processed through any logistics providers integrated with DirectScale and through the Update Package Status and Update Package Status Batch Public API endpoints. This may also occur within Corporate Admin when an order package is manually marked “Shipped”.

⚠Important Exception

If you've enabled the Enable Legacy FTP Package Update Behavior setting, package updates submitted via FTP server will not trigger the update event.

Order Package Status Event

This event triggers whenever a package’s status updates. This often happens when a package status is changed to “Printed” or “Shipped” from an integrated logistics provider. This event may occur multiple times for a given order package as statuses often change numerous times throughout a package’s lifecycle.

Note that any change in the status of an order package will also trigger this event, as carrier and tracking info and shipping dates are often updated alongside the status.

⚠Important Exception

If you've enabled the Enable Legacy FTP Package Update Behavior setting, package updates submitted via FTP server will not trigger the update event.

Created Inventory Item Event

This event triggers whenever you create a new inventory item. Inventory items may be created through the Save Item Public API endpoint, or using the Inventory page in Corporate Admin.

Event Sample:

{
   "ItemId":4,
   "Sku":"TST_EVT",
   "TrackStock":true,
   "HasOptions":false,
   "EventDateUtc":"2021-10-12T17:58:36.204837Z",
   "EventCategory":"OrderEvents",
   "EventType":"CreateInventoryItemEvent",
}

Updated Inventory Item Event

This event triggers whenever you update an inventory item. Inventory items may be updated through the Update Item Public API endpoint, or using the Inventory page in Corporate Admin.

Event Sample:

{
   "ItemId":4,
   "Sku":"TST_EVT",
   "TrackStock":true,
   "HasOptions":true,
   "EventDateUtc":"2021-10-12T18:00:58.0119209Z",
   "EventCategory":"OrderEvents",
   "EventType":"UpdateInventoryItemEvent",
   "CustomData":{

   },
   "UnknownDataItems":{

   }
}

Deleted Inventory Item Event

This event triggers whenever you delete an inventory item. Inventory items may be deleted using the Delete Item Public API endpoint, or from the Inventory page in Corporate Admin. See Deleting an Inventory Item for more information.

⚠Important

It’s important to note that this event also triggers for item options when either the parent item is deleted, or a specific option or set of options are removed.

Event Sample:

{
   "ItemId":4,
   "Sku":"TST_EVT",
   "TrackStock":true,
   "HasOptions":true,
   "EventDateUtc":"2021-10-12T18:01:39.5127343Z",
   "EventCategory":"OrderEvents",
   "EventType":"DeleteInventoryItemEvent",
}