Skip to content
Tutorials
/
API tutorials
/
/
Create subscriptions

Create a subscription

This section showcases the cURL examples for creating a subscription in different scenarios by calling the Create an order operation. The corresponding Zuora client libraries code examples are also provided.

Note that we're using the US API Sandbox Cloud 2 environment https://rest.apisandbox.zuora.com as the base URL. You need to substitiute it with your own environment URL.

Create a subscription without charge overrides

Create an order subscribing to a Monthly recurring plan (id=8ad08ea194da7ba00194df52a41f04c6) for an existing account (accountNumber = A00000001). The order date is today - Feb 1, 2025, the same as the billing target date.

The invoice is generated immediately along with the order creation.

cURL
curl --location 'https://rest.apisandbox.zuora.com/v1/orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $token' \
--data '{
    "orderDate": "2025-02-01",
    "processingOptions": {
        "runBilling": true,
        "billingOptions": {
            "targetDate": "2025-02-01"
        }
    },
    "existingAccountNumber": "A00000001",
    "subscriptions": [
        {
            "orderActions": [
                {
                    "type": "CreateSubscription",
                    "createSubscription": {
                       "terms": {
                         "initialTerm": {
                           "startDate": "2025-02-01",
                            "period": 12,
                            "periodType": "Month",
                            "termType": "TERMED"
                           },
                           "renewalSetting": "RENEW_WITH_SPECIFIC_TERM",
                           "renewalTerms": [
                            {
                                "period": 12,
                                "periodType": "Month"
                            }
                        ]
                        },
                        "subscribeToRatePlans":[
                            {
                            "productRatePlanId": "8ad08ea194da7ba00194df52a41f04c6"
                            }
                        ]
                    }
                }
            ]
        }
    ]
}'

Create a subscription with tiered charges

Create an order with a 12-month subscription of tiered charges for an existing account (A00000135). The order date is today - Feb 1, 2025.

TierUnitPricePrice format
11-5$100Per Unit
26 and above$80Per Unit

The subscribed quantity is 15.

The invoice is generated immediately along with the order creation.

cURL
curl -i -X POST "https://rest.apisandbox.zuora.com/v1/orders" \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Example tiered pricing order",
    "existingAccountNumber": "A00000135",
    "orderDate": "2025-02-01",
    "processingOptions": {
        "billingOptions": {
            "targetDate": "2025-02-01"
        },
        "collectPayment": false,
        "runBilling": true
    },
    "subscriptions": [
        {
            "orderActions": [
                {
                    "createSubscription": {
                        "invoiceSeparately": true,
                        "subscribeToRatePlans": [
                            {
                                "chargeOverrides": [
                                    {
                                        "productRatePlanChargeId": "f94f166281e952195f35223e4b2f002f",
                                        "pricing": {
                                            "recurringTiered": {
                                                "quantity": 15,
                                                "tiers": [
                                                    {
                                                        "tier": 1,
                                                        "startingUnit": 1,
                                                        "endingUnit": 5,
                                                        "price": 100.00,
                                                        "priceFormat": "PerUnit"
                                                        },
                                                    {
                                                        "tier": 2,
                                                        "startingUnit": 6,
                                                        "price": 80.00,
                                                        "priceFormat": "PerUnit"
                                                        }
                                                ]
                                            }
                                        }
                                    }
                                ],
                                "productRatePlanId": "f94fbebf61e952182765223a7a1d0000",
                                "uniqueToken": "Tiered Annual"
                            }
                        ],
                        "terms": {
                            "autoRenew": true,
                            "initialTerm": {
                                "period": 12,
                                "periodType": "Month",
                                "termType": "TERMED"
                            },
                            "renewalSetting": "RENEW_WITH_SPECIFIC_TERM",
                            "renewalTerms": [
                                {
                                    "period": 12,
                                    "periodType": "Month"
                                }
                            ]
                        }
                    },
                    "triggerDates": [
                        {
                            "name": "ContractEffective",
                            "triggerDate": "2025-02-01"
                        }
                    ],
                    "type": "CreateSubscription"
                }
            ]
        }
    ]
}'

Create a subscription with percentage discount override

Create an order with a 12-month subscription of a 30%-off discount charge while creating a new account. The order date is today - Feb 1, 2025.

The new account information is as follows:

  • Name: Amy Lawrence account
  • Bill cycle day: 1
  • Currency of the account: USD
  • Bill-to-contact:
    • Address: 1051 E Hillsdale, Foster City, CA, United States, 94404
    • Name: Bella Lawrence
    • work email: myorder@example.com
  • Create a credit card as the payment method:
    • Card number: 4111111111111111
    • Card type: Visa
    • Card expiration date: Dec 2025
    • Security code: 111
    • Cardholder name: Bella Lawrence
    • Cardholder address: 1051 E Hillsdale, Foster City, CA, United States, 94404
    • Email: myorder@example.com

