> This page is for Developers.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://zuora.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://zuora.ferndocs.com/_mcp/server.

# Recipe: Create a Subscription

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.

> **Info**
>
> 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](/docs/get-started/authentication))
* 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
```

### 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

```bash
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"
  }'
```

#### Python

```python
import requests

account_payload = {
    "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 = client.request("POST", "/v1/accounts", json=account_payload)
account_data = response.json()
account_id = account_data["id"]
account_number = account_data["accountNumber"]

print(f"Created account: {account_number}")
```

#### TypeScript

```typescript
const accountPayload = {
  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",
};

const accountResponse = await fetch(
  "https://rest.test.zuora.com/v1/accounts",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(accountPayload),
  }
);

const account = await accountResponse.json();
console.log(`Created account: ${account.accountNumber}`);
```

#### Response

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

### 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

```bash
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"
                }
              ]
            }
          }
        ]
      }
    ]
  }'
```

#### Python

```python
order_payload = {
    "existingAccountNumber": account_number,
    "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 = client.request("POST", "/v1/orders", json=order_payload)
order_data = response.json()

print(f"Order number: {order_data['orderNumber']}")
print(f"Subscription: {order_data['subscriptions'][0]['subscriptionNumber']}")
```

#### TypeScript

```typescript
const orderPayload = {
  existingAccountNumber: account.accountNumber,
  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",
              },
            ],
          },
        },
      ],
    },
  ],
};

const orderResponse = await fetch(
  "https://rest.test.zuora.com/v1/orders",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(orderPayload),
  }
);

const order = await orderResponse.json();
console.log(`Order: ${order.orderNumber}`);
console.log(`Subscription: ${order.subscriptions[0].subscriptionNumber}`);
```

#### Response

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

### Step 3: Verify the Subscription

Retrieve the subscription to confirm it was created correctly.

#### cURL

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

#### Python

```python
response = client.request(
    "GET", f"/v1/subscriptions/{order_data['subscriptions'][0]['subscriptionNumber']}"
)
subscription = response.json()

print(f"Status: {subscription['status']}")
print(f"Term start: {subscription['termStartDate']}")
print(f"Term end: {subscription['termEndDate']}")
print(f"Rate plans: {len(subscription['ratePlans'])}")
```

#### TypeScript

```typescript
const subResponse = await fetch(
  `https://rest.test.zuora.com/v1/subscriptions/${order.subscriptions[0].subscriptionNumber}`,
  {
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
  }
);

const subscription = await subResponse.json();
console.log(`Status: ${subscription.status}`);
console.log(`Term: ${subscription.termStartDate} - ${subscription.termEndDate}`);
```

## What's Next

Now that you have an active subscription, you can:

* **Generate an invoice** -- Run a [Bill Run](/api-reference/bill-runs/bill-run) to create invoices for the subscription period.
* **Process a payment** -- Use the [Payments API](/api-reference/payments/payments) to collect payment against the invoice.
* **Amend the subscription** -- Use [Order Actions](/api-reference/orders-and-subscriptions/order-actions) to upgrade, downgrade, or cancel the subscription.
* **Query data** -- Use [Object Queries](/api-reference/object-query/object-queries) to retrieve subscription and billing data programmatically.

> **Info**
>
> Always test in a **Sandbox** environment before running orders in production. Use the [Preview Order](/api-reference/orders-and-subscriptions/orders) endpoint to simulate the billing impact of an order without committing it.