Home > Services > Set-up Instructions > Recurring Transactions

Services

Set-up Instructions : Recurring Order Interface

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 only apply to credit card orders only.

Recurring Options

  • 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".
  •  
  • Recurrence Setup
  •  
  • The most common 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 Setup" link
    • Click the "Add" button on the right
    • 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 1 week and 24 hours before the recurrence so the customer can opt-out if desired.
    • Select the "Billing Repitition"
    • Next add products to the profile by selecting the "Add" button on the right 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. An example if I want my setup product of $250.00 to recur everytime 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 $.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 setup an order to recur after the order is placed. To do this, go to "Recurrence Setup" and then input the order number into the "Manual Order Setup". Then you will set the same specifications for that specific order.
  •  
  • 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.

Enabling or Disabling a Master Order through an API

The API provides a way for you to disable or enable a recurring master 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 "Automated Calls" 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.
    • The only attribute changeable through the API is the enable or disable status
    • 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.
  •  
  • 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 LWP::UserAgent docs).
  •  
  • #!/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.