The invoice is generated immediately along with the order creation.

cURL
curl -i -X POST https://rest.apisandbox.zuora.com/v1/orders \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d '
{
  "orderDate": "2025-02-01",
  "newAccount": {
    "name": "Amy Lawrence account",
    "billCycleDay": 1,
    "currency": "USD",
    "paymentTerm": "Due Upon Receipt",
    "billToContact": {
      "address1": "1051 E Hillsdale",
      "city": "Foster City",
      "country": "United States",
      "firstName": "Bella",
      "lastName": "Lawrence",
      "postalCode": "94404",
      "state": "CA",
      "workEmail": "myorder@example.com"
    },
    "creditCard": {
      "cardType": "Visa",
      "cardNumber": "4111111111111111",
      "expirationMonth": 12,
      "expirationYear": 2035,
      "securityCode": "111",
      "cardHolderInfo": {
        "cardHolderName": "Bella Lawrence",
        "addressLine1": "1051 E Hillsdale",
        "city": "Foster City",
        "state": "CA",
        "zipCode": "94404",
        "country": "United States",
        "email": "myorder@example.com"
      }
    }
  },
  "subscriptions": [
    {
      "orderActions": [
        {
          "type": "CreateSubscription",
          "triggerDates": [
            {
              "name": "ContractEffective",
              "triggerDate": "2025-02-01"
            },
            {
              "name": "ServiceActivation",
              "triggerDate": "2025-02-01"
            },
            {
              "name": "CustomerAcceptance",
              "triggerDate": "2025-02-01"
            }
          ],
          "createSubscription": {
            "terms": {
              "initialTerm": {
                "startDate": "2025-02-01",
                "period": 12,
                "periodType": "Month",
                "termType": "TERMED"
              },
              "renewalTerms": [
                {
                  "period": 12,
                  "periodType": "Month"
                }
              ],
              "renewalSetting": "RENEW_WITH_SPECIFIC_TERM",
              "autoRenew": true
            },
            "invoiceSeparately": true,
            "subscribeToRatePlans": [
              {
                "productRatePlanId": "f94fbebf61e952182765223a7a1d0000",
                "chargeOverrides": [
                    {
                        "productRatePlanChargeId": "f94f16628be952195f3522404efb0010",
                        "description": "Overriding the default 20% discount to 30%",
                        "pricing": {
                          "discount":
                            {
                              "discountPercentage": 30
                            }
                        }
                    }
                ]
              }
            ]
          }
        }
      ]
    }
  ],
  "processingOptions": {
    "runBilling": true,
    "billingOptions": {
      "documentDate": "2025-02-01",
      "targetDate": "2025-02-01"
    }
  }
}
'

Create a subscription for a product rate plan with two charges, one charge starting on a future date

Create an order for a new subscription on an existing account (A00000135) that includes a product rate plan (id = 8ad08ae28adb8e2f018af22a5799226a) that has the following two charges. The order date is today - Feb 1, 2025.

  • A one-time charge (id = f94fbebf60e95218276522506ac30001 ) where the customer wishes to purchase 100 units.
  • A recurring charge (id = f94f166281e952195f35223e4b2f002f) for 20 seats that will automatically start billing 15 days after the one time charge.

The invoice is generated immediately along with the order creation.

cURL
curl -i  -X POST https://rest.apisandbox.zuora.com/v1/orders \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d '
    {
    "orderDate": "2025-02-01",
    "description": "One Time Volume charge will be billed immediately, but recurring charge delayed until specified date, 15 days later. The specific date override changes the default -bill on the Contract Effective Date behavior - defined on the charge in the product catalog. ",
    "existingAccountNumber": "A00000135",
    "subscriptions": [
        {
        "orderActions": [
            {
            "type": "CreateSubscription",
            "createSubscription": {
                "terms": {
                "initialTerm": {
                    "period": 12,
                    "periodType": "Month",
                    "termType": "TERMED"
                },
                "renewalTerms": [
                    {
                    "period": 12,
                    "periodType": "Month"
                    }
                ],
                "renewalSetting": "RENEW_WITH_SPECIFIC_TERM",
                "autoRenew": true
                },
                "invoiceSeparately": true,
                "subscribeToRatePlans": [
                {
                    "productRatePlanId": "8ad08ae28adb8e2f018af22a5799226a",
                    "chargeOverrides": [
                    {
                        "productRatePlanChargeId": "f94fbebf60e95218276522506ac30001",
                        "pricing": {
                        "oneTimeVolume": {
                            "quantity" : 100
                        }
                        }
                    }
                    ]
                },
                {
                    "productRatePlanId": "8ad08ae28adb8e2f018af22a5799226a",
                    "chargeOverrides": [
                    {
                        "productRatePlanChargeId": "f94f166281e952195f35223e4b2f002f",
                        "description": "Overriding the charge specified default behavior of billing on contract effective date with this specified date",
                        "startDate": {
                        "specificTriggerDate": "2025-02-15",
                        "triggerEvent": "SpecificDate"
                        },
                        "pricing": {
                          "recurringTiered": {
                            "quantity" : 20
                          }
                        }
                    }
                    ]
                }
                ]
            },
            "triggerDates": [
                {
                "name": "ContractEffective",
                "triggerDate": "2025-02-01"
                }
            ]
            }
        ]
        }
        ],
        "processingOptions": {
            "runBilling": true
        }
    }
    '

