SWREG Event Notification System
The SWREG Event Notification System is tool through which vendors can subscribe to specific SWREG system events using various delivery methods and format types. Notifications can be delivered by transport methods such as email or HTTP POST to a specified URL. The system also supports multiple output formats such as plain text, XML, and JSON. Multiple delivery methods may also be configured for a single event.
The event types currently supported are listed in this document. In time, support for additional event types will be added. Please contact SWREG vendor services to suggest event types that would be helpful to you.
Setting Up a Notification
A link to configure the SWREG Event Notification System can be found under "Setup" on the main page within your SWREG account. This page allows you to configure new event types (along with the associated delivery methods and format types), as well as edit events to which you have previously subscribed.
The following fields are required for setting up a notification:
Notification: The type of event notification (i.e. the trigger that generates the notification).
Format: The format type of the notification (text, XML, and JSON).
Delivery: The delivery method of the event (email, HTTP POST). If email is selected, a field will be displayed to enter the recipient email address. If URL is a selected, a field will be display to enter the target URL.
Email or URL: Additional fields based on delivery method (per above).
Status: The status of the event (enabled or disabled).
After successfully setting up the notification (assuming the notification is enabled), you will begin receiving event notifications based on the delivery methods and format types you have configured for each event. The events are sent in near real time (meaning no more than a few minutes after the event has been completed within the SWREG system).
Security
To ensure the event notification call is coming from a trusted source, a security parameter is added to event notifications that are made by HTTP POST. This parameter is set on the vendor Configuration page in the Security Key field. The value set in the "Security Key" field will be added as a header parameter named "X-SWREG-SECURITYKEY" in the HTTP POST.
Notification Types
Completed Order
This notification is triggered when an order has been completed on the platform.
| Field Name | Description |
|---|---|
| test_order | Flag designating whether the order is a test order (Y or N) |
| shop_no | Shop ID |
| order_no | Order number |
| base_currency | Base currency of order |
| first_name | First name |
| last_name | Last name |
| company_name | Company name |
| address_1 | First address field |
| address_2 | Second address field |
| city | City |
| postal_code | Postal code |
| country | Country |
| region | Region or state |
| telephone | Telephone number |
| order_total | The total amount of the order for the shop |
| order_time | Time the order was placed |
| pay_source | Payment type |
| items | Section to display line item products purchased |
| product_code | Product code of line item |
| product_name | Product name of line item |
| product_price | Product price for line item |
| qty | Quantity of line item |
| tax | Tax charged for line item |
| affiliate | Affiliate code for line item |
| user_text | Shopper question answer for line item, if applicable |
Refund
This notification is triggered when a full refund, partial refund, tax refund, or chargeback has been issued on an order.
| Field Name | Description |
|---|---|
| test_order | Flag designating whether the order is a test order (Y or N) |
| shop_no | Shop ID |
| order_no | Order number |
| base_currency | Base currency of order |
| refund_type | Type of refund (full, partial, chargeback) |
| total_refund_amount | Total amount of refund/chargeback |
| first_name | First name |
| last_name | Last name |
| company_name | Company name |
| address_1 | First address field |
| address_2 | Second address field |
| city | City |
| postal_code | Postal code |
| country | Country |
| region | Region or state |
| telephone | Telephone number |
| order_time | Date and time order was placed |
| pay_source | Payment type |
| items | Section to display line item products refunded |
| product_code | Product code of line item |
| product_name | Product name of line item |
| refund_tax | Tax refunded for line item |
| refund_amount | Amount refunded for line item |
| affiliate | Affiliate code for line item |
Cancelled Recurring Order
This notification is triggered when a recurring order has been cancelled.
| Field Name | Description |
|---|---|
| test_order | Flag designating whether the order is a test order (Y or N) |
| shop_no | Shop ID |
| master_order_no | Master order number which is cancelled |
| manual_cancellation | Flag based on whether the shop is setup for manual recurring cancellation by the vendor (Y or N) |
| product_name | Name of the product which is cancelled |
| product_code | Product code of the product which is cancelled |
Failed Recurring Order
This notification is triggered when a recurring order has failed.
| Field Name | Description |
|---|---|
| test_order | Flag designating whether the order is a test order (Y or N) |
| shop_no | Shop ID |
| order_no | Order number |
Notification Examples
An example of the Completed Order notification in XML format:
<?xml version="1.0" encoding="UTF-8"?>
<order>
<order_no>U123456789</order_no>
<shop_no>123456</shop_no>
<test_order>N</test_order>
<order_time>2011-09-01 17:28:59</order_time>
<order_total>8.57</order_total>
<base_currency>USD</base_currency>
<pay_source>CC</pay_source>
<first_name>Randy</first_name>
<last_name>Johnson</last_name>
<address_1>123 Main Street</address_1>
<address_2></address_2>
<city>San Francisco</city>
<company_name></company_name>
<country>US</country>
<email>randyjohnson@yahoo.com</email>
<postal_code>55403</postal_code>
<region>CA</region>
<telephone>1231231234</telephone>
<items>
<qty>1</qty>
<product_code>113395-17</product_code>
<product_name>TestProduct</product_name>
<product_price>5.00</product_price>
<tax>0.39</tax>
<affiliate>affiliate_code</affiliate>
</items>
</order>
An example of the Refund notification in XML format:
<?xml version="1.0" encoding="UTF-8"?>
<order>
<order_no>U123456789</order_no>
<shop_no>123456</shop_no>
<test_order>N</test_order>
<order_time>2011-09-01 17:28:59</order_time>
<total_refund_amount>2.00</order_total>
<refund_type>partial_refund</refund_type>
<base_currency>USD</base_currency>
<pay_source>CC</pay_source>
<first_name>Randy</first_name>
<last_name>Johnson</last_name>
<address_1>123 Main Street</address_1>
<address_2></address_2>
<city>San Francisco</city>
<company_name></company_name>
<country>US</country>
<email>randyjohnson@yahoo.com</email>
<postal_code>55403</postal_code>
<region>CA</region>
<telephone>1231231234</telephone>
<items>
<product_code>113395-8</product_code>
<product_name>TestProduct</product_name>
<refund_amount>2.00</refund_amount>
<refund_tax>0.00</refund_tax>
<affiliate>affiliate_code</affiliate>
</items>
</order>
An example of the Cancelled Recurring Order notification in XML format:
<?xml version="1.0" encoding="UTF-8"?>
<order>
<order_no>U123456789</order_no>
<shop_no>123456</shop_no>
<test_order>N</test_order>
<product_name>Test Product</product_name>
<product_code>1234-1</product_code>
<manual_cancellation>N</manual_cancellation>
</order>
An example of the Failed Recurring Order notification in XML format:
<?xml version="1.0" encoding="UTF-8"?>
<order>
<order_no>U123456789</order_no>
<shop_no>123456</shop_no>
<test_order>N</test_order>
</order>