> 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/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/v2/reference/billing/billingplans/update

## Authentication

- `Authorization` header (required) — OAuth 2.0 access token (JWT or auth-code grant). Sent as Authorization: Bearer \<token>.

## 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 set to **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 an account address.
- `creditCardInformation` (creditCardInformation, optional)
- `downgradeReason` (string, optional)
- `enableSupport` (string, optional) — When set to **true**, then customer support is provided as part of the account plan.
- `includedSeats` (string, optional) — The number of seats (users) included.
- `incrementalSeats` (string, optional) — Reserved: TBD
- `paymentProcessorInformation` (paymentProcessorInformation, optional)
- `planInformation` (planInformation, optional) — An object used to identify the features and attributes of the account being created.
- `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 DoucSign use only.
- `renewalStatus` (string, optional)
- `saleDiscountAmount` (string, optional) — Reserved for DocuSign use only.
- `saleDiscountFixedAmount` (string, optional) — Reserved for DocuSign use only.
- `saleDiscountPercent` (string, optional) — Reserved for DocuSign use only.
- `saleDiscountPeriods` (string, optional) — Reserved for DocuSign use only.
- `saleDiscountSeatPriceOverride` (string, optional) — Reserved for DocuSign use only.

## Response

### 200

Successful response.

- `accountPaymentMethod` (string, optional)
- `billingPlanPreview` (billingPlanPreview, optional) — Contains information about a preview billing plan.
- `currencyCode` (string, optional) — Specifies the ISO currency code for the account.
- `includedSeats` (string, optional) — The number of seats (users) included.
- `paymentCycle` (string, optional)
- `paymentMethod` (string, optional)
- `planId` (string, optional) — The DocuSign Plan ID for the account.
- `planName` (string, optional)

## Errors

### 400 Bad Request Error

Error encountered.

- `errorCode` (string, optional) — An error code associated with the error.
- `message` (string, optional) — A short error message.

## Types

### appStoreReceipt

Contains information about an APP store receipt.

- `productId` (string, optional) — The Product ID from the AppStore.
- `receiptData` (string, optional) — Reserved: TBD

### accountAddress

Contains information about an account address.

- `address1` (string, optional) — First Line of the address. Maximum length: 100 characters.
- `address2` (string, optional) — Second Line of the address. Maximum length: 100 characters.
- `city` (string, optional) — The city value of the address.
- `country` (string, optional) — Specifies the country associated with the address.
- `email` (string, optional)
- `fax` (string, optional)
- `firstName` (string, optional) — The user's first name. Maximum Length: 50 characters.
- `lastName` (string, optional) — The recipient's last name.
- `phone` (string, optional)
- `postalCode` (string, optional)
- `state` (string, optional) — The state or province associated with the address.
- `supportedCountries` (list of country, optional) — Contains an array of countries supported by the billing plan.

### creditCardInformation

- `address` (addressInformation, optional) — Contains address information.
- `cardNumber` (string, optional) — The number on the credit card.
- `cardType` (string, optional) — The credit card type. Valid values are: visa, mastercard, or amex.
- `expirationMonth` (string, optional) — The month that the credit card expires (1-12).
- `expirationYear` (string, optional) — The year 4 digit year in which the credit card expires.
- `nameOnCard` (string, optional) — The exact name printed on the credit card.

### paymentProcessorInformation

- `address` (addressInformation, optional) — Contains address information.
- `billingAgreementId` (string, optional)
- `email` (string, optional)

### planInformation

An object used to identify the features and attributes of the account being created.

- `addOns` (list of addOn, optional) — Reserved:
- `currencyCode` (string, optional) — Specifies the ISO currency code for the account.
- `freeTrialDaysOverride` (string, optional) — Reserved for DocuSign use only.
- `planFeatureSets` (list of featureSet, optional) — A complex type that sets the feature sets for the account.
- `planId` (string, optional) — The DocuSign Plan ID for the account.
- `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 DoucSign 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 DoucSign use only.
- `enableSupport` (string, optional) — When set to **true**, then customer support is provided as part of the account plan.
- `externalOrgId` (string, optional)
- `groupMemberId` (string, optional)
- `idType` (string, optional)
- `includedSeats` (string, optional) — The number of seats (users) included.
- `industry` (string, optional)
- `planStartMonth` (string, optional)
- `promoCode` (string, optional)
- `publisherId` (string, optional)
- `referralCode` (string, optional)
- `referrerName` (string, optional)
- `saleDiscountAmount` (string, optional) — Reserved for DocuSign use only.
- `saleDiscountFixedAmount` (string, optional) — Reserved for DocuSign use only.
- `saleDiscountPercent` (string, optional) — Reserved for DocuSign use only.
- `saleDiscountPeriods` (string, optional) — Reserved for DocuSign use only.
- `saleDiscountSeatPriceOverride` (string, optional) — Reserved for DocuSign use only.
- `shopperId` (string, optional)