Create a future-dated swap order

Create an order with a future-dated swap action while creating a new account. The order date is today - Feb 1, 2025.

The new account information is as follows:

  • Name: Amy Lawrence account
  • Bill cycle day: 1
  • Currency of the account: USD
  • Bill-to-contact:
    • Address: 1051 E Hillsdale, Foster City, CA, United States, 94404
    • Name: Bella Lawrence
    • work email: myorder@example.com
  • Create a tokenized credit card as the payment method:
    • Token ID: 42342axdsa3243
    • Second token ID: 23423423mnsdsd

The three order actions are as follows:

  • On Feb 1, 2025, create a subscription for product rate plan A (id = e41259a14f7cecfa38893a4541890b01). The subscription term is 1 year.
  • On Feb 15, 2025, remove this product rate plan A.
  • On Feb 15, 2025, add a product rate plan B (id = 8ad08e1a8634dd1c018638acd24c4fcc) to this subscription.

The invoice is generated immediately along with the order creation.

cURL
curl -i  -X POST https://rest.apisandbox.zuora.com/v1/orders \
  -H "Authorization: Bearer $token" \
  -H "Content-Type: application/json" \
  -d '
    {
    "orderDate": "2025-02-01",
    "description": "Three order actions for a subscription in one order. Note externally generated token as payment method, token is often a proxy for a credit card stored in an external to Zuora, system. Example of using uniqueToken to ensure the right rate plan is removed even though you do not know the rate plan id when the order is submitted.",
    "newAccount":{
        "batch": "Batch49",
        "autoPay": false,
        "billCycleDay": "0",
        "currency":	"USD",
        "name": "Amy Lawrence account",
        "paymentMethod": {
        "type": "CreditCardReferenceTransaction",
        "tokenId": "42342axdsa3243",
        "secondTokenId": "23423423mnsdsd"
        },
        "billToContact":	{
        "firstName": "Amy",
        "lastName": "Lawrence",
        "postalCode": "94044",
        "country": "United States",
        "state": "California"
        }
    },
    "processingOptions": {
        "billingOptions": {
        "targetDate": "2025-02-01"
        },
        "collectPayment": false,
        "runBilling": true
    },
    "subscriptions": [
        {
        "orderActions": [
        {
            "createSubscription": {
                "subscribeToRatePlans": [
                    {
                        "productRatePlanId": "e41259a14f7cecfa38893a4541890b01",
                        "uniqueToken": "320984329048239042380423"
                    }
                    ],
                    "terms": {
                        "autoRenew": true ,
                        "initialTerm": {
                            "startDate": "2025-02-01",
                            "termType": "TERMED",
                            "period": "1",
                            "periodType": "Year"
                        },
                        "renewalSetting": "RENEW_WITH_SPECIFIC_TERM",
                        "renewalTerms": [{"period": "1", "periodType": "Year"}]
                    }
                },
                "triggerDates": [
                    {
                        "name": "ContractEffective",
                        "triggerDate": "2025-02-01"
                    },
                    {
                        "name": "ServiceActivation",
                        "triggerDate": "2025-02-01"
                    },
                    {
                        "name": "CustomerAcceptance",
                        "triggerDate": "2025-02-01"
                    }
                ],
                "type": "CreateSubscription"
            },
            {
                "removeProduct": {
                        "uniqueToken": "320984329048239042380423"
                    },
                "triggerDates": [
                    {
                        "name": "ContractEffective",
                        "triggerDate": "2025-02-15"
                    },
                    {
                        "name": "ServiceActivation",
                        "triggerDate": "2025-02-15"
                    },
                    {
                        "name": "CustomerAcceptance",
                        "triggerDate": "2025-02-15"
                    }
                ],
                "type": "RemoveProduct"
            },
            {
                "addProduct": {
                    "productRatePlanId": "8ad08e1a8634dd1c018638acd24c4fcc"
                },
                "triggerDates": [
                    {
                        "name": "ContractEffective",
                        "triggerDate": "2025-02-15"
                    },
                    {
                        "name": "ServiceActivation",
                        "triggerDate": "2025-02-15"
                    },
                    {
                        "name": "CustomerAcceptance",
                        "triggerDate": "2025-02-15"
                    }
                ],
                "type": "AddProduct"
            }
        ]
        }
    ]
    }'
Previous page
Next page