Skip to navigation
Guides

Recipe: Create a Subscription

Walk through the end-to-end flow to set up a customer with a subscription using the Zuora Orders API

View as Markdown

This guide walks through the complete workflow to create a customer account and attach a subscription using the Zuora Orders API. By the end, you’ll have a billable subscription ready for invoicing.

This recipe uses the Orders API, which is the recommended approach for creating and managing subscriptions. The legacy Subscription API is still available but should not be used for new integrations.

Prerequisites

  • A valid OAuth Bearer token (Authentication guide)
  • At least one Product and Rate Plan configured in your Zuora catalog
  • API access to a Sandbox or Test Drive environment for testing

Workflow Overview

1. Create Account  -->  2. Create Order (with subscription)  -->  3. Verify
1

Step 1: Create a Customer Account

Create a billing account to hold the subscription. The account requires contact information and a billing/payment configuration.

curl -X POST https://rest.test.zuora.com/v1/accounts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "currency": "USD",
    "billCycleDay": 1,
    "billToContact": {
      "firstName": "Jane",
      "lastName": "Doe",
      "workEmail": "jane.doe@acme.com",
      "country": "United States",
      "state": "California"
    },
    "paymentTerm": "Net 30"
  }'

Response

{
  "success": true,
  "id": "402880e749c4030e0149c6b401bd0015",
  "accountNumber": "A00000001",
  "paymentMethodId": null
}
2

Step 2: Create an Order with a Subscription

Use the Orders API to create a subscription on the account. This associates the customer with a product rate plan and starts billing.

curl -X POST https://rest.test.zuora.com/v1/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "existingAccountNumber": "A00000001",
    "orderDate": "2025-01-15",
    "subscriptions": [
      {
        "orderActions": [
          {
            "type": "CreateSubscription",
            "createSubscription": {
              "terms": {
                "initialTerm": {
                  "period": 12,
                  "periodType": "Month",
                  "termType": "TERMED"
                },
                "renewalSetting": "RENEW_WITH_SPECIFIC_TERM",
                "renewalTerms": [
                  {
                    "period": 12,
                    "periodType": "Month"
                  }
                ]
              },
              "subscribeToRatePlans": [
                {
                  "productRatePlanId": "402880e749c4030e0149c6b401bd0099"
                }
              ]
            }
          }
        ]
      }
    ]
  }'

Response

{
  "success": true,
  "orderNumber": "O-00000001",
  "accountNumber": "A00000001",
  "status": "Completed",
  "subscriptions": [
    {
      "subscriptionNumber": "S-00000001",
      "status": "Active"
    }
  ]
}
3

Step 3: Verify the Subscription

Retrieve the subscription to confirm it was created correctly.

curl -X GET "https://rest.test.zuora.com/v1/subscriptions/S-00000001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

What’s Next

Now that you have an active subscription, you can:

  • Generate an invoice — Run a Bill Run to create invoices for the subscription period.
  • Process a payment — Use the Payments API to collect payment against the invoice.
  • Amend the subscription — Use Order Actions to upgrade, downgrade, or cancel the subscription.
  • Query data — Use Object Queries to retrieve subscription and billing data programmatically.

Always test in a Sandbox environment before running orders in production. Use the Preview Order endpoint to simulate the billing impact of an order without committing it.