Was this article helpful?

Zuora API Developer's Guide

Modified 11:51, 12 Oct 2011 by Neal Kaplan | Page History

No headers

View tutorials for:

Intermediate tutorials

API Use Cases and Examples

Logging In to the Zuora System: Logging in is a prerequisite for all calls. For information on obtaining login credentials, see Getting Started with the Zuora API.
Creating an Active Account with the create() Call: To create a new active account, you will be using a number of different objects. The following method uses the create() call to create an account, a contact, and a payment method.
Using Customizable Gateway Options: Zuora allows you to pass in any value for payments for Verifi and CyberSource. This feature allows you to specify one or more gateway options. For each gateway option, you pass a name and a value. Zuora takes the name and value passes it to the gateway. This allows you to add functionality that supported by a specific gateway but currently not supported by Zuora. The following sections provide code samples for the gateway option functionality.
Creating an Export: Use the Zuora Export object to conveniently query and access data that is joined with other objects.

Creating a Product Catalog: You can now create and update your product catalog via the Z-Commerce API. Creating your product catalog consist of three basic steps: Create a product Create a product rate plan for the product Create charges for the product rate plan This topic includes examples (SOAP) of creating products, rate plans, and various charges and prices.
Updating the Product Catalog: You can update all aspects of the product catalog, including: Products Product Rate Plans Product Rate Plan Charges Product Rate Plan Charge Tiers Note: As of version 26.0+, you can update ProductRatePlanCharge and ProductRatePlanChargeTier objects, giving you full programmatic control of the product catalog.

Invoking the subscribe Call: To invoice the subscribe() call, begin by populating all of the data (account, contact, payment method, etc.), then call subscribe().
Provisioning Subscriptions: Provisioning is the process of setting up the various aspects of a subscription.

Adding a Product: Use the NewProduct amendment to add a product to a subscription. The method that you use depends on the version of the Zuora API that you are using.
Updating a Product: Use the UpdateProduct amendment to update a product in a subscription. The method that you use depends on the version of the Zuora API that you are using.
Removing a Product: Use the RemoveProduct amendment to remove a product from a subscription. The method that you use depends on the version of the Zuora API that you are using.
Changing the Terms and Conditions: Use the TermsAndConditions amendment to change the terms and conditions of a subscription. The method that you use depends on the version of the Zuora API that you are using.
Renewing a Subscription: Use a Renewal amendment to cancel a subscription. The method that you use depends on the version of the Zuora API that you are using. Note that a subscription will automatically renew if the Subscription field AutoRenew has been set to true.
Canceling a Subscription: Use the Cancellation amendment to cancel a subscription. The method that you use depends on the version of the Zuora API that you are using. You cannot cancel draft subscriptions.

