Recurring Transactions

SWREG offers to ability to completely automate weekly, monthly, quarterly, semi-annually, or annual recurring/subscription orders. The recurring order functionality offers the ability to have multiple products in the same order with different recurring timeframes. Subscriptions apply to credit card orders only.

Reports

Reports can be processed within the main reporting area of your store. To limit the reports to only master or child orders you will select those options under "Order Type".

Setup

The most common setup method is a recurring profile. To setup up a profile you first need to create the product that will recur under the "Create/Edit Products" area. Next, from the main menu, follow these steps:

• Click the "Recurrence Profiles" link
• Click the "Add" button
• Enter your "Profile Name" which is for your reference only
• Select the "Frequency" or how often you want the order to recur
• Select the "Day of the Month", recommended is the default "Automatic" so the order recurs on the same date as the original order. You can also select "Automatic" and then adjust the day of the month by + or - a number of days, i.e. my initial order was placed on the 3rd, now monthly it will recur on the 4th of the month.
• Select Yes or No for "Pre-bill Notifications", best practice is Yes. We will send an email one week and 24 hours before the recurrence so the customer can opt-out if desired.
• Select the "Billing Repetition"
• Save your Recurrence Profile
• Next, add products to the profile by selecting the "Add" button which will initiate a modal window where you can select the product you want. Any products already assigned to a profile will show, but cannot be selected for this profile. Click "Save" in the modal once the products are selected.
• Optionally you can select a "Price Variance" for those product(s) that can be a positive or negative amount. For example, if I want my setup product of $250.00 to recur every time for $50 after that initial purchase, I would enter -200.00 into the price variance.
• Click "Save" for this new profile, and it is now active.

The recurring functionality has the ability to a "trial" period where we will check the credit card and won't bill them until the certain timeframe has passed. To set this up, a product for $0 needs to be created and assigned to the recurring profile with all the recurrence rules. A price variance will need to be on the profile for the amount to be billed after the initial profile frequency has passed. When that product is ordered we will check the card with a $0.01 authorization, and if successful, will process the order. SWREG will then charge the customer the variance amount on the first recurrence and going forward.

To note: The system will only process a product for $0 if it is a recurring product that has a profile assigned to it.

There is also the option to set up an order to recur after the order is placed. To do this, go to "Recurrence Profiles" and then input the order number into the "Manual Order Setup". Then, you will set the same specifications for that specific order.

Finally, there is the ability to pay any affiliates for recurring or subscription orders. To select this option, login to the SWREG control panel and select "Configuration." In the "Setting" area, "Affiliate Tracking," make your selection accordingly.

Actions

To Stop a Master Order:

• Click "Show Orders"
• Go to "Quick Actions" and enter order number in the "Bulk Master Order Stop"
• Click "Go" and then the order will be disabled.
• You can also stop multiple orders by inputting a list with each master order number on a new line

To Retry a Failed Child Order:

• Click "Show Orders"
• Go to "Quick Actions" and enter order number in the "Bulk Child Order Retry"
• Click "Go" and then we will attempt to reprocess the order.
• You can also retry multiple child orders by inputting a list with each order number on a new line

To See Details on an Enabled Master Order:

• Click "Show Orders"
• Go to "Quick Actions" and enter order number in the "Go to Order No"
• The order details will show that master orders status of Enabled or Disabled
• Click on the Enabled or Disabled link
• The page shows the specific settings for that master order
• If the master order is Disabled, you can Enable it here

You can also see on the order details all child orders associated with that master order and their status.

Altering a Recurring Order through our API

API Usage

The API provides a way for you to alter some characteristics of a recurring order. You can integrate the API within your systems or customized deliverables to your customer. To use this API you will need to be able to POST data to a URL and parse the results. It is recommended that you use standard toolsets available for your platform or application to ensure all data is encoded and decoded in a standard and compliant manner. The API is designed to conform to RESTful design principles.

General integration details

