# Sign up

This call performs many actions. You can use this operation to implement
 the standard requirements for signing up a customer, such as validating the
 uniqueness of an account and limiting the number of subscriptions per account.
 Also, you can use this operation to create a subscription, generate an invoice,
 and collect payment for a new or existing customer. 
 
 Note: You need to
 have the Orders
 or Orders Harmonization
 feature enabled to use this API. For a new customer, you can perform the
 following tasks in one call. Note that you can skip creating a payment meethod
 and still get the subscription and invoice successfully created.
 * Create an account
 * Create a payment method
 * Subscribe to a product in the product catalog and create a subscription
 * Generate an invoice
 * Collect payment

For an existing customer, you can use an account identification field of an
external system to specify the account. You can make make asynchronous requests
when using the "Sign up" operation.

This call supports a subset of the functionality of our Create an order call. 
We generally recommend using "Create an order" instead of this call because the Orders call has the following advantages: 
- Provides options for managing the entire subscription lifecycle from creation through to cancellation using different order actions. 
- Allows the creation or modifying of multiple subscriptions in a single order. 
- Allows a single order to combine both recurring subscription digital goods or services with order line items for physical goods.
- Orders are treated as atomic transactions. If any part fails, the entire order, subscription, and billing account creation are rolled back.

This call does have some unique abilities not supported by "Create an order". You should consider using this call when you need to:

- Use Account UPSERT functionality by specifying a custom external identifier.
- Limit the number of subscriptions on an account

There are no deprecation plans for this call and we will continue to support this call.

Endpoint: POST /v1/sign-up
Version: 2026-02-20
Security: bearerAuth

## Header parameters:

  - `Idempotency-Key` (string)
    Specify a unique idempotency key if you want to perform an idempotent POST or PATCH request. Do not use this header in other request types. 

With this header specified, the Zuora server can identify subsequent retries of the same request using this value, which prevents the same operation from being performed multiple times by accident.

  - `Accept-Encoding` (string)
    Include the Accept-Encoding: gzip header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response. 

If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a Content-Encoding header with the compression algorithm so that your client can decompress it.

  - `Content-Encoding` (string)
    Include the Content-Encoding: gzip header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.

  - `Zuora-Track-Id` (string)
    A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

  - `Zuora-Entity-Ids` (string)
    An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you should not set this header.

  - `Zuora-Org-Ids` (string)
    Comma separated IDs. If you have Zuora Multi-Org enabled, 
you can use this header to specify which orgs to perform the operation in. If you do not have Zuora Multi-Org enabled, you should not set this header.

The IDs must be a sub-set of the user's accessible orgs. If you specify an org that the user does not have access to, the operation fails. This header is important in Multi-Org (MO) setups because it defines the organization context under which the API should operate—mainly used for read access or data visibility filtering. If the header is not set, the operation is performed in scope of the user's accessible orgs.

  - `Accept` (string)
    Expressed as MIME types that the client is able to understand. Using content negotiation, the server then selects one of the proposals, uses it and informs the client of its choice with the Content-Type response header. The possible response MIME types are application/json-seq compatible with http://jsonlines.org/, and text/csv compatible with RFC 4180. application/json-seq is the default response MIME type. If the Accept header is not sepecified, or set /, the response body is returned in application/json-seq MIME type.

  - `Zuora-Version` (string)
    The minor API version.

For a list of available minor versions, see API upgrades.

