Sign up Subscribers

Create a subscription with a customer account

Suppose that a new customer wants to subscribe to a service offered by you. You need to capture the following information:

  • Basic information about your new customer
  • The product or service you will be provisioning for them
  • Price and frequency with which they will be charged
  • The contract effective date from which the subscription becomes effective

By default the payment method will be authorized with the payment gateway you have configured for your tenant.

The following example shows how to create a subscription, passing the customer account and a reference to a plan. To learn about plans, see the Plans API operations.

cURLJavaNode
Copy
Copied
curl -X POST "https://rest.sandbox.na.zuora.com/v2/subscriptions" 
     -H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3" 
     -H "Content-Type: application/json" 
     -d '{  
          "account_data":{
            "bill_to": {
                "first_name": "Amy",
                "last_name": "Lawrence",
                "email": "amy.lawrence@zuora.com",
                "address":{
                  "line1": "101 Redwood Shors Parkaway",
                  "city": "Redwood City",
                  "postal_code": "94065",
                  "state": "CA",
                  "country": "USA"
                }
            },
            "name": "Amy Lawrence Account",
            "currency": "USD"
          },
          "subscription_plans": [{
            "plan_id": "8ad095b8813772670181383d05136860"
          }],
          "start_on":{
            "contract_effective": "2022-08-01"
          }
        }'
Copy
Copied
AccountContactCreateRequest contactCreateRequest = new AccountContactCreateRequest()
    .firstName("Amy")
    .lastName("Lawrence")
    .email("amy.lawrence@zuora.com")
    .address(new Address()
               .line1("101 Redwood Shors Parkaway")
               .city("Redwood City")
               .postalCode("94065")
               .country("USA")
               .state("CA"));

AccountCreateRequest accountCreateRequest = new AccountCreateRequest()
    .name("Amy Lawrence's Account")
    .billTo(contactCreateRequest)
    .currency("USD");

PlanCreateRequest planRequest = new PlanCreateRequest() 
    .name('Monthly Plan') 
    .productId(newProduct.getId()) 
    .startDate('2021-10-20') 
    .endDate('2031-10-19') 
    .description('Gold Product'); 

Plan newPlan = zuoraClient.plans().createPlan(planRequest); 

LocalDate todayDate = LocalDate.now();
String todayDateStr = todayDate.format(DateTimeFormatter.ISO_LOCAL_DATE);
SubscriptionCreateRequest subscriptionCreateRequest = new SubscriptionCreateRequest() 
  .accountData(accountCreateRequest) 
  .subscriptionPlans(Collections.singletonList(new SubscriptionChildPlanCreateRequest().planId(newPlan.getId())))
  .startOn(new StartOn().contractEffective(todayDateStr)); 

Subscription createdSubscription = zuoraClient.subscriptions().createSubscription(subscriptionCreateRequest);
Copy
Copied
const date = new Date();
const todayDate = date.toISOString().split('T')[0];
const planId = '8ad095b8813772670181383d05136860';
 
const account = {
  bill_to: {
    first_name: 'Amy',
    last_name: 'Lawrence',
    email: 'amy.lawrence@zuora.com',
    address:{
      line1: '101 Redwood Shors Parkaway',
      city: 'Redwood City',
      postal_code: '94065',
      state: 'CA',
      country: 'USA',
    }
},
name: 'Amy Lawrence Account',
currency: 'USD',
}
 
const subscriptionRequest = {
    account_data: account,
    subscription_plans: [
      {
        plan_id: planId,
      }
    ],
    start_on:{
      contract_effective: todayDate,
    },
};

const createdSubscription = await zuoraClient.subscriptions.createSubscription(subscriptionRequest);

Preview a subscription

You can use the "Preview a subscription" operation to generate a preview of billing documents and charge metrics of a subscription. This operation is only for preview, and no subscription or billing document is created. You can use this operation to the following metrics generated by the subscription:

  • Metrics on the billing documents, including:
    • Total amount
    • Subtotal amount
    • Tax amount
  • Delta metrics of order actions, including:
    • Gross amount of delta MRR
    • Net amount of delta MRR

For more information about the Order delta metrics, see Order Delta Mrr.

To preview a subscription, you must specify the following fields:

  • account_id or account_data
  • metrics
  • subscription_plans

The following example previews the billing document metrics for an evergreen subscription (subscription plan ID is 8ad09bce82aa84840182afab5e7b04fb) where the ID of the associated account is 8ad09b7d8292b85d0182a4d6f875225a:

cURLJavaNode
Copy
Copied
curl --request POST
     --url 'https://rest.apisandbox.zuora.com/v2/subscriptions/preview'
     --header 'Authorization: Bearer 2e4e1763af7d4cf5aaca1b519dfa3200'
     --header 'Content-Type: application/json'
     --data '{
        "account_id": "8ad09b7d8292b85d0182a4d6f875225a",
        "subscription_plans": [
          {
            "plan_id": "8ad09bce82aa84840182afab5e7b04fb"
          }
        ],
        "end_date": "2022-11-30",
        "metrics": ["billing_documents"]
      }'
Copy
Copied
LocalDate date = LocalDate.of(2022,11,30);

SubscriptionPreviewRequest previewRequest = new SubscriptionPreviewRequest()
  .metrics(Collections.singletonList(SubscriptionPreviewRequest.MetricsEnum.BILLING_DOCUMENTS))
  .endDate(date)
  .accountId("8ad09b7d8292b85d0182a4d6f875225a")
  .subscriptionPlans(Collections.singletonList(new SubscriptionPlanCreateRequest().planId("8ad09bce82aa84840182afab5e7b04fb")));

Map<String, Object> previewSubscription = zuoraClient.subscriptions().previewSubscription(previewRequest); 
System.out.println(previewSubscription);
Copy
Copied
const previewRequest = {
    account_id: '8ad09c4b84eac7870184ec0b170f1d87',
    subscription_plans: [
      {
        plan_id: '8ad09bce82aa84840182afab5e7b04fb'
      }
    ],
    end_date: '2023-4-30',
    metrics: ['billing_documents']
};
 
const previewSubscription = await zuoraClient.subscriptions.previewSubscription(previewRequest);
console.log(previewSubscription);