Subscription API

Overview

The subscription service makes it possible for consumers to place subscription-type orders, of a recurring nature, for products and services available from the retailer. Through the subscription service APIs, subscription order functionality can be invoked from a webstore or from Customer Care.

A subscription order is a set of one or more items that have a repeatable schedule managed through an account that includes shipping, billing, and payment information. In order to implement subscription ordering, a system must be able to regenerate orders automatically, on a periodic basis, and process the recurring payments as well. Subscriptions orders are limited to credit card tenders.

The functions available through the subscription service are listed in the Subscription URI table below.

Subscription URI Summary

Subscription URIs use the service identifier subscription.

Operation	Action	URI Template	URI Example	Transaction Type	Unique RequestID Needed for Duplicate Detection?	Non-URI Request Payload	Response
Search	POST	/vM.m/stores/storeID/customers/customerID/subscriptions/search/subscriptionID	/v1.0/stores/ABCD/customers/C12345/subscriptions/search/0002500001234567_s1	Get all subscriptions that match the search criteria.	No	XML	200 + XML response
Update	POST	/vM.m/stores/STOREID/customers/customerID/subscriptions/update/subscriptionID	/v1.0/stores/ABCD/customers/C1234/subscriptions/update/0002500001234567_s1	Update subscriptions that match the update criteria.	No	XML	200 + XML response
Cancel	POST	/vM.m/stores/STOREID/customers/customerID/subscriptions/cancel/subscriptionID	/v1.0/stores/ABCD/customers/C1234/subscriptions/cancel/0002500001234567_s1	Cancel all subscriptions that match the cancel criteria.	No	XML	200 + XML response

Schemas

Subscription Order Identifiers

When a subscription is created, the client sends an order with a web order ID. This original order ID serves as a base number for all subsequent subscription order IDs, with suffixes added to distinguish each subscription order.

The formula for generating subscription order IDs imposes the following limitations:

The original web order ID must be 16 characters or less.
Each web order can contain no more than 9 subscriptions.
Each subscription is limited to 9999 generated orders.

Subscription order IDs are constructed according to the following pattern:

<base_order_id>_s<subscription count number (1 digit)>_<order interval number (4 digits)>

For example, if a subscription is creates in web order 0002500007330504:

0002500007330504_s1 is the first order for the subscription
0002500007330504_s1_2 is the second order for the subscription
0002500007330504_s1_10 is the tenth order for the subscription.

Create a Subscription Order

A subscription order is created through the Order Create API, using the Subscriptions element to define subscription details. For a request XML sample, see the Subscription Order example on the Order API page.

Search Subscription

For subscription search, the customer ID and subscription ID are included in the URI string.

Search Subscription Request

<?xml version="1.0" encoding="UTF-8"?>
<SearchSubscriptionRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0" sessionId="session123"/>

Search Subscription Response

<?xml version="1.0" encoding="UTF-8"?>
<SearchSubscriptionResponse xmlns="http://schema.gspt.net/Order/1.0" 
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <SourceId type="CHANNEL">TMSUS</SourceId>
    <CreateTimestamp>2014-07-25T18:54:42.120</CreateTimestamp>
    <CustomerId>Customer123</CustomerId>
    <Subscriptions>
        <Subscription id="123">
            <Interval type="MONTHLY">3</Interval>
            <ShippingAddressId>1234</ShippingAddressId>
        </Subscription>
    </Subscriptions>
</SearchSubscriptionResponse>

Update Subscription

For Update Suscription, the customer ID and subscription ID are included in the URI string. The following subscription values can be updated through the subscription service:

Recurring subscription interval
Shipping address information, including name, email address, and phone number

Note that changing shipping address for a subscription order will cause recalculation of taxes, duties, and shipping. Webstores can choose to prohibit changing address for subscription orders to avoid the potential of incurring higher costs for taxes, duties, or shipping.

Payment details for subscription orders can be updated through the payment service.

Update Subscription Request

<?xml version="1.0" encoding="UTF-8"?>
<UpdateSubscriptionRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
                           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                           sessionId="session123">
    <CreateTimestamp>2014-07-25T18:54:42.120</CreateTimestamp>
    <!--<RecurringSubscriptionInterval type="MONTHLY">3</RecurringSubscriptionInterval>-->
    <ShippingAddress>
        <ShippingAddressId>ShippingAddressId</ShippingAddressId>
        <PhysicalAddress>
            <Line1>line1</Line1>
            <City>City</City>
            <MainDivision>division</MainDivision>
            <CountryCode>PA</CountryCode>
            <PostalCode>12345</PostalCode>
        </PhysicalAddress>
        <FirstName>service</FirstName>
        <MiddleName>order</MiddleName>
        <LastName>subscription</LastName>
        <EmailAddress>emailaddress@email.com</EmailAddress>
        <PhoneNumber>123456789</PhoneNumber>
    </ShippingAddress>
    <Context>
        <Locale>en_US</Locale>
        <BrowserData>
            <HostName>tmsna-sectst02-live.us.gspt.net</HostName>
            <IPAddress>172.21.246.24</IPAddress>
            <SessionId>fComi5qK32omi8ofUy80fY8m65XnSQ01veixNFtI</SessionId>
            <UserAgent>Mozilla/5.0 (Macintosh; Intel Mac OS X 10_8_0) AppleWebKit/537.4 (KHTML, like Gecko)
                Chrome/22.0.1229.94 Safari/537.4
            </UserAgent>
            <Connection>keep-alive</Connection>
            <Cookies>AuthenticationStateToken-Bx6sFfYSL50AAAE6gr5Lubni=3fd8efa3804263189ebbfb0c9da0fb0f;
                AuthenticationStateToken-MtusFfYSHPUAAAE6TY4uJKmx=a0428e48c8eb62762d5b062f7f51d972;
                AuthenticationStateToken-1sisFfYSakYAAAE6wvJ0AblK=9f1385a53b2ff529c0efcfc56a068c44
            </Cookies>
            <JavascriptData>
                TF1;015;;;;;;;;;;;;;;;;;;;;;;Mozilla;Netscape;5.0%20%28Macintosh%3B%20Intel%20Mac%20OS%20X%2010_8_0
