Knowledge Center

Knowledge Center > API > REST API > REST API Reference > Accounts > Create account

Create account

This REST API reference describes how to create a customer account with a credit-card payment method, a bill-to contact, and an optional sold-to contact. Request and response field descriptions and sample code are provided. Use this method to optionally create a subscription, invoice for that subscription, and collect payment through the default payment method. The transaction is atomic; if any part fails for any reason, the entire transaction is rolled back.

This API call is CORS Enabled, so you can use client-side Javascript to invoke the call. For more information, visit the Zuora CORS REST page.

Request

  • Production: POST https://api.zuora.com/rest/v1/accounts
  • API Sandbox: POST https://apisandbox-api.zuora.com/rest/v1/accounts

Request Header

zuora-version

optional

The minor version of the Zuora REST API. 

Set this parameter only if you use the collect or invoice field. See REST API Basics for more information on versioning.

Accept

optional

Optionally enter application/json. Only JSON is returned.

 

Request body

batch

optional

The alias name given to a batch. A string of 50 characters or less.

accountNumber

optional

A unique account number, up to 50 characters that do not begin with the default account number prefix.  If no account number is specified, one is generated.

name

required

Account name, up to 255 characters

currency

required

A currency as defined in Z-Billing Settings in the Zuora UI

notes

optional

A string of up to 65,535 characters

billCycleDay

conditional

The account's bill cycle day (BCD), when bill runs generate invoices for the account.  Specify any day of the month (1-31, where 31 = end-of-month), or 0 for auto-set.

  • Required if no subscription will be created. 
  • Optional if a subscription is created and defaults to the day-of-the-month of the subscription's contractEffectiveDate.

autoPay

optional

Specifies whether future payments are to be automatically billed when they are due. Possible values are: true, false.

crmId

optional

CRM account ID for the account, up to 100 characters

invoiceTemplateId

optional

Invoice template ID, configured in Z-Billing Settings

communicationProfileId

optional

ID of a communication profile, as described in the Knowledge Center

paymentGateway

optional

The name of the payment gateway instance. If null or left unassigned, the Account will use the Default Gateway.

paymentTerm

optional

Payment terms for this account. Possible values are "Due Upon Receipt", "Net 30", "Net 60", "Net 90".

cf_txtn__c

optional

One or more optional custom fields

cf_pkn__c

optional

One or more optional custom fields

billToContact 

required

Container for bill-to contact information for this account. If you do not provide a sold-to contact, the bill-to contact is copied to sold-to contact. Once the sold-to contact is created, changes to billToContact will not affect soldToContact and vice versa.

address1

optional

First address line, 255 characters or less

address2

optional

Second address line, 255 characters or less

city

optional

City, 40 characters or less

country

conditional

Country; must be a valid country name or abbreviation. If using Z-Tax, must specify a country in the sold-to contact to calculate tax. A bill-to contact may be used if no sold-to contact is provided.

county

optional

County; 32 characters or less. May optionally be used by Z-Tax to calculate county tax.

fax

optional

Fax phone number, 40 characters or less

firstName

required

First name, 100 characters or less

homePhone

optional

Home phone number, 40 characters or less

lastName

required

Last name, 100 characters or less

mobilePhone

optional

Mobile phone number, 40 characters or less

nickname

optional

Nickname for this contact

otherPhone

optional

Other phone number, 40 characters or less

otherPhoneType

optional

Possible values are: Work, Mobile, Home, Other.

personalEmail

optional

Personal email address, 80 characters or less

zipCode

optional

Zip code, 20 characters or less

state

optional

State; must be a valid state or province name or 2-character abbreviation. If using Z-Tax, be aware that Z-Tax requires a state (in the US) or province (in Canada) in this field for the sold-to contact to calculate tax, and that a bill-to contact may be used if no sold-to contact is provided.

taxRegion

optional

If using Z-Tax, a region string as optionally defined in your tax rules. Not required.

workEmail

optional

Work email address, 80 characters or less

workPhone

optional

Work phone number, 40 characters or less

cf_txtn__c

optional