## Request fields (application/json):

  - `accountData` (object)
    The information of the account that you are to create through the "Sign up" operation.

  - `accountData.accountNumber` (string)

  - `accountData.autoPay` (boolean)
    Specifies whether future payments are to be automatically billed when they are due. Possible values are true, false.

  - `accountData.batch` (string)
    Note: By default, you have 50 configurable account batches. To increase the limit to 200 batches, you must have the Performance Booster Elite package.

  - `accountData.billCycleDay` (integer, required)
    Day of the month that the account prefers billing periods to begin on. If set to 0, the bill cycle day will be set as "AutoSet".

  - `accountData.billToContact` (object, required)
    Contact details associated with an account.

  - `accountData.billToContact.address1` (string)
    First line of the contact's address. This is often a street address or a business name.

  - `accountData.billToContact.address2` (string)
    Second line of the contact's address.

  - `accountData.billToContact.city` (string)
    City of the contact's address.

  - `accountData.billToContact.contactDescription` (string)
    A description for the contact.

  - `accountData.billToContact.country` (string)
    Country; must be a valid country name or abbreviation. If using [Zuora Tax](https://knowledgecenter.zuora.com/Zuora_Billing/Taxes/A_Zuora_Tax), you must specify a country in the bill-to contact to calculate tax.

  - `accountData.billToContact.county` (string)
    County of the contact's address.

  - `accountData.billToContact.customFields` (object)
    Container for custom fields.

  - `accountData.billToContact.fax` (string)
    Fax number of the contact.

  - `accountData.billToContact.firstName` (string, required)
    First name of the contact.

  - `accountData.billToContact.homePhone` (string)
    Home phone number of the contact.

  - `accountData.billToContact.lastName` (string, required)

  - `accountData.billToContact.mobilePhone` (string)
    Mobile phone number of the contact.

  - `accountData.billToContact.nickname` (string)
    Nickname of the contact.

  - `accountData.billToContact.otherPhone` (string)
    Additional phone number of the contact. Use the otherPhoneType field to specify the type of phone number.

  - `accountData.billToContact.otherPhoneType` (string)
    Specifies the type of phone number in the otherPhone field.
    Enum: "Work", "Mobile", "Home", "Other"

  - `accountData.billToContact.personalEmail` (string)
    Personal email address of the contact.

  - `accountData.billToContact.postalCode` (string)
    ZIP code or other postal code of the contact's address.

  - `accountData.billToContact.state` (string)
    State or province of the contact's address.

  - `accountData.billToContact.taxRegion` (string)
    Region defined in your taxation rules. Only applicable if you use Zuora Tax.

  - `accountData.billToContact.workEmail` (string)
    Business email address of the contact.

  - `accountData.billToContact.workPhone` (string)
    Business phone number of the contact.

  - `accountData.communicationProfileId` (string)

  - `accountData.creditMemoTemplateId` (string)
    Note: This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see [Invoice Settlement Enablement and Checklist Guide](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/Invoice_Settlement_Migration_Checklist_and_Guide) for more information.

The unique ID of the credit memo template, configured in Billing Settings > Manage Billing Document Configuration through the Zuora UI. For example, 2c92c08a6246fdf101626b1b3fe0144b.

  - `accountData.crmId` (string)

  - `accountData.currency` (string, required)
    3 uppercase character currency code.

Note: Specify this field only for a new account to be created; do not specify this field to update an existing account.


For payment method authorization, if the paymentMethod > currencyCode field is specified, currencyCode is used. Otherwise, this currency field is used for payment method authorization. If no currency is specified for the account, the default currency of the account is then used.

  - `accountData.debitMemoTemplateId` (string)
    Note: This field is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement) enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see [Invoice Settlement Enablement and Checklist Guide](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/Invoice_Settlement_Migration_Checklist_and_Guide) for more information.

The unique ID of the debit memo template, configured in Billing Settings > Manage Billing Document Configuration through the Zuora UI. For example, 2c92c08d62470a8501626b19d24f19e2.

  - `accountData.invoiceTemplateId` (string)

  - `accountData.name` (string, required)

  - `accountData.notes` (string)

  - `accountData.organizationLabel` (string)
    The organization that this object belongs to.

Note: This field is available only when the Multi-Org feature is enabled.

  - `accountData.paymentMethod` (object)
    Container for custom fields of a payment method object.

  - `accountData.paymentMethod.type` (string, required)
    Type of payment method. The following types of the payment method are supported:
    Enum: "PayPalEC", "PayPalNativeEC", "PayPalAdaptive", "CreditCard", "CreditCardReferenceTransaction"

  - `accountData.paymentMethod.secondTokenId` (string)
    The second token id of CreditCardReferenceTransaction.

  - `accountData.paymentMethod.tokenId` (string)
    The token id of payment method, required field of CreditCardReferenceTransaction type.

  - `accountData.paymentMethod.BAID` (string)
    ID of a PayPal billing agreement, for example, I-1TJ3GAGG82Y9.

  - `accountData.paymentMethod.email` (string)
    Email address associated with the payment method. This field is only supported for PayPal payment methods and is required if you want to create any of the following PayPal payment methods:
  - PayPal Express Checkout payment method 
  - PayPal Adaptive payment method
  - PayPal Commerce Platform payment method

  - `accountData.paymentMethod.preapprovalKey` (string)
    The PayPal preapproval key.

  - `accountData.paymentMethod.cardHolderInfo` (object)
    Container for cardholder information. If provided, Zuora will