### billingPlanPreview

Contains information about a preview billing plan.

- `currencyCode` (string, optional) — Specifies the ISO currency code for the account.
- `invoice` (billingInvoice, optional)
- `isProrated` (string, optional)
- `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.

- `city` (string, optional) — The city associated with the address.
- `country` (string, optional) — Specifies the country associated with the address.
- `fax` (string, optional) — A Fax number associated with the address if one is available.
- `phone` (string, optional) — A phone number associated with the address.
- `state` (string, optional) — The state or province associated with the address.
- `street1` (string, optional) — The first line of the address.
- `street2` (string, optional) — The second line of the address (optional).
- `zip` (string, optional) — The zip or postal code associated with the address.
- `zipPlus4` (string, optional)

### addOn

Contains information about add ons.

- `active` (string, optional) — Reserved:
- `addOnId` (string, optional) — Reserved:
- `id` (string, optional)
- `name` (string, optional) — Reserved:

### featureSet

- `currencyFeatureSetPrices` (list of currencyFeatureSetPrice, optional) — A complex type that contains alternate currency values that are configured for this plan feature set.
- `envelopeFee` (string, optional)
- `featureSetId` (string, optional) — A unique ID for the feature set.
- `fixedFee` (string, optional)
- `is21CFRPart11` (string, optional) — When set to **true**, indicates that this module is enabled on the account.
- `isActive` (string, optional)
- `isEnabled` (string, optional) — Specifies whether the feature set is actively enabled as part of the plan.
- `name` (string, optional)
- `seatFee` (string, optional) — An incremental seat cost for seat-based plans. Only valid when isEnabled for the feature set is set to true.

### recipientDomain

- `active` (string, optional)
- `domainCode` (string, optional)
- `domainName` (string, optional)
- `recipientDomainId` (string, optional)

### billingInvoice

- `amount` (string, optional) — The total amount of the purchase.
- `balance` (string, optional) — Reserved: TBD
- `dueDate` (string, optional) — Reserved: TBD
- `invoiceId` (string, optional)
- `invoiceItems` (list of billingInvoiceItem, optional) — Reserved: TBD
- `invoiceNumber` (string, optional) — Reserved: TBD
- `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

- `currencyCode` (string, optional) — Specifies the alternate ISO currency code for the account.
- `currencySymbol` (string, optional) — Specifies the alternate currency symbol for the account.
- `envelopeFee` (string, optional) — An incremental envelope cost for plans with envelope overages (when `isEnabled` is set to **true**.)
- `fixedFee` (string, optional) — Specifies a one-time fee associated with the plan (when `isEnabled` is set to **true**.)
- `seatFee` (string, optional) — Specifies an incremental seat cost for seat-based plans (when `isEnabled` is set to **true**.)

### billingInvoiceItem

Contains information about an item on a billing invoice.

- `chargeAmount` (string, optional) — Reserved: TBD
- `chargeName` (string, optional) — Reserved: TBD
- `invoiceItemId` (string, optional) — Reserved: TBD
- `quantity` (string, optional) — The quantity of envelopes to add to the account.
- `unitPrice` (string, optional) — Reserved: TBD

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "accountPaymentMethod": "string",
  "billingPlanPreview": {
    "currencyCode": "string",
    "invoice": {
      "amount": "string",
      "balance": "string",
      "dueDate": "string",
      "invoiceId": "string",
      "invoiceItems": [
        {
          "chargeAmount": "string",
          "chargeName": "string",
          "invoiceItemId": "string",
          "quantity": "string",
          "unitPrice": "string"
        }
      ],
      "invoiceNumber": "string",
      "invoiceUri": "string",
      "nonTaxableAmount": "string",
      "pdfAvailable": "string",
      "taxableAmount": "string"
    },
    "isProrated": "string",
    "subtotalAmount": "string",
    "taxAmount": "string",
    "totalAmount": "string"
  },
  "currencyCode": "string",
  "includedSeats": "string",
  "paymentCycle": "string",
  "paymentMethod": "string",
  "planId": "string",
  "planName": "string"
}
```