One or more optional custom fields

cf_pkn__c

optional

One or more optional custom fields

soldToContact

optional

Container for optional sold-to contact; uses the same field structure as the bill-to contact (above). If a sold-to contact is not specified, one is created from the bill-to contact. Once created, these are two separate data entities, and future changes to one do not affect the other.

hpmCreditCardPaymentMethodId

conditional

The ID of the HPM credit card payment method associated with this account. You must provide either this field or the creditCard structure, but not both.

Non-credit card payment methods are not supported.

creditCard 

conditional

Container for information on a credit card to associate with this account. You must provide either this structure or the hpmCreditCardPaymentMethodId field, but not both.

cardType

required

Possible values are: Visa, MasterCard, AmericanExpress, Discover.

cardNumber

required

Card number, up to 16 characters.  Once created, this field can't be updated or queried, and is only available in masked format (e.g., XXXX-XXXX-XXXX-1234).

expirationMonth

required

Two-digit expiration month (01-12)

expirationYear

required

Four-digit expiration year

securityCode

optional

The CVV or CVV2 security code of the card. To ensure PCI compliance, this value isn't stored and can't be queried. For more information, see How do I control what information Zuora sends over to the Payment Gateway?

cardHolderInfo

required

Container for cardholder information. If provided, Zuora will only use this information for this card.  If not provided, Zuora will use the account's existing bill-to contact information for this card.

cardHolderName

required

The card holder's full name as it appears on the card, e.g., "John J Smith", 50 characters or less

addressLine1

required

First address line, 255 characters or less

addressLine2

optional

Second address line, 255 characters or less

city

required

City, 40 characters or less

state

required

State; must be a valid state name or 2-character abbreviation.

zipCode

required

Zip code, 20 characters or less

country

required

Country; must be a valid country name or abbreviation.

phone

optional

Phone number, 40 characters or less

email

optional

Card holder's email address, 80 characters or less

subscription conditional

Container for subscription information, used if creating a subscription for the new account at the time of account creation.

subscriptionNumber

optional

Subscription Number. The value can be up to 1000 characters.

If you do not specify a subscription number when creating a subscription for the new account, Zuora will generate a subscription number automatically.

If the account is created successfully, the subscription number is returned in the subscriptionNumber response field.

invoiceOwnerAccountKey

optional

Invoice owner account number or ID

This feature is in Limited Availability. If you wish to have access to the feature, submit a request at Zuora Global Support

termType

required

Possible values are: TERMED, EVERGREEN. See Subscriptions for more information.

contractEffectiveDate

required

Effective contract date for this subscription, as yyyy-mm-dd

serviceActivationDate

optional

The date on which the services or products within a subscription have been activated and access has been provided to the customer, as yyyy-mm-dd.

Default value is dependent on the value of other fields. See Notes section below for more details.

customerAcceptanceDate

optional

The date on which the services or products within a subscription have been accepted by the customer, as yyyy-mm-dd.

Default value is dependent on the value of other fields. See Notes section below for more details.

termStartDate

optional

The date on which the subscription term begins, as yyyy-mm-dd. If this is a renewal subscription, this date is different from the subscription start date.

initialTerm

optional

Duration of the initial subscription term in whole months.  Default is 0. 

autoRenew

optional

If true, auto-renew is enabled. Default is false.

renewalTerm

optional

Duration of the renewal term in whole months. Default is 0.

cf_txtn__c

optional

One or more optional custom fields.

cf_pkn__c

optional

One or more optional custom fields.

subscribeToRatePlans

optional

Container for one or more rate plans for this subscription.

productRatePlanId

required

ID of a product rate plan for this subscription.

chargeOverrides

optional

This optional container is used to override the quantity of one or more product rate plan charges for this subscription. Used for per-unit, volume, and tiered pricing models only.

productRatePlanChargeId

required

ID of a product rate-plan charge for this subscription

quantity

required

Number of units
cf_txtn__c One or more rate plan charge custom fields
cf_pkn__c One or more rate plan charge custom fields
cf_txtn__c One or more rate plan custom fields
cf_pkn__c One or more rate plan custom fields