%29%20AppleWebKit/537.4%20%28KHTML%2C%20like%20Gecko%29%20Chrome/22.0.1229.94%20Safari/537.4;20030107;undefined;true;;
true;MacIntel;undefined;Mozilla/5.0%20%28Macintosh%3B%20Intel%20Mac%20OS%20X%2010_8_0%29%20AppleWebKit/537.4%20%28KHTML
%2C%20like%20Gecko%29%20Chrome/22.0.1229.94%20Safari/537.4;en-US;ISO-8859-1;tmsna-sectst02-live.us.gspt.net;undefined;
undefined;undefined;undefined;true;true;1351968880404;-5;Tue%20Jun%2007%202005%2021%3A33%3A44%20GMT-0400%20%28EDT%29;
1440;900;;11.4;7.7.1;;;;2;300;240;Sat%20Nov%2003%202012%2014%3A54%3A40%20GMT-0400%20%28EDT%29;24;1440;810;0;22;;;;;;
Shockwave%20Flash%7CShockwave%20Flash%2011.4%20r402;;;;QuickTime%20Plug-in%207.7.1%7CThe%20QuickTime%20Plugin%20allows
%20you%20to%20view%20a%20wide%20variety%20of%20multimedia%20content%20in%20web%20pages.%20For%20more%20information%2C
%20visit%20the%20%3CA%20HREF%3Dhttp%3A//www.apple.com/quicktime%3EQuickTime%3C/A%3E%20Web%20site.;;;;;;;;;14;
            </JavascriptData>
            <Referrer>
                https://tmsna-sectst02-live.us.gspt.net/gsi/webstore/WFS/TMSNA-TMSUS-Site/en_US/-/USD/ViewData-Start/
1644409024?JumpTarget=ViewCheckoutReview-Start
            </Referrer>
            <HTTPAcceptData>
                <ContentTypes>text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8</ContentTypes>
                <Encoding>gzip,deflate,sdch</Encoding>
                <Language>en-US,en;q=0.8</Language>
                <CharSet>ISO-8859-1,utf-8;q=0.7,*;q=0.3</CharSet>
            </HTTPAcceptData>
        </BrowserData>
        <TdlOrderTimestamp>2012-11-03T18:54:40.458Z</TdlOrderTimestamp>
        <SessionInfo>
            <TimeSpentOnSite>00:29:12</TimeSpentOnSite>
            <AuthorizationAttempts>1</AuthorizationAttempts>
        </SessionInfo>
        <CustomAttributes>
            <Attribute>
                <Key>CustomerId</Key>
                <Value>Customer123</Value>
            </Attribute>
        </CustomAttributes>
    </Context>
</UpdateSubscriptionRequest>

Update Subscription Response

<?xml version="1.0" encoding="UTF-8"?>
<UpdateSubscriptionResponse xmlns="http://schema.gspt.net/Order/1.0" 
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <SourceId type="CHANNEL">TMSUS</SourceId>
    <CustomerId>Customer123</CustomerId>
    <CreateTimestamp>2014-07-25T18:54:42.120</CreateTimestamp>
    <ResponseCode>SUCCESS</ResponseCode>
</UpdateSubscriptionResponse>

Cancel Subscription

For subscription search, the customer ID and subscription ID are included in the URI string.

Cancel Subscription Request

<?xml version="1.0" encoding="UTF-8"?>
<CancelSubscriptionRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
                           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                           sessionId="session123">
    <CreateTimestamp>2014-07-25T18:54:42.120</CreateTimestamp>
    <CancelReason>Because</CancelReason>
</CancelSubscriptionRequest>

Cancel Subscription Response

<?xml version="1.0" encoding="UTF-8"?>
<CancelSubscriptionResponse xmlns="http://schema.gspt.net/Order/1.0" 
                            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <SourceId type="CHANNEL">TMSUS</SourceId>
    <CustomerId>Customer123</CustomerId>
    <CreateTimestamp>2014-07-25T18:54:42.120</CreateTimestamp>
    <ResponseCode>SUCCESS</ResponseCode>
</CancelSubscriptionResponse>