How To Use The Z-Commerce Platform
GENERAL Z-COMMERCE API QUESTIONS
How do I login via the Z-Commerce PI?
-
Before you make any calls via the Z-Commerce API, you must log in. To login
- Create a login request object.
- Set your username and password.
- If you are working with the sandbox, use the URL for the sandbox to log in - http://apisandbox.zuora.com/apps.services/a/2.0
- If you are working with production, use the URL for the prodcution to log in - http://www.zuora.com/apps/services/a/2.0
- The SOAP response will return the session ID.
- With a valid session ID, you can issue API calls.
What version of the Z-Commerce API should I use?
- We suggest that you use the latest version of the API in order to ensure you have access to the latest functionality.
- However, you can use any Z-Commerce API version that supplies the functionality you need. The Z-Commerce Platform will continue to support older versions.
CREATING AND QUERYING OBJECTS
How do I create a subscription?
- There are two ways to create a subscription, with the subscribe() API call or subscribewithexistingaccount() API call. You should use the subscribe() call for new customers, as this will create all required objects for a subscription for a new customer, including account, bill to and sold to contact, payment methods, and subscriptions. If the customer already has a billing account in Z-Billing System, then use the subscribewithexistingaccount().
How do I get an invoice in PDF format?
- Create a query object for an invoice, including the Body field. For example, "SELECT Id, AccountId, Amount, Balance, DueDate, InvoiceDate, InvoiceNumber, Status, TargetDate, Body FROM Invoice where Id='XXYYZZ'". Make sure to set XXYYZZ to the id of the invoice you want.
- The Body field returned is encoded in Base64, which you will need to decode.
- The resulting data is the PDF file of the invoice.
How do I create and apply payments to an Invoice?
- First, determine which invoice you want to which you want to apply a payment using the query() call, such as: SELECT Id from Invoice where AccountId = 'someAccountId'
-
Create a new Payment with the following fields set as follows:
- Status = Draft
- AccountId = someAccountId
- PaymentMethodId = somePaymentMethodId (where somePaymentMethodId refers to a valid Payment Method for the Account). Valid values are ACH, CreditCard, DebitCard, Paypal.
-
Create a new InvoicePayment with the following fields set as follows:
- InvoiceId = ID from Invoice
- PaymentId = ID from Payment. Ensure that the complete amount of the Payment is applied on the Invoice Payment
- Update the Payment with Status = Processed.
How do I create usage records?
-
Create a Usage object and set the following fields:
- AccountId = The Id of the account that the usage is to be applied.
- UOM = name of UOM (as configured in Admin settings)
- RbeStatus = "Pending"
- SubmissionDateTime, StartDateTime and EndDateTime specified
How do I read existing usage records?
- Create a query object, querying the usage for account you are interested in. Sample ZOQL would be:
SELECT Id, AccountId, SourceType, UOM, Quantity, RbeStatus, StartDateTime, EndDateTime, SourceName, SubmissionDateTime FROM Usage WHERE AccountId = 'someAccountId'
CHANGING SUBSCRIPTIONS (AMENDMENTS)
How do I cancel a subscription?
-
To cancel a subscription, you must use an amendement. First, create an amendment object, and set the following fields:
- Set Type to "Cancellation"
- Set EffectiveDate to the desired. The EffectiveDate must be equal to or later than (in the future of) the ContractEffectiveDate.
- Set SubscriptionId to the ID of the subscription you want to cancel.
- Call the create() API call passing the amendment above.
How do I change an existing subscription's pricing?
-
Create a new Amendment.
- Set Type to UpdateProduct.
- Specify the subscription's ID.
- Set the Status to Draft. Setting it to Draft is important because the amendment then won't go through until you insert the final part of the code.
- Insert the new amendment.
-
Create a new RatePlan object.
- Set AmendmentId to the ID of the new amendment you've created in step above.
- Set AmendmentType to UpdateProduct.
- Insert the new RatePlan.
- RatePlanCharges will be created in the background.
-
Update the amendment from above by setting the following fields:
- Id = id of the amendment.
- Status = Completed.
- ContractEffectiveDate = a date and time in the future.
- If you have set the "Require Customer Acceptance of Orders?" field on your Admin "Default Subscription Settings" page to Yes, then you will also need to specify a customer acceptance date.
- If you have set the "Require Service Activation?" field on your Admin "Default Subscription Settings" page to Yes, then you will also need to specify a service activation date.
-
Our sample XML code has a complete example of how to update pricing.
How do I change an existing subscription's terms?
-
Create a new Amendment. Set the following fields:
- Type = TermsAndConditions.
- Set TermCommitment and TermStartDate values you want.
- Set SubscriptionId to the ID of the subscription you want.
- Set the Status to Completed.
- Insert the new amendment.
How do I add products to an existing subscription?
-
Create a new Amendment object.
- Set the Type to NewProduct.
- Specify the subscription's ID.
- Set the Type to Draft. Setting it to Draft is important because the amendment then won't go through until you insert the final part of the code.
- Insert the new amendment with the create call.
-
Create a new RatePlan object.
- Set the AmendmentId to the Id of the new amendment you created above.
- Set the Type to NewProduct.
- Insert the new RatePlan.
- RatePlanCharges will be created in the background; for more information, see RatePlanCharge.
-
Update the amendment you created above. Set the following fields:
- Status =Completed.
- ContractEffectiveDate to a date and time in the future.
- If you have set Require Customer Acceptance of Orders? on your Admin "Default Subscription Settings" page to Yes, then you will also need to specify a customer acceptance date.
- If you have set Require Service Activation? on your Admin "Default Subscription Settings" page to Yes, then you will also need to specify a service activation date.
- Update the new amendment by using the API update call.
-
Our sample XML code has a complete example of how to add new products to an existing subscription.
How do I remove products from an existing subscription?
-
Create a new RatePlan object. Set the following fields:
- Set the AmendmentId to the Id of the amendment you've created above.
- Set the Type to RemoveProduct.
- Set AmendmentSubscriptionRatePlanId to the Id of the RatePlan you are removing from the subcription.
- Insert the new RatePlan using the create() API call. Since you have already set the Type to RemoveProduct, then the system knows that this rate plan is to be deleted from the subscription.
-
Our sample XML code has a complete example of how to remove products from an existing subscription.