invoiceCollect

optional

This field has been replaced by the invoice field and the collect field. invoiceCollect is available only for backward compatibility.

If true (default), and a subscription is created, an invoice is generated at account creation time and payment is immediately collected using the account's default payment method.

This field is in Zuora REST API version control. Supported minor versions are 186.0, 187.0, 188.0, and 189.0. See Zuora REST API Versions for more information.

invoice

optional

Creates an invoice for a subscription. The invoice generated in this operation is only for this subscription, not for the entire customer account.

If the value is true, an invoice is created. If the value is false, no action is taken.
The default value is true

This field is in Zuora REST API version control. Supported minor versions are 196.0 or later. To use this field in the method, you must set the zuora-version parameter to the minor version number in the request header. See Zuora REST API Versions for more information.

collect

optional

Collects an automatic payment for a subscription. The collection generated in this operation is only for this subscription, not for the entire customer account.
If the value is true, the automatic payment is collected. If the value is false, no action is taken.
The default value is true.
Prerequisite: invoice must be true

This field is in Zuora REST API version control. Supported minor versions are 196.0 or later. To use this field in the method, you must set the zuora-version parameter to the minor version number in the request header. See Zuora REST API Versions for more information.

invoiceSeparately

optional

Separates a single subscription from other subscriptions and invoices the charge independently. 
If the value is true, the subscription is billed separately from other subscriptions. If the value is false, the subscription is included with other subscriptions in the account invoice.
The default value is false.
Prerequisite: The default subscription setting Enable Subscriptions to be Invoiced Separately must be set to Yes.

applyCreditBalance

optional

Applies a credit balance to an invoice.
If the value is true, the credit balance is applied to the invoice. If the value is false, no action is taken.
Prerequisite: invoice must be true

Note: If you are using the field invoiceCollect rather than the field invoice, the invoiceCollect value must be true.

To view the credit balance adjustment, retrieve the details of the invoice using the Get Invoices method.

invoiceTargetDate

optional

If invoiceCollect is true, the target date for the invoice (that is, the date through which charges should be calculated). In yyyy-mm-dd format; defaults to the current date.

taxInfo

optional

Container for tax exempt information, used to establish the tax exempt status of a customer account.

companyCode

optional

Unique code that identifies a company account in Avalara. Use this field to calculate taxes based on origin and sold-to addresses in Avalara.

This feature is in Limited Availability. If you wish to have access to the feature, submit a request at Zuora Global Support

exemptCertificateId

optional

ID of the customer tax exemption certificate. Requires Z-Tax.

exemptCertificateType

optional

Type of tax exemption certificate that the customer holds. Requires Z-Tax.

exemptDescription

optional

Description of the tax exemption certificate that the customer holds. Requires Z-Tax.

exemptEffectiveDate

optional

Date when the customer tax exemption starts. Requires Z-Tax.

Format: yyyy-mm-dd. Defaults to the current date.

exemptExpirationDate

optional

Date when the customer tax exemption expires. Requires Z-Tax.

Format: yyyy-mm-dd. Defaults to the current date.

exemptIssuingJurisdiction

optional

Jurisdiction in which the customer tax exemption certificate was issued.

exemptStatus

conditional

 

Status of the account tax exemption. Requires Z-Tax.

Required if you use Z-Tax. This field is unavailable if Z-Tax is not used.

Values: Yes, No, pendingVerification

VATId

optional

EU Value Added Tax ID.

This feature is in Limited Availability. If you wish to have access to the feature, submit a request at Zuora Global Support

Response

success

Contains true if successful, otherwise false.

processId

Internal process ID to assist Zuora support. Only returned if success is false.

reasons

Information on one or more reasons for the result. Only returned if success is false.

code

Eight-digit numeric error code

message

Description of the error

accountId

Auto-generated account ID

accountNumber

Account number

paymentMethodId

ID of the payment method that was set up at account creation, which automatically becomes the default payment method for this account.

subscriptionId

ID of the subscription that was set up at account creation, if applicable