only use this information for this card. Otherwise, Zuora will use
the account''s existing bill-to contact information for this card.

  - `accountData.paymentMethod.cardHolderInfo.addressLine1` (string)
    First address line, 255 characters or less.

  - `accountData.paymentMethod.cardHolderInfo.addressLine2` (string)
    Second address line, 255 characters or less.

  - `accountData.paymentMethod.cardHolderInfo.cardHolderName` (string, required)
    The card holder's full name as it appears on the card, e.g., "John J Smith", 50 characters or less.

  - `accountData.paymentMethod.cardHolderInfo.city` (string)
    City, 40 characters or less.

  - `accountData.paymentMethod.cardHolderInfo.country` (string)
    Country, must be a valid country name or abbreviation.

  - `accountData.paymentMethod.cardHolderInfo.email` (string)
    Card holder's email address, 80 characters or less.

  - `accountData.paymentMethod.cardHolderInfo.phone` (string)
    Phone number, 40 characters or less.

  - `accountData.paymentMethod.cardHolderInfo.state` (string)
    State; must be a valid subregion (state or province) name or code. For more information, see View subregions of a specific country or region.

  - `accountData.paymentMethod.cardHolderInfo.zipCode` (string)
    Zip code, 20 characters or less.

  - `accountData.paymentMethod.cardNumber` (string)
    Credit card number.

  - `accountData.paymentMethod.cardType` (string)
    The type of the credit card.