Generating an Invoice: This use case describes how to generate an invoice programmatically.
Querying an Invoice Body Field: You can use a specially-encoded PDF file for an invoice (through the Invoice object's Body field). Once you add the invoice in the system, you can query on that field. This use case provides information about this procedure.
Applying Payments to an Invoice: As of API version 22, Zuora offers an improved, streamlined method of creating a payment and applying a payment to an invoice with a single API call. Zuora recommends all Z-Commerce API users to use the latest method. However, if you are using an API version earlier than 22.0, or if you want to apply a single payment to multiple invoices, use the original method.

Invoice Adjustment Use Cases: This topic provides information about creating an adjustment to an invoice, canceling an adjustment, and deleting an adjustment.
Invoice Item Adjustment Use Cases: This topic provides information about creating an adjustment to an invoice item, canceling an adjustment, and deleting an adjustment.

Creating Usage: In this use case, usage will be created programmatically for an account.
Reading Usage: This use case queries programmatically for usages that were created in the system.
Deleting Usage: This use case describes how to delete Usage objects programmatically from an account.

Handling Overpayments: At times, customers will overpay the amount due on their invoices. With Zuora's credit balance feature, you can track readily track overpayments, and store credit on a customers account, which can then be later used to pay for future charges or refunded back to the customer. Zuora tracks of all payments, invoices, and refunds.
Creating Credit Balance Adjustments: Using Credit Balance Adjustments you can increase or decrease a customer's credit balance.
Canceling a Credit Balance Adjustment: You can cancel a CreditBalanceAdjustment. Zuora does not support deleting CreditBalanceAdjustments.
Refunding Credit Balances: Refunds issue money back to customers.

Add a Troubleshooting Page

Troubleshooting pages are for users to identify reasons and fixes for problems. To mark a troubleshooting page, add the tag article:task-troubleshooting to any page.

View references for:

Features
Samples

Features

Filter Statements: A query includes filter statements. A filter statement must evaluate as true, or the item will not be included in the query results. Filter statements can use different operators, which are described in the following sections.
Query Statement Examples: This topic provides examples showing how you can construct queries.

Zuora API Version History: This topic describes the features available in Zuora's Z-Commerce API, listed by the version in which the features were released. See New Features for information about API changes in the latest release.

Objects and Their Supported Calls: The following matrix shows which objects in the Zuora API can be used with which calls. See API Objects for detailed reference information about the individual objects.

Error Handling

Errors: Errors are row-level failures that occurred when trying to do a batch call ; for example, trying to create 20 accounts, where 18 succeed but 2 have errors. With errors, whichever part succeeded will be processed, and one or more error codes will be returned indicating where the errors occurred.
Faults: Faults are fatal, call-level errors. When a fault occurs, nothing is processed because the entire call was invalid—for example, there was an incorrect ZOQL statement, an invalid authentication, or a server error.

API Calls

amend(): Use the amend() to amend a subscription in a single call. This call and replaces the need to use create() with an Amendment object. See Amendment Use Cases for more information about using the various methods for creating amendments. Note: The amend() call is only available in versions 29.0+ of the API.
create(): Use create() to create one or more objects of a specific type. You can specify different types in different create() calls, but each create() call must apply to only one type of object.
delete(): Deletes one or more objects of the same type. You can specify different types in different deletecalls, but each delete call must only apply to one type of object.
generate(): Generate is used to generate an invoice for a given account. Similarly to an ad hoc bill run for a single customer account, you can now create an invoice on demand via the API.
login(): The login() call takes a user name and a password and logs you in to the Zuora server. Although you can log in, you cannot explicitly log out. The session timeout for any given login session is two (2) hours.
query(): Use query() to request information from an object.
queryMore(): Use queryMore() to request additional results from a previous query() call. If your initial query() call returns more than 2000 results, you can use queryMore() to query for more the additional results Contact Zuora Global Support to enable queryMore() functionality.
subscribe(): The subscribe() call bundles the information required to create one or more new subscriptions. This is a combined call that you can use to perform all of the following tasks in a single call. Create accounts Create contacts Create payment methods Apply the first payment to a subscription
subscribeWithExistingAccount(): Important: subscribeWithExistingAccount() is deprecated in versions 11.0+. Please use subscribe() to create subscriptions for accounts that already exist if you are using version 11.0+. If you have already created an account, use this call to create a subscription for that account. The call takes an account ID, creates a new subscription, and, optionally, generates an invoice on that account and applies a payment immediately. If you use this call on an account with an existing subscription, the new subscription will be created and, if options are set to generate an invoice and apply payment, the invoice will include outstanding charges for all existing subscriptions for that account (including the previous subscriptions as well as the new one being created). The payment would then be applied to the outstanding balance for the newly created invoice.
update(): Updates the information in one or more objects of the same type. You can specify different types of objects in different update() calls, but each specific update() call must apply to one type of object.

Previewing a Subscription (API): Starting with version 25.0 of the API, select customers will now have the ability preview invoices that would be generated by the subscribe() call.

API Objects

Account: The customer's account. Zuora uses the Account object to track all subscriptions, usage, and transactions for a single account to be billed. Each Account is the source of a recurring invoice stream. Each account must capture everything Zuora needs in order to bill and collect, including "bill to" addresses, payment method and payment method details, payment terms (for example, Net 30), and more. A new account must be created before a new subscription can be entered. Using this Object Use the Account object to create billing accounts. A billing account contains all of the relevant billing information, including name and billing terms, contacts, payment methods, and subscriptions. A subscription can only be created for an active account. Invoices are created at the account level and can include all of the charges across many subscriptions for this account. Fields Name Required? Type Allowed Operations Description AccountNumber Yes string Create Query Update Delete Filter The account number associated with the account that is being created. This must be unique within your system. Zuora will create an account number if you do not specify a value. If you specify an account number, Zuora uses the number you specify unless it conflicts with an account number already in the system. An account number always exists. Zuora will assign an account number if you do not specify a value. This is different than the ID. Allowable Values: This can either be null on insert, which will auto-populate based on the account number prefix specified in setup, or a string value that does not begin with the account number prefix specified in setup. 50 characters maximum. AdditionalEmailAddresses No string Create Query Update Delete Filter Introduced in 7.0 of the API. A list of additional list of email addresses emailed invoices should be sent to. Allowable Values: A comma-separated list of email addresses. 1200 characters maximum. AllowInvoiceEdit Yes boolean Create Query Update Delete Filter Indicates whether the invoice can be edited (true) or not (false). If you omit this in create(), subscribe(), or subscribeWithExistingAccount(), it will default to false. Allowable Values: true, false AutoPay No boolean Create Query Update Delete Filter Set this to true if all future payments are to be automatically billed when due. This can only be set to true if the default payment method is an electronic payment method. For subscribe(), you must pass an electronic payment method like a credit card to set to true. If you use create(Account), you must set the default payment method to an electronic payment method before you can activate the account and have AutoPay set to true. Allowable Values: true, false (default) Balance No double (v1.0-18.0) decimal (v19.0+) Query Filter The current outstanding balance for the account. This is a read-only field. Allowable Values: A valid currency amount. Batch Yes string Create Query Update Delete Filter This will be validated against the list of batches defined in the system. Allowable Values: Any of the system-defined batches (Batch1-Batch20). BcdSettingOption No string Create Query Update Delete Filter Specify AutoSet or ManualSet. The default value is ManualSet. When the value is set to AutoSet, you cannot set the billing cycle day (BCD). The BCD value will be populated automatically by Zuora. Allowable values: AutoSet, ManualSet (default) BillCycleDay Yes int Create Query Update Delete Filter Represents the billing cycle day (BCD) for the account, and when billing runs generate invoices for this account. Usually set based to the same day the account was created to avoid any proration charges on first invoice. Set the value to 31 to indicate "end of month." Set the value to 0 (zero) to set the value to use the auto-set functionality. This allows the account BCD to be set to the same day as the triggering date of the first recurring charge on the account. This only applies to recurring charges, and not to one-time or usage charges. See Customer Accounts: Bill Cycle Day for more information. Allowable Values: Any of the system-defined bill cycle days (1–30) that have been activated within Z-Billing administration. Specify 0 to set the billing cycle day to Auto-set (WSDL version 30 and above). Specify 31 to set it to end of month. BillToId See description zns: ID Create Query Update Delete Filter This is the ID of the person who is to be billed for the subscription. It can be the same as the SoldToId. This value is required for active accounts. This value is not required for draft accounts. Allowable Values: A valid contact ID created for this account. If you do not specify this value in subscribe() or subscribeWithExistingAccount(), Zuora will generate the ID from the specified contact. CommunicationProfileId No zns:ID Create Query Update Delete Filter When creating a new account or updating an existing customer account, set CommunicationProfileId to a specific profile ID. See Setup Profiles, Notifications, and Templates for more information about using communication profiles. You can set the communication profile field from a subscribe() call when creating a new subscription. See CommunicationProfile for information about the CommunicationProfile object. Allowable Values: The ID of a communication profile. CreatedById No zns: ID Query Filter The Zuora system automatically generates this Id of the user who created the object. This is a system-generated value. Allowable Values: This field is not editable. 32 characters maximum. CreatedDate No dateTime Query Filter The Zuora system automatically generates this, and denotes when the objects was first created. Allowable Values: This field is not editable. CreditBalance No decimal Query Filter Displays the total credit balance for the account. This field was made available in version 22.0, and must be enabled for the tenant. CrmId No string Create Query Update Delete Filter The CRM account ID. You can create an initial subscription using the API, and later return with another call to set or update the CrmId field in this object. Allowable Values:100 characters maximum Currency Yes string Create Query Update Delete Filter The currency with which the account is being paid. Allowable Values: Allowable values are defined in the Admin interface. CustomerServiceRepName No string Create Query Update Delete Filter The name of this account's Customer Service representative. The customer may choose to supply this information if a Customer Service representative was involved. Allowable Values: 50 characters maximum DefaultPaymentMethodId See description zns: ID Create Query Update Delete Filter A reference to the default payment for this account. This field is required if AutoPay is set to Yes. Allowable Values: The ID of an existing payment method on Account Gateway No string Create Query Update Delete Filter Deprecated with version 23.0, and has been renamed PaymentGateway. Specifies which gateway to use to process electronic payments and refunds. Allowable Values: The valid name of a configured gateway InvoiceDeliveryPrefsEmail No. boolean Create Query Update Delete Filter Specifies whether the customer prefers to receive an invoice via email. You cannot set this value in subscribe(). If you are creating an account with subscribe(), use update() on the account object to set this to true. Allowable Values: True, false. The default value is false. InvoiceDeliveryPrefsPrint No boolean Create Query Update Delete Filter Specifies whether the customer prefers to receive a printed version of the invoice (typically via postal mail). You can download the PDF invoice for print from the invoice detail page or from the bill run. Allowable Values: True, false. The default value is false. InvoiceTemplateId No zns: ID Create Query Update Delete Filter A reference to the invoice template. This allows each customer account to use a specific invoice template for invoice generation. Allowable Values: The ID of the template to be used for generating invoices. LastInvoiceDate No dateTime Query Filter The date when the last invoice was generated for an account. The field is NULL if no invoice has ever been generated for the account. This is a read-only field. Allowable Values: This field is system-generated and not editable. Name Yes string Create Query Update Delete Filter This is the name of the account. Allowable Values: 50 characters maximum Notes No string Create Query Update Delete Filter Use this to record notes about the account. Allowable Values: 65535 characters maximum ParentId No zns: ID Create Query Update Delete Filter If you have customer hierarchy enabled, you can use this to define a parent customer account for an account. Allowable Values: The ID of the parent account. PaymentGateway No string Create Query Update Delete Filter Replaces the field Gateway as of version 23.0. Specifies which gateway to use to process electronic payments and refunds. Inherits the default set in Payment Settings if you do not specify a value. Allowable Values: The valid name of a configured gateway PaymentTerm Yes string Create Query Update Delete Filter This field maps to the payment terms defined for your organization as configured in administrative settings. If a value is provided, it will be referenced with the list of supported payment terms. Allowable Values: Typical payment terms (for example, Due Upon Receipt, Net 30, Net 45) PurchaseOrderNumber No string Create Query Update Delete Filter The number of the purchase order associated with this account. Allowable Values: Any text string, 100 characters maximum SalesRepName No string Create Query Update Delete Filter The customer may choose to supply this information based on whether a sales rep was involved. Allowable Values: 50 characters maximum SoldToId See description zns:ID Create Query Update Delete Filter This is the ID of the person who the subscription is being sold to. This value can be the same as the BillToId. This value is required for active accounts. This value is not required for draft accounts. Allowable Values: A valid contact ID created for this account Status See description string Create Query Update Delete Filter The status of the account. The values are case sensitive and must be used exactly as shown here. You must include Contact Id values in the BillToId and SoldToId fields when changing Status from Draft to Active. This field is not required in subscribe() calls, which automatically create an active account. This field is required for create() calls. Allowable Values: Draft, Active, Canceled TaxExemptCertificateId No string Create Query Update Delete Filter The ID/identifier of the tax exemption certificate. This field is available only to customers of Z-Tax. Allowable Values: Any string, can be null. 32 characters maximum. TaxExemptCertificateType No string Create Query Update Delete Filter This is a freeform field that allows you to identify the type of tax exemption certificate. This field is available only to customers of Z-Tax. Allowable Values: Any string, can be null. 32 characters maximum. TaxExemptDescription No string Create Query Update Delete Filter Free form field to describe the tax exemption. This field is available only to customers of Z-Tax. Allowable Values: Any string, can be null. 500 characters maximum. TaxExemptEffectiveDate No dateTime Create Query Update Delete Filter The date on which the account becomes tax exempt. This field is available only to customers of Z-Tax. Allowable Values: A valid datetime stamp. TaxExemptExpirationDate No dateTime Create Query Update Delete Filter The date on the account on which the tax exemption status ends. This field is available only to customers of Z-Tax. Allowable Values: A valid date TaxExemptIssuingJurisdiction No string Create Query Update Delete Filter A freeform field used to describe the jurisdiction of the tax exemption issuing authority/jurisdiction. This field is available only to customers of Z-Tax. Allowable Values: Any string, can be null. 32 characters maximum. TaxExemptStatus See description string Create Query Update Delete Filter The status of the tax exemption for the account. This field is required if you are using Z-Tax. This field is not required if you are not using Z-Tax. Allowable Values: Yes, No, PendingVerification. TotalInvoiceBalance No decimal Query Filter Total balance of this customer account's invoices. This field is applicable and available only to customers using Credit Balances. UpdatedById No zns:Id Query Filter The Zuora system automatically generates this Id of the user who last updated the object. Allowable Values: This field is not editable. 32 characters maximum. UpdatedDate No dateTime Query Filter The Zuora system automatically generates this, and denotes when the objects was last updated. Allowable Values: This field is not editable. Related
Amendment: Use Amendment to make changes to a subscription. For example, if you wish to change the terms and conditions of a subscription, you would use an Amendment.
CommunicationProfile: This object contains information about a communication profile for an account. This object was added in version 30 of the Z-Commerce API.
Contact: This defines the contact (the end user) for the account. There are two types of contacts that need to be created as part of the customer account creation: the Bill-To and the Sold-To contacts. Contact provides the attributes needed to create these.
CreditBalanceAdjustment: The CreditBalanceAdjustment is an adjustment that can add or subtract to the customer's credit balance. This is helpful tracking overpayments and credits where refunds are not appropriate. This object is only available in version 22.0 of the API and greater.
Export: Exports mimic the export functionality in Z-Billing and Z-Payments, and are intended to be used for: Large data sets Objects joined with other objects not readily attainable via Z-Commerce API MS-Excel and other applications. You can readily import the files into Microsoft Excel or other applications for charting, reporting, accounting or other business intelligence applications.
Invoice: This object provides needed information about the customer's account for an invoice, including payment terms, payment type, and due date.
InvoiceAdjustment: This object connects a specific invoice with the specific adjustment that is being made to that invoice.
InvoiceItem: This object is a line item of an invoice, detailing a specific charge.
InvoiceItemAdjustment: This object is an adjustment of an InvoiceItem, and allows you to adjust either invoice charge items or taxes.
InvoicePayment: This object ties a payment to an invoice, providing information on how much the payment is and how a payment is to be applied to one or more invoices. Only one PaymentID and once InvoiceID are accepted (you cannot spread a payment across multiple invoices).
Payment: The Payment is a description of the customer's payment: how much the customer is paying, which invoice or invoices the payment is to be applied to, and the type of payment being made.
PaymentMethod: PaymentMethod contains information on how the contact pays for the account. In order to activate an account, you need to create a payment method.
Product: The Product Catalog within Zuora is used to build subscriptions. The Product object provides the list of products, along with the details of their product rate plans and product rate plan charges. Each product can have one or more product rate plans, and each rate plan can have one or more product rate plan charges. In addition, each rate plan charge can have one or more tiers. You can use this object to identify what is in the product catalog, and to identify the product rate plan ID that is necessary for the subscribe call.
ProductRatePlan: A ProductRatePlan is part of a product, which in turn can be associated with one or more subscriptions. A rate plan is what your customer is signing up for. Each product can have one or more product rate plans, and each product rate plan can have one or more product rate plan charges. Rate plan charges are the actual charges for the services (rate plans) that you are giving, and can be of different types, including one-time fees, monthly recurring fees, and usage fees.
ProductRatePlanCharge: A ProductRatePlanCharge, like ProductRatePlan, is part of a Product. Every product can have one or more rate plans, and each rate plan can have one or more rate plan charges. Rate plan charges are actual charges for services you are providing, and can be of different types. For example, one-time fees, monthly recurring fees, and usage-based fees.
ProductRatePlanChargeTier: A ProductRatePlanChargeTier represents one tier of charges for a ProductRatePlanCharge. Each rate plan charge has one or more tiers associated with it. For example, you can use the tiers to create different charges for different quantities of an item: 1 to 400 text messages would have one price, and that would be one tier. You can then create a second tier, with a second price, for 401 to 800 text messages.
RatePlan: A RatePlan is part of a subscription. Each subscription can have one or more rate plans, and each rate plan can have one or more rate plan charges. A rate plan is essentially a price or a collection of prices for a service you are offering. When a RatePlan object of type NewProduct is created as part of an amendment, the ProductRatePlans and ProductRatePlanCharges from the corresponding product are created automatically as RatePlans and RatePlanCharges on the amendment. To update a particular RatePlanCharge, you must first query it and then update the desired field (Quantity) by ID.
RatePlanCharge: A RatePlanCharge, like RatePlan, is part of a subscription. Each subscription can have one or more rate plans, and each rate plan can have one or more rate plan charges. Rate plan charges are the actual charges for the services (rate plans) that you are giving, and can be of different types. For example, one-time fees, monthly recurring fees, and usage fees.
RatePlanChargeTier: A RatePlanChargeTier represents one tier of charges for a RatePlanCharge. Each rate plan charge can have one or more tiers associated with it. You can create tiers with different charges for different quantities of an item. For example, you can create different charges for different quantities of an item: 1 to 400 text messages would have one price, and that would be one tier; 401 to 800 text messages would have another price, and that would be a second tier.
Refund: The Refund object is used to create and query refunds. Note that refunds imply that money has been returned to customers. You should use adjustments (credit memos) if you are issuing credit to customers, but are not returning funds to a customer. Refunds must be applied against a previous payment, and cannot exceed the payment amount. Refunds are available from version 18 of the Zuora API.
RefundInvoicePayment: This object is generated automatically by Zuora when you create a refund.
Subscription: This object contains the information needed to create a new subscription for an account. It is part of the entire subscribe process. The subscribe() call is a superset of Subscription. A subscription represents a customer signing up for a product for a certain amount of time. Each subscription can have one or more RatePlans. See Invoking The subscribe() Call for more information about creating subscriptions.
TaxationItem: This object is for customers that have purchased Z-Tax. Z-Tax allows you to apply taxation and manage your customer's tax exemption status.
Usage: This object tracks how many units a customer has used of a certain product, such as the number of minutes in a telephone plan. You can import the data through the Zuora application Admin console, or you can upload a CSV (comma-separated values) file. Spreadsheet programs have the capability of exporting data to CSV files.
zObject: This is the base object from which all other objects have been extended.

Core Data Types: The following data types are used in various ways in applications created using this API.
Field Types: The underlying basic data types used in the WSDL, described in Understanding the Zuora WSDL, can have different interpretations depending on context. For example, text, textarea, email, phone number, enum, and autonumber are all different types of string fields. The possible interpretations of the basic WSDL data types are provided on the following table.

API Complex Types

amendOptions: AmendOptions is used with the amend() call.
AmendResult: This object provides the result of the amend() call.
CallOptions: The CallOptions is used when using create() with an amendment. It is only used in versions 25.0+ of the API, and is used when creating amendments in a single call. This insures that if one of the operations fails (either create or activate), the entire action will be rolled back. See Amendment Use Cases for more information about working with amendments.
DeleteResult: This object provides the result of the delete() call.
InvoiceData: This object provides the results of a subscribe() request in preview mode. It returns what an invoice would be for the given subscribe() call.
InvoiceProcessingOptions: InvoiceProcessingOptions is used with amend() call, and is wrapped by AmendOptions object.
LoginResult: This is the object returned from the login() call.
PreviewOptions: Use PreviewOptions with the amend() and subscribe() calls to specify whether the call should return an actual subscription or amendment, or a preview of what the subscription or amendment would be if activated. This is useful when you want to see what charges would be for a customer considering an order (such as a new order, upgrade/downgrade, adding a product, or adding additional units). You can also use this to debug during implementations or when writing new business logic with the Z-Commerce API.
QueryResult: This object provides the result of the query() call.
RatePlanChargeData: RatePlanChargeData is used to pass complex data to the subscribe() and subscribeWithExistingAccount() calls. Each RatePlanChargeData identifies one RatePlanCharge object and a list of one or more RatePlanChargeTiers. The subscribe() and subscribeWithExistingAccount() calls do not require you to include RatePlanChargeData. Use this to override the price, override the description, override the name, or set quantities.
RatePlanData: RatePlanData is used to pass complex data to the subscribe() call. Each RatePlanData identifies one RatePlan object and a list of one or more RatePlanChargeData objects.
SaveResult: This object provides the result of the create() and update() calls.
SessionHeader: A call to login returns SessionHeader as part of it. SessionHeader returns the session key. Place the SessionHeader in the header of your SOAP request.
SubscribeOptions: This object provides information for SubscribeRequest. For WSDL v10 and earlier, it also provides information for SubscribeWithExistingAccountRequest, which in turn provides the information for the subscribeWithExistingAccount() call. This object provides flags to use when creating a subscription.
SubscribeRequest: Use this object with the subscribe() call to create one or more subscriptions.
SubscribeResult: This object provides the results of a subscribe() request.
SubscribeWithExistingAccountRequest: Use this object with the subscribeWithExistingAccount() call to add a subscription to an account you have already created.
SubscriptionData: SubscriptionData is used to pass complex data to the subscribe() and subscribeWithExistingAccount() calls. Each SubscriptionData identifies one Subscription object and a list of one or more RatePlanData objects.

Country, State, and Currency Codes

Country Names and Their ISO Standard 2- and 3-Digit Codes: Use the following names and codes when working with country fields in the Zuora API.
State Names for the United States and Their Standard 2-Digit Codes: Use the following names and codes when working with state fields with the Zuora API.
Canadian Province Names and Their Standard 2-Digit Codes: Use the following names and codes when working with Canadian province names with the Zuora API.
Currencies and Their 3-Letter Codes: Use the following 3-letter codes when working with currency fields in the Zuora API.

The Z-Commerce API is a set of SOAP-based web services that make it easy for developers to access Z-Billing, Z-Payments, and Z-Force through web service calls. With the Z-Commerce API, you can plug in Zuora’s powerful subscription management, billing, and payment services into your custom applications.

This guide provides information about the Z-Commerce API. It contains recommendations for getting started, code samples, and reference information for calls and objects.

Topics

Getting Started with the Zuora API
The Z-Commerce API is designed for any developer working on a subscription service who needs: A means to sell, monetitze, and manage subscription services. The flexibility to easily change pricing, packaging, billing, and payment options with minimal IT intervention. This topic describes the steps required to begin working with the Zuora API.
Zuora Object Query Language
Filter Statements(Reference)
Query Statement Examples(Reference)
Understanding the Zuora WSDL
WSDL and API Versions(Topic)
Coding Overview
Working With SOAP(Topic)
Implementation Considerations(Topic)
Sessions(Topic)
Custom Fields
API Use Cases and Examples
With the Z-Commerce API, you can programmatically create, manage, change and cancel subscriptions, create invoices, and apply payments. In addition, you can programmatically query and update account, contact, payment method, subscription, invoice and usage data.
Logging In to the Zuora System(Tutorial)
Creating an Active Account with the create() Call(Tutorial)
Using Customizable Gateway Options(Tutorial)
Creating an Export(Tutorial)
Working with the Product Catalog
Creating a Product Catalog(Tutorial)
Updating the Product Catalog(Tutorial)
Working with Subscriptions
Making Changes: Amendment Use Cases(Topic)
Invoking the subscribe Call(Tutorial)
Provisioning Subscriptions(Tutorial)
Working with Invoices
Adjusting Invoices(Topic)
Generating an Invoice(Tutorial)
Querying an Invoice Body Field(Tutorial)
Applying Payments to an Invoice(Tutorial)
Working with Usage
Creating Usage(Tutorial)
Reading Usage(Tutorial)
Deleting Usage(Tutorial)
Working with Credit Balance Adjustments
Handling Overpayments(Tutorial)
Creating Credit Balance Adjustments(Tutorial)
Canceling a Credit Balance Adjustment(Tutorial)
Refunding Credit Balances(Tutorial)
Error Handling
Exceptions are handled using fault elements and the Error object. Although the term "error" refers to anything that goes wrong, we make a finer distinction between errors and faults.
Errors(Reference)
Faults(Reference)
API Calls
The calls in the Zuora API can be thought of as functioning much like verbs do in human languages: They are the actions that you perform. In human languages, verbs act upon objects, so in this case, the Zuora API calls are the actions you perform upon the Zuora API objects.
amend()(Reference)
create()(Reference)
delete()(Reference)
generate()(Reference)
login()(Reference)
query()(Reference)
queryMore()(Reference)
subscribe()(Reference)
subscribeWithExistingAccount()(Reference)
update()(Reference)
Call Basics
API Objects
The topics in this section provide detailed information about the Zuora API objects, including usage information, object fields, and examples of use.
Account(Reference)
Amendment(Reference)
CommunicationProfile(Reference)
Contact(Reference)
CreditBalanceAdjustment(Reference)
Export(Reference)
Invoice(Reference)
InvoiceAdjustment(Reference)
InvoiceItem(Reference)
InvoiceItemAdjustment(Reference)
InvoicePayment(Reference)
Payment(Reference)
PaymentMethod(Reference)
Product(Reference)
ProductRatePlan(Reference)
ProductRatePlanCharge(Reference)
ProductRatePlanChargeTier(Reference)
RatePlan(Reference)
RatePlanCharge(Reference)
RatePlanChargeTier(Reference)
Refund(Reference)
RefundInvoicePayment(Reference)
Subscription(Reference)
TaxationItem(Reference)
Usage(Reference)
zObject(Reference)
Object Basics
Core Data Types(Reference)
Field Types(Reference)
API Complex Types
The Zuora API complex types are used to group attributes, and provide a convenient method of setting the values of those attributes. The complex types are used by the Zuora API calls and allow you to set multiple values, or read the results of call actions.
amendOptions(Reference)
AmendResult(Reference)
CallOptions(Reference)
DeleteResult(Reference)
InvoiceData(Reference)
InvoiceProcessingOptions(Reference)
LoginResult(Reference)
PreviewOptions(Reference)
QueryResult(Reference)
RatePlanChargeData(Reference)
RatePlanData(Reference)
SaveResult(Reference)
SessionHeader(Reference)
SubscribeOptions(Reference)
SubscribeRequest(Reference)
SubscribeResult(Reference)
SubscribeWithExistingAccountRequest(Reference)
SubscriptionData(Reference)
Export ZOQL
Zuora Export ZOQL (Zuora Object Query Language) is the query language used to create Exports with the Z-Commerce API. Zuora Export ZOQL is similar to Z-Commerce API ZOQL, with a few differences. The biggest difference is that with Exports, you query a data source, not a Z-Commerce API object.
Select Statement
Aggregate Functions(Topic)
Export ZOQL Clauses
Filter Statements
Dates and Datetimes
Country, State, and Currency Codes
When using the API to enter a Contact or PaymentMethod address (through the subscribe, create, or update calls), Zuora does NOT require a state or a country to be entered. However, Zuora will require a valid country name or code if entered, as well as valid state/provinces for Canada and the US.
Country Names and Their ISO Standard 2- and 3-Digit Codes(Reference)
State Names for the United States and Their Standard 2-Digit Codes(Reference)
Canadian Province Names and Their Standard 2-Digit Codes(Reference)
Currencies and Their 3-Letter Codes(Reference)
Sample Source Code
Here you will find sample code in PHP, Java, .NET, and XML. The source code provided can help you quickly learn the Z-Commerce API as well as how to implement SOAP-based web services. Important: This code is provided as an example of the code that you can use with Zuora. You must customize the sample code for use with your system.

Table of contents

Zuora API Developer's Guide

Table of contents

Tags

Comments

Attachments

Table of contents