subscriptionNumber

Number of the subscription that was set up at account creation, if applicable

invoiceId

ID of the invoice generated at account creation, if applicable

paymentId

ID of the payment collected on the invoice generated at account creation, if applicable

paidAmount

Amount collected on the invoice generated at account creation, if applicable

contractedMrr

Contracted monthly recurring revenue of the subscription

totalContractedValue

Total contracted value of the subscription

companyCode

Unique code that identifies a company account in Avalara.

exemptCertificateId

ID of the customer tax exemption certificate.

exemptCertificateType

Type of tax exemption certificate that the customer holds. 

exemptDescription

Description of the tax exemption certificate that the customer holds.

exemptEffectiveDate

Date when the customer tax exemption starts.

exemptExpirationDate

Date when the customer tax exemption expires.

exemptIssuingJurisdiction

Jurisdiction in which the customer tax exemption certificate was issued.

exemptStatus

Status of the account tax exemption.

VATId

EU Value Added Tax ID.

Notes

  1. The account is created in active status.  
  2. The request must provide either a creditCard structure or the hpmCreditCardPaymentMethodId field (but not both). The one provided becomes the default payment method for this account. If the credit card information is declined or can't be verified, then the account is not created.
  3. Customer accounts created with this call are automatically be set to Auto Pay.
  4. If either the workEmail or personalEmail are specified, then the account's email delivery preference is automatically set to true. (In that case, emails go to the workEmail address, if it exists, or else the personalEmail.) If neither field is specified, the email delivery preference is automatically set to false.

Defaults for customerAcceptanceDate and serviceActivationDate

Default values for customerAcceptanceDate and serviceActivationDate are set as follows:

  serviceActivationDate
 (SA) specified

serviceActivationDate
(SA) NOT specified

customerAcceptanceDate (CA)

specified

SA uses value in the request call

CA uses value in the request call

CA uses value in the request call

SA uses CE as default

customerAcceptanceDate (CA)

NOT specified

SA uses value in the request call

CA uses SA as default

SA and CA use CE as default
 

Examples

The following JSON and CURL examples show how to create a subscription for an existing customer account. Some fields in the REST methods are supported as of Zuora REST API minor versions. The fields you can specify depends on the REST API minor version you use.

JSON Examples (REST API Minor Version 196.0 and later)

In API minor version 196.0 and later, the invoicecollect field is replaced by the invoice and collect fields. To use the collect and invoice fields,  you must set the zuora-version parameter to the minor version number in the request header. 

HTTP/JSON request:

POST https://api.zuora.com/rest/v1/accounts

JSON request:

{
  "name": "Zuora Test Account",
  "currency": "USD",
  "notes": "This account is for demo purposes.",
  "billCycleDay": 0,
  "autoPay": false, 
  "paymentTerm": "Due Upon Receipt",
  "billToContact": {
    "address1": "1051 E Hillsdale Blvd",
    "city": "Foster City",
    "country": "United States",
    "firstName": "John",
    "lastName": "Smith",
    "zipCode": "94404",
    "state": "CA",
    "workEmail": "john.smith@test.com"
  },
  "hpmCreditCardPaymentMethodId": "2c92c0f93cf64d94013cfe2d20db61a7",
  "subscription": {
    "termType": "TERMED",
    "initialTerm": 12,
    "renewalTerm": 12,
    "autoRenew": true,
    "notes": "This is a trial subscription for POST account demo.",
    "subscribeToRatePlans": [
      {
        "productRatePlanId": "2c92c0f94ac8307f014ae5d3d1d469e2",
        "chargeOverrides": [
          {
              "productRatePlanChargeId": "2c92c0f94ac8307f014ae5d4a5156b28",
              "price": 1000
          },
          {
              "productRatePlanChargeId": "2c92c0f94ac8307f014ae5dbe2947851",
              "price": 1000
          }
        ]
      },
      {
        "productRatePlanId": "2c92c0f93cf64d94013d027681560341",
        "chargeOverrides": [
          {
            "productRatePlanChargeId": "2c92c0f83cf64298013d027725a67b7b",
            "price": 1000
          }
        ]
      }
    ],
    "contractEffectiveDate": "2016-01-01"
  },
  "invoice": true,
  "collect": false
}