Possible values include Visa, MasterCard, AmericanExpress, Discover, JCB, and Diners. For more information about credit card types supported by different payment gateways, see [Supported Payment Gateways](https://knowledgecenter.zuora.com/CB_Billing/M_Payment_Gateways/Supported_Payment_Gateways).

  - `accountData.paymentMethod.checkDuplicated` (boolean)

  - `accountData.paymentMethod.expirationMonth` (string)
    One or two digit expiration month (1-12) of the credit card.

  - `accountData.paymentMethod.expirationYear` (string)
    Four-digit expiration year of the credit card.

  - `accountData.paymentMethod.mitConsentAgreementRef` (string)
    Specifies your reference for the stored credential consent agreement that you have established with the customer. Only applicable if you set the mitProfileAction field.

  - `accountData.paymentMethod.mitConsentAgreementSrc` (string)
    Required if you set the mitProfileAction field. Specifies how the consent agreement has been established with the customer. The allowed value is External. If you do not specify the mitProfileAction field, Zuora will automatically create a stored credential profile for the payment method, with the default value External set to this field.
    Enum: "External"

  - `accountData.paymentMethod.mitNetworkTransactionId` (string)
    Specifies the ID of a network transaction. Only applicable if you set the mitProfileAction field to Persist.

  - `accountData.paymentMethod.mitProfileAction` (string)
    Specifies how Zuora creates and activates the stored credential profile. If you do not specify this field, Zuora will automatically create a stored credential profile for the payment method, with the default value Activate set to this field.
    Enum: "Activate", "Persist"

  - `accountData.paymentMethod.mitProfileAgreedOn` (string)
    The date on which the profile is agreed. The date format is yyyy-mm-dd.

  - `accountData.paymentMethod.mitProfileType` (string)
    Required if you set the mitProfileAction field. If you do not specify the mitProfileAction field, Zuora will automatically create a stored credential profile for the payment method, with the default value Recurring set to this field.
    Enum: "Recurring"

  - `accountData.paymentMethod.securityCode` (string)
    CVV or CVV2 security code of the credit card.

To ensure PCI compliance, this value is not stored and cannot be queried.

  - `accountData.paymentMethod.accountKey` (string)
    Internal ID of the customer account that will own the payment method.

  - `accountData.paymentMethod.authGateway` (string)
    Internal ID of the payment gateway that Zuora will use to authorize the payments that are made with the payment method.

If you do not set this field, Zuora will use one of the following payment gateways instead:

* The default payment gateway of the customer account that owns the payment method, if the accountKey field is set.
* The default payment gateway of your Zuora tenant, if the accountKey field is not set.

  - `accountData.paymentMethod.ipAddress` (string)
    The IPv4 or IPv6 information of the user when the payment method is created or updated. Some gateways use this field for fraud prevention. If this field is passed to Zuora, Zuora directly passes it to gateways. 

If the IP address length is beyond 45 characters, a validation error occurs.

  - `accountData.paymentMethod.makeDefault` (boolean)
    Specifies whether the payment method will be the default payment method of the customer account that owns the payment method. Only applicable if the accountKey field is set.

  - `accountData.paymentTerm` (string)

  - `accountData.purchaseOrderNumber` (string)
    The number of the purchase order associated with this account. Purchase order information generally comes from customers.

  - `accountData.sequenceSetId` (string,null)
    The ID of the billing document sequence set to assign to the customer account. 

The billing documents to generate for this account will adopt the prefix and starting document number configured in the sequence set.

  - `accountData.shipToContact` (object)
    Contact details associated with an account.

  - `accountData.soldToContact` (object)
    Contact details associated with an account.

  - `accountData.taxInfo` (object)
    Information about the tax exempt status of a customer account.

  - `accountData.taxInfo.VATId` (string)
    EU Value Added Tax ID.

Note: This feature is in Limited Availability. If you wish to have access to the feature, submit a request at [Zuora Global Support](https://support.zuora.com).

  - `accountData.taxInfo.companyCode` (string)
    Unique code that identifies a company account in Avalara. Use this field to calculate taxes based on origin and sold-to addresses in Avalara.

Note: This feature is in Limited Availability. If you wish to have access to the feature, submit a request at [Zuora Global Support](https://support.zuora.com).

  - `accountData.taxInfo.exemptCertificateId` (string)
    ID of the customer tax exemption certificate. Applicable if you use Zuora Tax or Connect tax engines.

  - `accountData.taxInfo.exemptCertificateType` (string)
    Type of tax exemption certificate that the customer holds. Applicable if you use Zuora Tax or Connect tax engines.

  - `accountData.taxInfo.exemptDescription` (string)
    Description of the tax exemption certificate that the customer holds. Applicable if you use Zuora Tax or Connect tax engines.

  - `accountData.taxInfo.exemptEffectiveDate` (string)
    Date when the customer tax exemption starts, in YYYY-MM-DD format. Applicable if you use Zuora Tax or Connect tax engines.

  - `accountData.taxInfo.exemptExpirationDate` (string)
    Date when the customer tax exemption expires, in YYYY-MM-DD format. Applicable if you use Zuora Tax or Connect tax engines.

  - `accountData.taxInfo.exemptIssuingJurisdiction` (string)
    Jurisdiction in which the customer tax exemption certificate was issued.

  - `accountData.taxInfo.exemptStatus` (string)
    Status of the account tax exemption. Applicable if you use Zuora Tax or Connect tax engines. Required if you use Zuora Tax.
    Enum: "No", "Yes", "PendingVerification"

  - `accountIdentifierField` (string)
    Specify the name of the field that holds external account id
    Example: "CustomerUserId__c"

  - `options` (object)
    Invoice or Payment.

  - `options.billingTargetDate` (string)
    Date through which to calculate charges if an invoice is generated. See [What is a Target Date?](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/G_Bill_Runs/Creating_Bill_Runs#What_is_a_Target_Date.3F).

  - `options.collectPayment` (boolean)
    Indicates if the current request needs to collect payments. This value can not be 'true' when 'runBilling' flag is 'false'.

  - `options.maxSubscriptionsPerAccount` (number)

  - `options.runBilling` (boolean)
    Indicates if the current request needs to generate an invoice. The invoice will be generated against all subscriptions included in this order.

  - `paymentData` (object)

  - `paymentData.authTransactionId` (string)
    The authorization transaction ID from the payment gateway.

  - `paymentData.authorizedAmount` (number)
    The amount that is authorized before this API call. Only used for the Delay Capture function.

  - `paymentData.authorizedCurrency` (string)
    The authorization of currency code that occurs before this API call. We will verify whether it is same as the account's currency.

  - `subscriptionData` (object)

  - `subscriptionData.invoiceSeparately` (boolean)
    Specifies whether the subscription appears on a separate invoice when Zuora generates invoices.

  - `subscriptionData.notes` (string)
    Notes about the subscription. These notes are only visible to Zuora users.

  - `subscriptionData.ratePlans` (array)

  - `subscriptionData.ratePlans.productRatePlanId` (string)
    Internal identifier of the product rate plan that the rate plan is based on.

  - `subscriptionData.startDate` (string)

  - `subscriptionData.subscriptionNumber` (string)
    Subscription number of the subscription to create, for example, A-S00000001.

If you do not set this field, Zuora will generate a subscription number.

  - `subscriptionData.terms` (object)
    Container for the terms and renewal settings of the subscription.

  - `subscriptionData.terms.autoRenew` (boolean)
    Specifies whether the subscription automatically renews at the end of the each term. Only applicable if the type of the first term is TERMED.

  - `subscriptionData.terms.initialTerm` (object, required)
    Information about the first term of the subscription.

  - `subscriptionData.terms.initialTerm.period` (integer)
    Duration of the first term in months, years, days, or weeks, depending on the value of the periodType field. Only applicable if the value of the termType field is TERMED.

  - `subscriptionData.terms.initialTerm.periodType` (string)
    Unit of time that the first term is measured in. Only applicable if the value of the termType field is TERMED.
    Enum: "Month", "Year", "Day", "Week"

  - `subscriptionData.terms.initialTerm.startDate` (string)
    Start date of the first term, in YYYY-MM-DD format.

  - `subscriptionData.terms.initialTerm.termType` (string, required)
    Type of the first term. If the value of this field is TERMED, the first term has a predefined duration based on the value of the period field. If the value of this field is EVERGREEN, the first term does not have a predefined duration.
    Enum: "TERMED", "EVERGREEN"

  - `subscriptionData.terms.renewalSetting` (string)
    Specifies the type of the terms that follow the first term if the subscription is renewed. Only applicable if the type of the first term is TERMED.

* RENEW_WITH_SPECIFIC_TERM - Each renewal term has a predefined duration. The first entry in renewalTerms specifies the duration of the second term of the subscription, the second entry in renewalTerms specifies the duration of the third term of the subscription, and so on. The last entry in renewalTerms specifies the ultimate duration of each renewal term.
* RENEW_TO_EVERGREEN - The second term of the subscription does not have a predefined duration.
    Enum: "RENEW_WITH_SPECIFIC_TERM", "RENEW_TO_EVERGREEN"

  - `subscriptionData.terms.renewalTerms` (object)

  - `subscriptionData.terms.renewalTerms.period` (integer)
    Duration of the renewal term in months, years, days, or weeks, depending on the value of the periodType field.

  - `subscriptionData.terms.renewalTerms.periodType` (string)
    Unit of time that the renewal term is measured in.
    Enum: "Month", "Year", "Day", "Week"

## Response 200 fields (application/json):

  - `accountId` (string)
    The account id for the order.

  - `accountNumber` (string)
    The account number for the order.

  - `creditMemoId` (string)
    An array of the credit memo id generated in this order request. The credit memo is only available if you have the Invoice Settlement feature enabled.

  - `creditMemoNumber` (string)
    An array of the credit memo numbers generated in this order request. The credit memo is only available if you have the Invoice Settlement feature enabled.

  - `invoiceId` (string)
    The invoice id generated in this order request

  - `invoiceNumber` (string)
    The invoice number generated in this order request

  - `orderNumber` (string)
    The order number of the order created.

  - `paidAmount` (string)
    The total amount collected in this order request.

  - `paymentId` (string)
    The payment id that is collected in this order request.

  - `paymentNumber` (string)
    The payment number that is collected in this order request.

  - `processId` (string)
    The Id of the process that handles the operation.

  - `reasons` (array)

  - `reasons.code` (string)
    The error code of response.

  - `reasons.message` (string)
    The detail information of the error response

  - `status` (string)
    Status of the order. Pending is only applicable for an order that contains a CreateSubscription order action.
    Enum: "Completed", "Pending"

  - `subscriptionId` (string)
    The subscription id of the order.

  - `subscriptionNumber` (string)
    The subscription number of the order.

  - `success` (boolean)
    Indicates whether the call succeeded.

## Response 500 fields (application/json):

  - `reasons` (array)
    Example: [{"code":"ObjectNotFound","message":"Notification definition with id 6e569e1e05f040eda51a927b140c0ac1 does not exist"}]

  - `reasons.code` (string)
    The error code of response.

  - `reasons.message` (string)
    The detail information of the error response

## Response 4XX fields (application/json):

  - `processId` (string)
    The ID of the process that handles the operation.

  - `reasons` (array)
    The container of the error code and message. This field is available only if the success field is false.

  - `reasons.code` (string)
    The error code of response.

  - `reasons.message` (string)
    The detail information of the error response

  - `requestId` (string)
    Unique identifier of the request.

  - `success` (boolean)
    Indicates whether the call succeeded.