> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL. > > Documentation indexes by section: > - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt > - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt > - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt > - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt > > Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth > Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks > > OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json > MCP server: https://docusign.docs.buildwithfern.com/_mcp/server # Update account billing plan PUT https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/billing_plan Content-Type: application/json Updates the billing plan information, billing address, and credit card information for the specified account. Reference: https://developers.docusign.com/docs/esign-rest-api/reference/billing/billingplans/update ## Authentication - `Authorization` header (required) (prefixed with ` Bearer `) — OAuth 2.0 access token (JWT or auth-code grant). Sent as `Authorization: Bearer ` on every request except `GET /v2.1` and `GET /service_information`, which are public discovery endpoints. ## Servers - `https://demo.docusign.net/restapi` (Demo, default) - `https://www.docusign.net/restapi` (Production) ## Request ### Path parameters - `accountId` (string, required) — The external account number (int) or account ID Guid. ### Query parameters - `preview_billing_plan` (string, optional) — When **true,** updates the account using a preview billing plan. ### Body (application/json) This endpoint expects a billingPlanInformation. - `appStoreReceipt` (appStoreReceipt, optional) — Contains information about an APP store receipt. - `billingAddress` (accountAddress, optional) — Contains information about the address associated with the account. - `creditCardInformation` (creditCardInformation, optional) — This object contains information about a credit card that is associated with an account. - `directDebitProcessorInformation` (directDebitProcessorInformation, optional) — Contains information about a bank that processes a customer's direct debit payments. - `downgradeReason` (string, optional) — (Optional) The user's reason for downgrading their billing plan. - `enablePreAuth` (string, optional) - `enableSupport` (string, optional) — When **true,** customer support is provided as part of the account plan. - `includedSeats` (string, optional) — The number of seats (users) included in the plan. - `incrementalSeats` (string, optional) — Reserved for Docusign. - `paymentMethod` (string, optional) — The payment method used for the billing plan. Valid values are: - `NotSupported` - `CreditCard` - `PurchaseOrder` - `Premium` - `Freemium` - `FreeTrial` - `AppStore` - `DigitalExternal` - `DirectDebit` - `paymentProcessor` (string, optional) - `paymentProcessorInformation` (paymentProcessorInformation, optional) - `planInformation` (planInformation, optional) — An object used to identify the features and attributes of the account being created. - `processPayment` (string, optional) - `referralInformation` (referralInformation, optional) — A complex type that contains the following information for entering referral and discount information. The following items are included in the referral information (all string content): enableSupport, includedSeats, saleDiscountPercent, saleDiscountAmount, saleDiscountFixedAmount, saleDiscountPeriods, saleDiscountSeatPriceOverride, planStartMonth, referralCode, referrerName, advertisementId, publisherId, shopperId, promoCode, groupMemberId, idType, and industry **Note:** saleDiscountPercent, saleDiscountAmount, saleDiscountFixedAmount, saleDiscountPeriods, and saleDiscountSeatPriceOverride are reserved for Docusign use only. - `renewalStatus` (string, optional) — The renewal status of the account. Possible values are: - `auto`: The account automatically renews. - `queued_for_close`: The account will be closed at the billingPeriodEndDate. - queued_for_downgrade`: The account will be downgraded at the` billingPeriodEndDate`. - `saleDiscountAmount` (string, optional) — Reserved for Docusign. - `saleDiscountFixedAmount` (string, optional) — Reserved for Docusign. - `saleDiscountPercent` (string, optional) — Reserved for Docusign. - `saleDiscountPeriods` (string, optional) — Reserved for Docusign. - `saleDiscountSeatPriceOverride` (string, optional) — Reserved for Docusign. - `taxExemptId` (string, optional) ## Response ### 200 Successful response. - `accountPaymentMethod` (string, optional) — The type of payment method used for the account. Valid values are: - `credit_card` - - `billingPlanPreview` (billingPlanPreview, optional) — Information used to provide a preview of a billing plan. - `currencyCode` (string, optional) — Specifies the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code for the account. - `includedSeats` (string, optional) — The number of seats (users) included in the plan. - `paymentCycle` (string, optional) — The payment cycle associated with the plan. Valid values: - `Monthly` - `Annually` - `paymentMethod` (string, optional) — The payment method used for the billing plan. Valid values are: - `NotSupported` - `CreditCard` - `PurchaseOrder` - `Premium` - `Freemium` - `FreeTrial` - `AppStore` - `DigitalExternal` - `DirectDebit` - `planId` (string, optional) — Docusign's ID for the account plan. - `planName` (string, optional) — The name of the billing plan used for the account. Examples: - `Personal - Annual` - `Unlimited Envelope Subscription - Annual Billing` ## Errors ### 400 Bad Request Error Error encountered. - `errorCode` (string, optional) — The code associated with the error condition. - `message` (string, optional) — A brief message describing the error condition. ## Types ### appStoreReceipt Contains information about an APP store receipt. - `downgradeProductId` (string, optional) - `isDowngradeCancellation` (string, optional) - `productId` (string, optional) — The Product ID from the AppStore. - `receiptData` (string, optional) — Reserved for Docusign. ### accountAddress Contains information about the address associated with the account. - `address1` (string, optional) — The first line of the address. Maximum length: 100 characters. - `address2` (string, optional) — The second line of the address. Maximum length: 100 characters. - `city` (string, optional) — The city associated with the address. Maximum length: 40 characters. - `country` (string, optional) — The country associated with the address. Maximum length: 50 characters. - `email` (string, optional) — The email address associated with the account. - `fax` (string, optional) — The fax number associated with the account. - `firstName` (string, optional) — The first name of the user associated with the account. Maximum Length: 50 characters. - `lastName` (string, optional) — The last name of the user associated with the account. - `phone` (string, optional) — The phone number associated with the account. - `postalCode` (string, optional) — The postal code associated with the address. Maximum length: 20 characters. - `state` (string, optional) — The state or province associated with the address. Maximum length: 40 characters. - `supportedCountries` (list of country, optional) — An array of supported countries associated with the account. ### creditCardInformation This object contains information about a credit card that is associated with an account. - `address` (addressInformation, optional) — Contains address information. - `cardLastDigits` (string, optional) - `cardNumber` (string, optional) — The credit card number. - `cardType` (string, optional) — The type of credit card. Valid values are: - `visa` - `mastercard` - `amex` - `cvNumber` (string, optional) — The 3 or 4-digit card verification value (CVV) number associated with the credit card. CVV numbers are also referred to as card security codes (CSCs). - `expirationMonth` (string, optional) — The month that the credit card expires, expressed as a number from 1 to 12. - `expirationYear` (string, optional) — The year in which the credit card expires, in 4-digit format. - `nameOnCard` (string, optional) — The exact name as it appears on the credit card. - `tokenizedCard` (string, optional) ### directDebitProcessorInformation Contains information about a bank that processes a customer's direct debit payments. - `bankBranchCode` (string, optional) — The branch code of the bank used for direct debit. Maximum Length: 10 characters. - `bankCheckDigit` (string, optional) — The check digit or digits in the international bank account number. These digits are used to confirm the validity of the account. Maximum Length: 4 characters. - `bankCode` (string, optional) — The code or number that identifies the bank. This is also known as the sort code. Example: `200000` Maximum Length: 18 characters. - `bankName` (string, optional) — The name of the direct debit bank. Maximum Length: 80 characters. - `bankTransferAccountName` (string, optional) — The name on the direct debit bank account. This field is required for POST and PUT requests. Maximum Length: 60 characters. - `bankTransferAccountNumber` (string, optional) — The customer's bank account number. This value will be obfuscated. This field is required for POST and PUT requests. Maximum Length: 30 characters. - `bankTransferType` (string, optional) — Specifies the type of direct debit transfer. The value of this field is dependent on the user's country. This field is required for POST and PUT requests. Possible values are: - `DirectDebitUK` - `DirectEntryAU` - `SEPA` - `country` (string, optional) — The user's country. The system populates this value automatically. - `email` (string, optional) — The email address of the user who is associated with the payment method. This field is required for POST and PUT requests. Maximum Length: 80 characters. - `firstName` (string, optional) — The user's first name. This field is required for POST and PUT requests. Maximum Length: 30 characters. - `iBAN` (string, optional) — The International Bank Account Number (IBAN). Example: `DE89370400440532013000` For more information, see [PeopleSoft's guide to Setting Up Banks](https://docs.oracle.com/cd/E16365_01/fscm91pbr0/eng/psbooks/fsbk/chapter.htm?File=fsbk/htm/fsbk03.htm). **Note:** This number will be obfuscated. - `lastName` (string, optional) — The user's last name. This field is required for POST and PUT requests. Maximum Length: 70 characters. ### paymentProcessorInformation - `address` (addressInformation, optional) — Contains address information. - `billingAgreementId` (string, optional) — The ID of the billing agreement. - `email` (string, optional) — The email address associated with the payment processor. ### planInformation An object used to identify the features and attributes of the account being created. - `addOns` (list of addOn, optional) — Reserved for Docusign. - `currencyCode` (string, optional) — Specifies the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code for the account. - `freeTrialDaysOverride` (string, optional) — Reserved for Docusign. - `planFeatureSets` (list of featureSet, optional) — Reserved for Docusign. - `planId` (string, optional) — Docusign's ID for the account plan. - `recipientDomains` (list of recipientDomain, optional) ### referralInformation A complex type that contains the following information for entering referral and discount information. The following items are included in the referral information (all string content): enableSupport, includedSeats, saleDiscountPercent, saleDiscountAmount, saleDiscountFixedAmount, saleDiscountPeriods, saleDiscountSeatPriceOverride, planStartMonth, referralCode, referrerName, advertisementId, publisherId, shopperId, promoCode, groupMemberId, idType, and industry **Note:** saleDiscountPercent, saleDiscountAmount, saleDiscountFixedAmount, saleDiscountPeriods, and saleDiscountSeatPriceOverride are reserved for Docusign use only. - `advertisementId` (string, optional) — A complex type that contains the following information for entering referral and discount information. The following items are included in the referral information (all string content): enableSupport, includedSeats, saleDiscountPercent, saleDiscountAmount, saleDiscountFixedAmount, saleDiscountPeriods, saleDiscountSeatPriceOverride, planStartMonth, referralCode, referrerName, advertisementId, publisherId, shopperId, promoCode, groupMemberId, idType, and industry. **Note:** saleDiscountPercent, saleDiscountAmount, saleDiscountFixedAmount, saleDiscountPeriods, and saleDiscountSeatPriceOverride are reserved for Docusign use only. - `enableSupport` (string, optional) — When **true,** customer support is provided as part of the account plan. - `externalOrgId` (string, optional) — An optional external ID for the referral. - `groupMemberId` (string, optional) - `idType` (string, optional) - `includedSeats` (string, optional) — The number of seats (users) included in the plan. - `industry` (string, optional) — The name of the industry associated with the referral. Example: `Accounting` - `planStartMonth` (string, optional) - `promoCode` (string, optional) - `publisherId` (string, optional) - `referralCode` (string, optional) - `referrerName` (string, optional) — The name of the referrer. - `saleDiscountAmount` (string, optional) — Reserved for Docusign. - `saleDiscountFixedAmount` (string, optional) — Reserved for Docusign. - `saleDiscountPercent` (string, optional) — Reserved for Docusign. - `saleDiscountPeriods` (string, optional) — Reserved for Docusign. - `saleDiscountSeatPriceOverride` (string, optional) — Reserved for Docusign. - `shopperId` (string, optional) ### billingPlanPreview Information used to provide a preview of a billing plan. - `currencyCode` (string, optional) — Specifies the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code for the account. - `invoice` (billingInvoice, optional) — Contains information about a billing invoice. - `isProrated` (string, optional) — When **true,** the billing plan is prorated. - `subtotalAmount` (string, optional) - `taxAmount` (string, optional) - `totalAmount` (string, optional) ### country - `isoCode` (string, optional) - `name` (string, optional) - `provinces` (list of province, optional) - `provinceValidated` (string, optional) ### addressInformation Contains address information. - `address1` (string, optional) — The first line of the user's address. Maximum length: 100 characters. - `address2` (string, optional) — The second line of the user's address. Maximum length: 100 characters. - `city` (string, optional) — The user's city. Maximum length: 40 characters. - `country` (string, optional) — The user's country. Maximum length: 50 characters. - `fax` (string, optional) — A Fax number associated with the address if one is available. - `phone` (string, optional) — A phone number associated with the address. - `postalCode` (string, optional) — The user's postal code. Maximum length: 20 characters. - `stateOrProvince` (string, optional) — The user's state or province. Maximum length: 40 characters. - `zipPlus4` (string, optional) ### addOn Contains information about add ons. - `active` (string, optional) — Reserved for Docusign. - `addOnId` (string, optional) — Reserved for Docusign. - `id` (string, optional) — A unique ID for the Salesforce object. - `name` (string, optional) — Reserved for Docusign. ### featureSet This object provides details about a feature set, or add-on product that is associated with an account. It is reserved for DocuSign internal use only. - `currencyFeatureSetPrices` (list of currencyFeatureSetPrice, optional) — Reserved for Docusign. - `envelopeFee` (string, optional) — Reserved for Docusign. - `featureSetId` (string, optional) — Reserved for Docusign. - `fixedFee` (string, optional) — Reserved for Docusign. - `is21CFRPart11` (string, optional) — Reserved for Docusign. - `isActive` (string, optional) — Reserved for Docusign. - `isEnabled` (string, optional) — When **true,** the feature set is actively enabled as part of the plan. - `name` (string, optional) — Reserved for Docusign. - `seatFee` (string, optional) — Reserved for Docusign. ### recipientDomain - `active` (string, optional) - `domainCode` (string, optional) - `domainName` (string, optional) - `recipientDomainId` (string, optional) ### billingInvoice Contains information about a billing invoice. - `amount` (string, optional) — The total amount of the purchase. - `balance` (string, optional) — Reserved for Docusign. - `dueDate` (string, optional) — Reserved for Docusign. - `invoiceId` (string, optional) — Reserved for Docusign. - `invoiceItems` (list of billingInvoiceItem, optional) — Reserved for Docusign. - `invoiceNumber` (string, optional) — Reserved for Docusign. - `invoiceUri` (string, optional) — Contains a URI for an endpoint that you can use to retrieve invoice information. - `nonTaxableAmount` (string, optional) - `pdfAvailable` (string, optional) - `taxableAmount` (string, optional) ### province - `isoCode` (string, optional) - `name` (string, optional) ### currencyFeatureSetPrice Information about the price and currency associated with the feature set. Reserved for internal DocuSign use only. - `currencyCode` (string, optional) — Specifies the alternate ISO currency code for the account. - `currencySymbol` (string, optional) — Reserved for Docusign. - `envelopeFee` (string, optional) — Reserved for Docusign. - `fixedFee` (string, optional) — Reserved for Docusign. - `seatFee` (string, optional) — Reserved for Docusign. ### billingInvoiceItem Contains information about an item on a billing invoice. - `chargeAmount` (string, optional) — Reserved for Docusign. - `chargeName` (string, optional) — Reserved for Docusign. - `invoiceItemId` (string, optional) — Reserved for Docusign. - `quantity` (string, optional) — The quantity of envelopes to add to the account. - `taxAmount` (string, optional) - `taxExemptAmount` (string, optional) - `unitPrice` (string, optional) — Reserved for Docusign. ## Examples **Request** ```json { "appStoreReceipt": { "downgradeProductId": "sample string 1", "isDowngradeCancellation": "sample string 2", "productId": "sample string 3", "receiptData": "sample string 4" }, "billingAddress": { "address1": "sample string 1", "address2": "sample string 2", "city": "sample string 3", "country": "sample string 4", "email": "sample string 5", "fax": "sample string 6", "firstName": "sample string 7", "lastName": "sample string 8", "phone": "sample string 9", "postalCode": "sample string 10", "state": "sample string 11", "supportedCountries": [ { "isoCode": "sample string 1", "name": "sample string 2", "provinces": [ { "isoCode": "sample string 1", "name": "sample string 2" } ], "provinceValidated": "sample string 3" } ] }, "creditCardInformation": { "address": { "address1": "sample string 1", "address2": "sample string 2", "city": "sample string 3", "country": "sample string 4", "fax": "sample string 5", "phone": "sample string 6", "postalCode": "sample string 7", "stateOrProvince": "sample string 8", "zipPlus4": "sample string 9" }, "cardLastDigits": "sample string 1", "cardNumber": "sample string 2", "cardType": "sample string 3", "cvNumber": "sample string 4", "expirationMonth": "sample string 5", "expirationYear": "sample string 6", "nameOnCard": "sample string 7", "tokenizedCard": "sample string 8" }, "directDebitProcessorInformation": { "bankBranchCode": "sample string 1", "bankCheckDigit": "sample string 2", "bankCode": "sample string 3", "bankName": "sample string 4", "bankTransferAccountName": "sample string 5", "bankTransferAccountNumber": "sample string 6", "bankTransferType": "sample string 7", "country": "sample string 8", "email": "sample string 9", "firstName": "sample string 10", "iBAN": "sample string 11", "lastName": "sample string 12" }, "downgradeReason": "sample string 1", "enablePreAuth": "sample string 2", "enableSupport": "sample string 3", "includedSeats": "sample string 4", "incrementalSeats": "sample string 5", "paymentMethod": "sample string 6", "paymentProcessor": "sample string 7", "paymentProcessorInformation": { "billingAgreementId": "sample string 1", "email": "sample string 2" }, "planInformation": { "addOns": [ { "active": "sample string 1", "addOnId": "sample string 2", "id": "sample string 3", "name": "sample string 4" } ], "currencyCode": "sample string 1", "freeTrialDaysOverride": "sample string 2", "planFeatureSets": [ { "currencyFeatureSetPrices": [ { "currencyCode": "sample string 1", "currencySymbol": "sample string 2", "envelopeFee": "sample string 3", "fixedFee": "sample string 4", "seatFee": "sample string 5" } ], "envelopeFee": "sample string 1", "featureSetId": "sample string 2", "fixedFee": "sample string 3", "is21CFRPart11": "sample string 4", "isActive": "sample string 5", "isEnabled": "sample string 6", "name": "sample string 7", "seatFee": "sample string 8" } ], "planId": "sample string 3", "recipientDomains": [ { "active": "sample string 1", "domainCode": "sample string 2", "domainName": "sample string 3", "recipientDomainId": "sample string 4" } ] }, "processPayment": "sample string 8", "referralInformation": { "advertisementId": "sample string 1", "enableSupport": "sample string 2", "externalOrgId": "sample string 3", "groupMemberId": "sample string 4", "idType": "sample string 5", "includedSeats": "sample string 6", "industry": "sample string 7", "planStartMonth": "sample string 8", "promoCode": "sample string 9", "publisherId": "sample string 10", "referralCode": "sample string 11", "referrerName": "sample string 12", "saleDiscountAmount": "sample string 13", "saleDiscountFixedAmount": "sample string 14", "saleDiscountPercent": "sample string 15", "saleDiscountPeriods": "sample string 16", "saleDiscountSeatPriceOverride": "sample string 17", "shopperId": "sample string 18" }, "renewalStatus": "sample string 9", "saleDiscountAmount": "sample string 10", "saleDiscountFixedAmount": "sample string 11", "saleDiscountPercent": "sample string 12", "saleDiscountPeriods": "sample string 13", "saleDiscountSeatPriceOverride": "sample string 14", "taxExemptId": "sample string 15" } ``` **Response** ```json { "accountPaymentMethod": "sample string 1", "billingPlanPreview": { "currencyCode": "sample string 1", "invoice": { "amount": "sample string 1", "balance": "sample string 2", "dueDate": "sample string 3", "invoiceId": "sample string 4", "invoiceItems": [ { "chargeAmount": "sample string 1", "chargeName": "sample string 2", "invoiceItemId": "sample string 3", "quantity": "sample string 4", "taxAmount": "sample string 5", "taxExemptAmount": "sample string 6", "unitPrice": "sample string 7" } ], "invoiceNumber": "sample string 5", "invoiceUri": "sample string 6", "nonTaxableAmount": "sample string 7", "pdfAvailable": "sample string 8", "taxableAmount": "sample string 9" }, "isProrated": "sample string 2", "subtotalAmount": "sample string 3", "taxAmount": "sample string 4", "totalAmount": "sample string 5" }, "currencyCode": "sample string 2", "includedSeats": "sample string 3", "paymentCycle": "sample string 4", "paymentMethod": "sample string 5", "planId": "sample string 6", "planName": "sample string 7" } ```