JSON response:

{ 
"success": true, "accountId": "402892c74c9193cd014c96bbe7c101f9", 
"accountNumber": "A00000004", 
"paymentMethodId": "402892c74c9193cd014c96bbe7d901fd" 
}

JSON Examples (REST API Minor Version 189.0 and earlier)

HTTP/JSON request:

POST https://api.zuora.com/rest/v1/accounts

JSON request:

{
    "creditCard": {
        "cardType": "Visa",
        "expirationMonth": 2,
        "securityCode": "111",
        "cardNumber": "4111111111111111",
        "expirationYear": 2016
    },
    "invoiceTargetDate": "2014-12-31",
    "name": "Alvin",
    "billCycleDay": "15",
    "soldToContact": {
        "country": "USA",
        "lastName": "Doe",
        "workEmail": "john.doe@zoura.com",
        "address1": "address1",
        "address2": "address2",
        "firstName": "John",
        "state": "California",
        "city": "San Francisco",
        "mobilePhone": "14156789012"
    },
    "billToContact": {
        "country": "USA",
        "lastName": "Doe",
        "workEmail": "jane.doe@zoura.com",
        "address1": "address1",
        "address2": "address2",
        "state": "California",
        "firstName": "Jane",
        "city": "San Francisco",
        "mobilePhone": "14156789012"
    },
    "invoiceCollect": false,
    "notes": "Soho Networks",
    "paymentTerm": "Net 30",
    "currency": "USD",
    "paymentGateway": "TestGateway"
}

JSON response:

{ 
"success": true, "accountId": "402892c74c9193cd014c96bbe7c101f9", 
"accountNumber": "A00000004", 
"paymentMethodId": "402892c74c9193cd014c96bbe7d901fd" 
}

CURL Example 1

##
## create an account without subscription
##
echo
echo "=============Creating An Account ==========="
echo
curl -i -k -H "apiAccessKeyId:$USER_NAME" -H "apiSecretAccessKey:$PASSWORD" -H "Content-Type:application/json" -H "Accept:application/json" -d '
{
    "name": "CRestTestingAccount",
    "currency": "USD",
    "notes": "this account is for crest account creation demo",
    "billCycleDay": 1,
    "paymentTerm": "Due Upon Receipt",
    "billToContact": {
        "address1": "3400 Bridge Pkwy",
        "address2": "#000",
        "city": "Redwood City",
        "country": "United States",
        "county": "San Mateo",
        "fax": "+1(123)4567890",
        "firstName": "Leo",
        "homePhone": "+1(123)4567890",
        "lastName": "Liu",
        "mobilePhone": "+1(123)4567890",
        "nickname": "LW",
        "otherPhone": "+1(123)4567890",
        "otherPhoneType": "Other",
        "personalEmail": "leo@test.com",
        "zipCode": "94000",
        "state": "CA",
        "taxRegion": "CA",
        "workEmail": "leo@test.com",
        "workPhone": "+1(123)4567890"
    },
    "soldToContact": {
        "address1": "3400 Bridge Pkwy",
        "address2": "#000",
        "city": "Redwood City",
        "country": "United States",
        "county": "San Mateo",
        "fax": "+1(123)4567890",
        "firstName": "J",
        "homePhone": "+1(123)4567890",
        "lastName": "C",
        "mobilePhone": "+1(123)4567890",
        "nickname": "J",
        "otherPhone": "+1(123)4567890",
        "otherPhoneType": "Other",
        "personalEmail": "j.c@test.com",
        "zipCode": "94000",
        "state": "CA",
        "taxRegion": "CA",
        "workEmail": "j.c@test.com",
        "workPhone": "+1(123)4567890"
    },
    "creditCard": {
        "cardType": "Visa",
        "cardNumber": "4111111111111111",
        "expirationMonth": 12,
        "expirationYear": 2020,
        "securityCode": null,
        "cardHolderInfo": {
            "cardHolderName": "Leo",
            "addressLine1": "3400 Bridge Pkwy",
            "addressLine2": "#000",
            "city": null,
            "state": null,
            "zipCode": "94000",
            "country": "United States",
            "phone": "+1(123)4567890",
            "email": "w.l@test.com"
        }
    }
}
' -X POST $BASE_URL/v1/accounts

