====== SubscriptionRequest ======

==== Overview ====

**SubscriptionRequest** will **generate a new Subscription** in the SubscriptionBridge system, which will then create a recurring payment profile with the payment gateway associated with the SubscriptionBridge //store//. As part of this process, SubscriptionBridge securely passes payment information (i.e. the credit card details) to the payment gateway.

  * Credit card information is never saved by SubscriptionBridge
  * Credit card information __should not__ be saved by your application

**Learn More:**

  * [[:developer_guide:developer_guide#using-the-apis|Using the APIs]]  
  * [[:developer_guide:developer_guide#http-status-code|HTTP Status Codes]]  
  * [[:developer_guide:developer_guide#error-codes|Error Codes]] 
  * [[:developer_guide:developer_guide#troubleshooting|Troubleshooting]] 


===== SubscriptionRequest =====


==== XML ====

<code>

<?xml version="1.0" encoding="utf-8"?>
    <SubscriptionRequest>
	<Username>string</Username>
        <Token>string</Token>
        <Customer>
               <Email>string</Email>
               <FirstName>string</FirstName>
               <LastName>string</LastName>
               <BillingAddress>
                      <FirstName>string</FirstName>
                      <LastName>string</LastName>
                      <Company>string</Company>
                      <Address>string</Address>
                      <Address2>string</Address2>
                      <City>string</City>
                      <Region>string</Region>
                      <PostalCode>string</PostalCode>
                      <Country>string</Country>
                      <Phone>string</Phone>
               </BillingAddress>
               <ShippingAddress>
                      <FirstName>string</FirstName>
                      <LastName>string</LastName>
                      <Company>string</Company>
                      <Address>string</Address>
                      <Address2>string</Address2>
                      <City>string</City>
                      <Region>string</Region>
                      <PostalCode>string</PostalCode>
                      <Country>string</Country>
                      <Phone>string</Phone>
               </ShippingAddress>
               <Password>string</Password>
               <Account>string</Account>
        </Customer>
        <CreditCard>
               <CardNumber>string</CardNumber>
               <CardType>string</CardType>
               <ExpMonth>string</ExpMonth>
               <ExpYear>string</ExpYear>
               <SecureCode>string</SecureCode>
        </CreditCard>
        <Cart>
               <RegularAmt>currency</RegularAmt>
               <TrialAmt>currency</TrialAmt>
               <RegularTax>currency</RegularTax>
               <TrialTax>currency</TrialTax>
               <RegularShipping>currency</RegularShipping>
               <TrialShipping>currency</TrialShipping>
               <IsShippable>boolean</IsShippable>
               <ShipName>string</ShipName>
               <TaxName>string</TaxName>
               <AgreedToTerms>boolean</AgreedToTerms>
               <LanguageCode>string</LanguageCode>
        </Cart>
        <Package>
               <LinkID>string</LinkID>
               <Plan>
                      <Profile>
                             <IsTrial>boolean</IsTrial>
                      </Profile>
               </Plan>
        </Package>	
    </SubscriptionRequest>

</code>



==== Elements (Linked Method) ====


^ Name ^ Type ^ Occurrence  ^ Meaning ^
| **SubscriptionRequest** | container | required | Parent Element |
| Username | string | required | Merchant API Username (Not your Merchant Center login) |
| Token| string | required | Hash of API Username and Password. [[:developer_guide:developer_guide:LinkID|Creating a Token]] |
| **Customer** | container | required | Parent Element |
| Customer/Email | string | required | customer email address |
| Customer/FirstName | string | required | customer first name |
| Customer/LastName | string | required | customer last name |
| **Customer/BillingAddress** | container | required | Parent Element |
| Customer/BillingAddress/FirstName | string | required | billing first name |
| Customer/BillingAddress/LastName | string | required | billing last name |
| Customer/BillingAddress/Company | string | optional | billing company |
| Customer/BillingAddress/Address | string | required | billing address |
| Customer/BillingAddress/Address2 | string | optional | billing address line 2 |
| Customer/BillingAddress/City | string | required | billing city |
| Customer/BillingAddress/Region | string | conditional | billing state code or province |
| Customer/BillingAddress/PostalCode | string | conditional | billing postal code |
| Customer/BillingAddress/Country | string | required | billing country |
| Customer/BillingAddress/Phone | string | required | billing phone |
| **Customer/ShippingAddress** | container | required | Parent Element |
| Customer/ShippingAddress/FirstName | string | required | shipping first name |
| Customer/ShippingAddress/LastName | string | required | shipping last name |
| Customer/ShippingAddress/Company | optional | required | shipping company |
| Customer/ShippingAddress/Address | string | required | shipping address |
| Customer/ShippingAddress/Address2 | optional | required | shipping address line 2 |
| Customer/ShippingAddress/City | string | required | shipping city |
| Customer/ShippingAddress/Region | conditional | required | shipping state code or province |
| Customer/ShippingAddress/PostalCode | conditional | required | shipping postal code |
| Customer/ShippingAddress/Country | string | required | shipping country |
| Customer/ShippingAddress/Phone | optional | required | shipping phone |
| Customer/Password | string | optional | a password for the customer center, which will allow you to use the auto log in feature to avoid double login |
| Customer/Account | string | optional | an account number of the customer in the 3rd party system |
| **CreditCard** | container | required | Parent Element |
| CreditCard/CardNumber | string | required | valid credit card number |
| CreditCard/CardType | string | required | card type (Visa, MasterCard, Discover, Amex)|
| CreditCard/ExpMonth | string | required | expiration month in format "mm" |
| CreditCard/ExpYear | string | required | expiration year in format "yyyy" |
| CreditCard/SecureCode | string | required | 3 or 4 digit security code |
| **Cart** | container | required | Parent Element |
| Cart/RegularAmt | currency | required | total amount less tax and shipping |
| Cart/TrialAmt | currency | conditional | total trial amount less tax and shipping |
| Cart/RegularTax | currency | optional | tax amount |
| Cart/TrialTax | currency | optional | trial tax amount |
| Cart/RegularShipping | currency | optional | shipping amount |
| Cart/TrialShipping | currency | optional | trial shipping amount |
| Cart/IsShippable | boolean | required | Is the product shipped? (0 = false, 1 = true) |
| Cart/ShipName | string | conditional | name to identify shipping method |
| Cart/TaxName | string | conditional | name of tax location or zone |
| Cart/AgreedToTerms | boolean | required | Customer has agreed to terms? (0 = false, 1 = true) |
| Cart/LanguageCode | string | required | valid language code (en-US, it-IT) |
| **Package** | container | required | Parent Element |
| Package/LinkID | string | required | Package Link ID |
| **Package/Plan** | container | required | Parent Element |
| Package/Plan/Profile | container | required | Parent Element |
| Package/Plan/Profile/IsTrial | boolean | required | Is there a trial? (0 = false, 1 = true) |



===== SubscriptionResponse =====


==== XML ====

<code>

<?xml version="1.0" encoding="utf-8"?>
    <SubscriptionResponse>	
        <Ack>string</Ack>
	<Timestamp>timestamp</Timestamp>
        <Guid>string</Guid>
        <Terms>string</Terms>
    </SubscriptionResponse>

</code>



==== Elements ====


^ Name ^ Type ^ Occurrence  ^ Meaning ^
| **SubscriptionResponse** | container | required | Parent Element |
| Ack | string | always | Success, Error, or Warning |
| Timestamp | string | always | All responses return the official SB time stamp in UTC/GMT |
| Guid | string | always | This is the identifier for the subscription and should be referenced in future management requests |
| Terms | string | always | The terms for the package (e.g. Free for 2 Months) |