Happy Business Starts Here

Re: [SOAP] Need clarification on subscribe() API call

Highlighted
Master

[SOAP] Need clarification on subscribe() API call

Hi,

I'm executing a subscribe() call with SOAP API. The Account already exists and he has several contacts. Is it possible to use the BillToContact object in the SubscribeRequest SOAP type to set the BIllTo Contact only for that particular subscription? Or does it need to be set on the Account "globally"?

7 REPLIES 7
Highlighted
Zuora Staff

Re: [SOAP] Need clarification on subscribe() API call

Sorry but no your use case isn't directly supported by the API. The Bill To and Sold To Contact Ids are properties of the Account object, not the Subscription object. You could add a custom field to the Subscripton object to store the Bill To information but assuming you need this to appear on an invoice at some point you'll also need to customize your invoice template to conditionally display this information instead of the standard Account Bill To info when present. Our invoice templates support if/then logic so you can basically go 'if subscription bill to data present display that else display the Account bill to'. That's a gross simplification by the way, but you get the idea.

 

An alternative approach is to create a separate billing account in these situations, now you can use the standard bill to contact and your usual invoice template. A possible downside here is if it's really important to report summary data per 'real' physical customer as you'll now have multple billing accounts that collectively represent a real customer in the real world. But you can assign a parent billing account to all of the 'child' subscription accounts and now you'll be able to group by 'real' customer.

 

Without knowing more about your business I can't recommend one approach over the other, but please post more info or feedback. 

Highlighted
Master

Re: [SOAP] Need clarification on subscribe() API call

Hi @Richard, thank you for your reply, very clarifying. We tend to sell one-time products only, not using the subscription model for the moment but planning to in the future. With your first solution it seems like we could print custom data in the invoice but would we still be able to apply taxation based on the right country? I thought that was only based on the Bill To Contact values.

Highlighted
Zuora Staff

Re: [SOAP] Need clarification on subscribe() API call

Tax is based on the Sold To address, not the Bill To. Specifically it's the combination of the Sold  To address and the Tax Code attribute of the rate plan charge that are used to determine the correct tax (optionally you can also specify a Tax Region in the contact but that's probably not helpful here). The Tax Code specifies the tax table to be used, the Sold To address filters the tax table to identify the correct tax.

 

Sold To is meant to capture the location the service or product is delivered, ergo that drives taxation. Bill to is 'only' the guy who gets to pay the bill 🙂

 

Also a brief caution, while most objects in Zuora can have custom fields added, support for displaying these custom fields on the invoice is limited to a much small set documented here:

http://knowledgecenter.zuora.com/CB_Billing/IA_Invoices/Creating_a_Custom_Invoice_Template/E_Display...

Highlighted
Master

Re: [SOAP] Need clarification on subscribe() API call

So, in the case I wanted to associate a specific bill to and sold to contacts (both shuold be the same) for a purchase with correctle calculated taxes, could I use your first solution?

Highlighted
Zuora Staff

Re: [SOAP] Need clarification on subscribe() API call

Great question, wish I had a simple answer. Please bear with me for a second, a key element to the choice of solution is actually downstream, how are you expecting the customer to pay?

 

Option 1, where we store the billign info as custom fields on the subscription allows all subscriptions to share the same payment method, so once captured all future orders/subscription can hit that same credit card/ACH/Direct Debit payment method.

 

Option 2, using separate billing accounts for each subscription that are loosly tied together means the payment method has to be asked for every time the subscription is created as payment methods can't be shared across billing accounts easily.

 

While most people throw their arms up at this point and want to go with option 1, it's been my experience that option 2 can be perfectly acceptable. Customers often DON'T want everything one card and want to spread their purchases around and welcome the opportunity to use a different payment method than what they used last time. But I've seen the opposite also, where it's all about minimizing friction on order capture so asking for another payment method is a big no-no.

 

This is obviously business specific, so there's no one solution for all here. Sorry I can't be more prescriptive.  

 

Highlighted
Master

Re: [SOAP] Need clarification on subscribe() API call

Hi richard, I'm expecting the customer to pay with their stored payment method, I don't want them to re-enter it every time. I would stick with the first solution if:

 

1. I can have different billing address for every subscription

2. share the account's payment methods between subscriptions

3. correctly apply taxation based on the subscription related billing information

4. I can display the billing information on the invoice

 

I'm only sure about point 2 at the moment, can you help me on the other 3? Especially on 3-4 I've no clue how to proceed.

Highlighted
Zuora Staff

Re: [SOAP] Need clarification on subscribe() API call

K, let's assume for now that we'll use a single Zuora account which has at least one payment method (Credit Card/ACH/DD). This Zuora account has a bill to contact and sold to contact that are the same and simply identify the person who is purchasing these subscriptions.

 

Now let's look at each of your points:

 

1. I can have different billing address for every subscription - yes, but only using one or more custom fields on the subscription to store these subscription specific billing addresses. You could just have one custom field with the whole address jammed in, or one for Address, one for City, one for Zip, etc.

 

2. share the account's payment methods between subscriptions - since all the subscriptions belong to the account, the account's payment method(s) can be used to pay for the invoices the subscriptions generate. 

 

3. correctly apply taxation based on the subscription related billing information - tax is based on sold to, not bill to! So you probably want to also use custom fields to store the subscription specific sold to. BUT! If the bill to and sold to for a subscription can be different than the account bill to and sold to, why wouldn't this be a different billing account? But this would mean having to collect a payment method again (even if it's already been collected for a different account). And if the sold to at the subscription level is different than the account sold to, only the account sold to is used in determining taxation. Ergo, this approach isn't going to work! Or, more likely, I'm not understanding important things about your business! More on this below.

 

4. I can display the billing information on the invoice - custom fields on the subscription can appear on an invoice, you just need to add them, there's a KC article on this.

 

The tax functionality in Zuora leverages the Sold To on the Account, not the Bill To. So if you have two subscriptions that may have different tax rates applied as they are being delivered to different geographies (Texas vs. California say), then what you really want to do is create Zuora accounts for each subscription. The subscription specific bill to and sold to are set to the appropriate locales, one in Texas, one in California. Let's just assume the guy in Texas is the one who has the credit card you want to use to pay both subscriptions. You can then create an 'invoice owner' amendment on the California subscription that makes the Texas account the invoice owner. Now the tax will be calculated for California, but the charges and that California tax can appear on the Texas invoice and you can use the Texas credit card to pay for both the California subscription AND the Texas subscription. 

 

Now no custom fields are needed, the invoice has tax from both States but only a single credit card is used. Does this hit all the requirements?