JSON response:

{
  "paymentMethodId": "2c92c8f83dcbd8b1013dcce096b0000b",
  "paymentId": "2c92c8f83dcbd8b1013dcce09f420032",
  "paidAmount": 599.55,
  "subscriptionNumber": "A-S00001083",
  "subscriptionId": "2c92c8f83dcbd8b1013dcce0983b0015",
  "accountId": "2c92c8f83dcbd8b1013dcce096790008",
  "success": true,
  "accountNumber": "A00030968",
  "invoiceId": "2c92c8f83dcbd8b1013dcce09d110025"
}

CURL Example 2

CURL request:

##
## create an account with subscription
##
echo
echo "============Account with subscription(Combo call) ==========="
echo
curl -i -k -H "apiAccessKeyId:$USER_NAME" -H "apiSecretAccessKey:$PASSWORD" -H "Content-Type:application/json" -H "Accept:application/json" -d '
{
  "name":"RestAccount",
  "currency":"USD",
  "notes":"XYZ Networks",
  "billCycleDay":15,
  "crmId":"",
  "autoPay":"false",
  "paymentTerm":"Net 30",
  "tnt__c":"xyz",
  "pk__c":"1",
  "billToContact":{
    "address1":"address1",
    "address2":"address2",
    "city":"Beijing",
    "country":"China",
    "county":"",
    "fax":"",
    "firstName":"Leo",
    "homePhone":"",
    "lastName":"Liu",
    "mobilePhone":"15551238755",
    "nickname":"",
    "otherPhone":"",
    "personalEmail":"",
    "zipCode":"",
    "state":"",
    "workEmail":"leo@test.com",
    "workPhone":""
  },
  "soldToContact":{
    "address1":"address1",
    "address2":"address2",
    "city":"Beijing",
    "country":"China",
    "county":"",
    "fax":"",
    "firstName":"Leo",
    "homePhone":"",
    "lastName":"Liu",
    "mobilePhone":"15551238755",
    "nickname":"",
    "otherPhone":"",
    "personalEmail":"",
    "zipCode":"",
    "state":"",
    "workEmail":"leo@test.com",
    "workPhone":""
  },
  "creditCard":{
    "cardType":"Visa",
    "cardNumber":"4111111111111111",
    "expirationMonth":10,
    "expirationYear":2016,
    "securityCode":"111"
  },
  "subscription":{
    "contractEffectiveDate": "2012-12-01",
    "termType":"TERMED",
    "initialTerm":12,
    "autoRenew":true,
    "renewalTerm":12,
    "notes":"test subscription",
    "subscribeToRatePlans":[
      {
        "productRatePlanId": "ff808081298c6e5401298c784faa0073",
        "chargeOverrides":[
          {"productRatePlanChargeId": "ff808081298c6e5401298c79727f0077", "quantity":10}
        ]
      }
    ]
  },
  "invoiceCollect": false,
  "invoiceTargetDate": "2013-01-01"
}
' -X POST $BASE_URL/v1/accounts

JSON response:

{
  "paymentMethodId": "2c92c8f83dcbd8b1013dcce096b0000b",
  "paymentId": "2c92c8f83dcbd8b1013dcce09f420032",
  "paidAmount": 599.55,
  "subscriptionNumber": "A-S00001083",
  "subscriptionId": "2c92c8f83dcbd8b1013dcce0983b0015",
  "accountId": "2c92c8f83dcbd8b1013dcce096790008",
  "success": true,
  "accountNumber": "A00030968",
  "invoiceId": "2c92c8f83dcbd8b1013dcce09d110025"
}
Last modified
16:43, 11 Sep 2016

Tags

Classifications

(not set)