• The service's base URL is: https://www.swreg.org/app/resource/recurringorder/%ORDER_NO%. You will need to replace "%ORDER_NO%" with the order number you are wanting to modify.
• The service must be accessed over SSL. Non-SSL requests will be denied.
• Your REST client will need to authenticate using HTTP Basic Authentication. The system will use your shop ID as the username and the "API password" as configured in the "Author and Payment Details > Passwords" section of the vendor admin area as the password.
• The order number you pass in the URL can optionally include the currency prefix (i.e. "U", "G" or "E") but it is not required.
• You must POST to this URL. No other HTTP verbs (i.e. HEAD, GET, PUT, DELETE) are supported at this time.
• In typical REST fashion, HTTP status codes are used to indicate success or failure. In general, status codes less than 400 indicate success while status codes 400 and above indicate failures. Additional details related to the failure are typically included in the body of the response for debugging purposes.
• Data for this call may be posted in simple URL-encoded format or other standard data formats including JSON or YAML. XML is not currently supported.

Enable/Disable a Master Order

This method provides a way for you to disable or enable a recurring master order, as long as you have the order number. An example is listed below, under "Integration Examples".

To disable an order, send a POST request to the URL listed above, with the value disabled=1.

To enable an order, send a POST request to the URL listed above, with the value disabled=0.

Change the next billing date of an order

This method provides a way for you to change the next billing date of a recurring order, as long as you have the order number. The order must already be in a processed state for the date to be changed.

To use, send a POST request to the URL listed above, with the value newdate=YYYY-MM-DD. Replace YYYY-MM-DD with the desired date. For example, to set the date to June 1, 2020, send newdate=2020-06-01.

Retry a failed order

This method provides a way for you to retry a failed recurring order. If an order resulted in a declined or rejected card, you are able to attempt an additional transaction against that child order. Note that this functionality will not allow you to retry an order for reasons other than a processing failure.

To use, send a POST request to the URL listed above, with /retry appended to the end, replacing %ORDER_NO% with the master order number. Child order numbers will not be accepted. A proper retry URL will look like this, before replacing with a proper order number:

https://www.swreg.org/app/resource/recurringorder/%ORDER_NO%/retry

Integration Examples:

cURL

This is the most portable method as it can be used with any programming language that can execute an external program and use the input. It does force you to manually do some parts of the process however so it should be considered secondary to any native library that allows you to execute HTTP POSTs.

% curl -i --user %SHOP_ID%:%PASSWORD% --data disabled=0 \
     https://www.swreg.org/app/resource/recurringorder/%ORDER_NO%

This outputs a response that should look something like this:

HTTP/1.1 200 OK
Date: Wed, 17 Jun 2009 13:51:52 GMT
Server: Apache/2.2.14 (Unix) mod_fastcgi/2.4.6
Vary: Content-Type,Authorization
Content-Length: 32
X-Catalyst: 5.800007
Connection: close
Content-Type: application/x-www-form-urlencoded

message=no+updates+made+to+order

You will need to parse and evaluate the output (most importantly the status code from the first line and any messages in the body).

Perl

This provides a richer interface (response parsing, etc) but does require knowledge of Perl programming (see the LWP::UserAgent documentation).

#!/usr/bin/perl

use strict;
use warnings;

use LWP::UserAgent;

my $ua = LWP::UserAgent->new();
$ua->credentials('www.swreg.org:443','vendor-api','12345','secret');
my $response = $ua->post(
    'https://www.swreg.org/app/resource/recurringorder/%ORDER_NO%',
    {disabled => 1}
);
if ($response->is_success) {
    # handle success here
    print $response->content;
} else {
    # handle errors here...
    print $response->as_string;
}

Other Languages

Any modern programming language should provide a native HTTP toolset that should allow you to do similar things to the above.

Email Notifications to Vendors

Every morning we will send out batch emails with any orders that failed during the attempt to complete. The email will contain the order number, reason for failure, and the master order number for each child order.