> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # CreateDraftSubscriptionContract # Package: subscriptions # Namespace: DraftSubscriptionContractsService # Method link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/create-draft-subscription-contract.md ## Permission Scopes: Write draft subscription contracts: SCOPE.ECOM.DRAFT-SUBSCRIPTION-CONTRACT-WRITE ## Introduction Creates a draft subscription contract from an existing subscription contract. The draft subscription contract starts as a copy of the subscription contract's line items, discounts, additional fees, and buyer, billing, shipping, and recipient details. Discounts and additional fees that end before the next billing cycle aren't copied. The response includes the totals recalculated for the next billing cycle. A subscription contract can have 1 draft subscription contract with the `DRAFT` status at a time, whoever created it. Before you create a draft subscription contract, call [Get Subscription Contract Draftability](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/get-subscription-contract-draftability.md) to check that the subscription contract can be edited. If another identity has a draft subscription contract with the `DRAFT` status for this subscription contract, the call fails with `SUBSCRIPTION_CONTRACT_NOT_DRAFTABLE`, and the error details list `DRAFT_ALREADY_EXISTS_FOR_ANOTHER_OWNER`. When you already created a draft subscription contract for this subscription contract with the same `target`, this method returns the existing draft subscription contract instead of creating another one, and `preexistingDraftSubscriptionContract` is `true`. A draft subscription contract expires when it has no changes for 24 hours, or when the billing cycle in its `target.contractTarget.nextCycleNumber` has already started. When anyone then creates a draft subscription contract for the same subscription contract, the expired draft subscription contract is deleted and replaced. A site member can create a draft subscription contract only for a subscription contract they bought. Otherwise, the call fails with `SUBSCRIPTION_CONTRACT_NOT_DRAFTABLE`, and the error details list `NOT_SUBSCRIPTION_CONTRACT_BUYER`. --- ## REST API ### Schema ``` Method: createDraftSubscriptionContract Description: Creates a draft subscription contract from an existing subscription contract. The draft subscription contract starts as a copy of the subscription contract's line items, discounts, additional fees, and buyer, billing, shipping, and recipient details. Discounts and additional fees that end before the next billing cycle aren't copied. The response includes the totals recalculated for the next billing cycle. A subscription contract can have 1 draft subscription contract with the `DRAFT` status at a time, whoever created it. Before you create a draft subscription contract, call [Get Subscription Contract Draftability](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/get-subscription-contract-draftability.md) to check that the subscription contract can be edited. If another identity has a draft subscription contract with the `DRAFT` status for this subscription contract, the call fails with `SUBSCRIPTION_CONTRACT_NOT_DRAFTABLE`, and the error details list `DRAFT_ALREADY_EXISTS_FOR_ANOTHER_OWNER`. When you already created a draft subscription contract for this subscription contract with the same `target`, this method returns the existing draft subscription contract instead of creating another one, and `preexistingDraftSubscriptionContract` is `true`. A draft subscription contract expires when it has no changes for 24 hours, or when the billing cycle in its `target.contractTarget.nextCycleNumber` has already started. When anyone then creates a draft subscription contract for the same subscription contract, the expired draft subscription contract is deleted and replaced. A site member can create a draft subscription contract only for a subscription contract they bought. Otherwise, the call fails with `SUBSCRIPTION_CONTRACT_NOT_DRAFTABLE`, and the error details list `NOT_SUBSCRIPTION_CONTRACT_BUYER`. URL: https://www.wixapis.com/ecom/v1/draft-subscription-contracts Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: subscriptionContractId Method parameters: param name: subscriptionContractId | type: subscriptionContractId | description: GUID of the subscription contract to create the draft subscription contract from. | required: true | validation: format GUID param name: target | type: Target | description: Billing cycles that a draft subscription contract applies to. | required: true - name: contractTarget | type: ContractTarget | description: Applies the changes to the subscription contract, from the next billing cycle onward. - name: nextCycleNumber | type: integer | description: Number of the next billing cycle. Set it to `currentCycleNumber` + 1, where `currentCycleNumber` is returned by [Get Subscription Contract Draftability](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/get-subscription-contract-draftability.md). | validation: format int32 Return type: CreateDraftSubscriptionContractResponse - name: calculatedDraftSubscriptionContract | type: CalculatedDraftSubscriptionContract | description: Created draft subscription contract with recalculated totals. When you already have a draft subscription contract for this subscription contract with the same `target`, the existing draft subscription contract is returned. - name: draftSubscriptionContract | type: DraftSubscriptionContract | description: Draft subscription contract. - name: id | type: string | description: Draft subscription contract GUID. | read-only: true | validation: format GUID - name: subscriptionContractId | type: string | description: GUID of the subscription contract that the draft subscription contract was created from. | validation: format GUID, immutable - name: target | type: Target | description: Billing cycles that the draft subscription contract applies to. - ONE-OF: - name: contractTarget | type: ContractTarget | description: Applies the changes to the subscription contract, from the next billing cycle onward. - name: nextCycleNumber | type: integer | description: Number of the next billing cycle. Set it to `currentCycleNumber` + 1, where `currentCycleNumber` is returned by [Get Subscription Contract Draftability](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/get-subscription-contract-draftability.md). | validation: format int32 - name: createdDate | type: string | description: Date and time the draft subscription contract was created. | read-only: true | validation: format date-time - name: updatedDate | type: string | description: Date and time the draft subscription contract was updated. A draft subscription contract with the `DRAFT` status expires 24 hours after this time. | read-only: true | validation: format date-time - name: createdBy | type: CreatedBy | description: Identity that created the draft subscription contract. Only this identity can retrieve, update, commit, or delete the draft subscription contract. | read-only: true - ONE-OF: - name: userId | type: string | description: User GUID. Returned when a Wix user created the draft subscription contract. | validation: format GUID - name: appId | type: string | description: App GUID. Returned when an app created the draft subscription contract. | validation: format GUID - name: memberId | type: string | description: Member GUID. Returned when a site member created the draft subscription contract. | validation: format GUID - name: identityType | type: IdentityType | description: Type of identity that created the draft subscription contract. - enum: - USER: A Wix user. - APP: An app. - MEMBER: A site member. - name: status | type: DraftStatus | description: Status of the draft subscription contract. | read-only: true - enum: - DRAFT: The draft subscription contract can be edited and committed. - COMMITTED: The draft subscription contract was committed and its changes were applied to the subscription contract. It can't be edited or deleted. - name: lineItems | type: array | description: Line items, each with how it changed compared to the subscription contract. Removed line items are returned with `changeType` set to `REMOVED`. In a draft subscription contract, `lineItem.subscriptionInfo.cycleNumber` is `0`. | validation: maxItems 100 - ONE-OF: - name: changedDetails | type: LineItemChangedDetails | description: Line item values before the change. - name: quantityBeforeChange | type: integer | description: Quantity before the change. Set only when the quantity changed. | validation: format int32 - name: priceBeforeChange | type: Price | description: Price before the change. Set only when the price changed. - name: amount | type: string | description: Amount. | validation: decimalValue {"gte":"0","lte":"1000000000000000"} - name: formattedAmount | type: string | description: Amount formatted with currency symbol. | read-only: true - name: catalogReferenceOptionsBeforeChange | type: CatalogReferenceOptionsBeforeChange | description: Catalog reference options before the change. Set only when the catalog reference options changed. - name: options | type: object | description: Catalog reference options. Absent when the line item had no options. - name: productNameBeforeChange | type: ProductNameBeforeChange | description: Product name before the change. Set only when the product name changed. - name: productName | type: ProductName | description: Product name. Absent when the line item had no product name. - name: original | type: string | description: __Required.__ Item name in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). Min: 1 character. Max: 200 characters. | validation: minLength 1, maxLength 200 - name: translated | type: string | description: Item name translated into the buyer's language. Min: 1 character. Max: 400 characters. Default: Same as `original`. | validation: minLength 1, maxLength 400 - name: descriptionLinesBeforeChange | type: DescriptionLinesBeforeChange | description: Description lines before the change. Set only when the description lines changed. - name: descriptionLines | type: array | description: Description lines. Empty when the line item had no description lines. | validation: minItems 0, maxItems 20 - ONE-OF: - name: plainText | type: PlainTextValue | description: Description line plain text value. - name: original | type: string | description: Description line plain text value in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). | validation: maxLength 600 - name: translated | type: string | description: Description line plain text value translated into the buyer's language. Default: Same as `original`. | validation: maxLength 600 - name: colorInfo | type: Color | description: Description line color value. - name: original | type: string | description: Description line color name in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). | validation: maxLength 500 - name: translated | type: string | description: Description line color name translated into the buyer's language. Default: Same as `original`. | validation: maxLength 500 - name: code | type: string | description: HEX or RGB color code for display. - name: name | type: DescriptionLineName | description: Description line name. - name: original | type: string | description: Description line name in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). | validation: maxLength 100 - name: translated | type: string | description: Description line name translated into the buyer's language. Default: Same as `original`. | validation: maxLength 200 - name: imageBeforeChange | type: ImageBeforeChange | description: Image before the change. Set only when the image changed. - name: image | type: Image | description: Image. Absent when the line item had no image. - name: id | type: string | description: Wix Media image GUID. | validation: maxLength 400 - name: url | type: string | description: Image URL. | validation: format WEB_URL - name: height | type: integer | description: Original image height. | read-only: true - name: width | type: integer | description: Original image width. | read-only: true - name: altText | type: string | description: Image alt text. | validation: maxLength 200 - name: filename | type: string | description: Image filename. | read-only: true | validation: maxLength 200 - name: physicalPropertiesBeforeChange | type: PhysicalPropertiesBeforeChange | description: Physical properties before the change. Set only when the physical properties changed. - name: physicalProperties | type: PhysicalProperties | description: Physical properties. Absent when the line item had no physical properties. - name: weight | type: number | description: Line item weight. Measurement unit matches the weight unit specified in `weightUnit` in the request. | validation: format double - name: sku | type: string | description: Stock-keeping unit. Learn more about [SKUs](https://www.wix.com/encyclopedia/definition/stock-keeping-unit-sku). | validation: maxLength 40 - name: shippable | type: boolean | description: Whether this line item is shippable. - name: itemTypeBeforeChange | type: ItemTypeBeforeChange | description: Item type before the change. Set only when the item type changed. - name: itemType | type: ItemType | description: Item type. Absent when the line item had no item type. - ONE-OF: - name: preset | type: ItemTypePreset | description: Preset item type. - enum: UNRECOGNISED, PHYSICAL, DIGITAL, GIFT_CARD, SERVICE - name: custom | type: string | description: Custom item type. When none of the preset types are suitable, specifies the custom type. - name: fulfillerIdBeforeChange | type: FulfillerIdBeforeChange | description: Fulfiller GUID before the change. Set only when the fulfiller GUID changed. - name: fulfillerId | type: string | description: Fulfiller GUID. Absent when the line item had no fulfiller. | validation: format GUID - name: digitalFileBeforeChange | type: DigitalFileBeforeChange | description: Digital file before the change. Set only when the digital file changed. - name: digitalFile | type: DigitalFile | description: Digital file. Absent when the line item had no digital file. - name: fileId | type: string | description: GUID of the secure file in media. | validation: minLength 1, maxLength 100 - name: link | type: string | description: Link will exist after the digital links have been generated on the order. | validation: minLength 1, maxLength 2000, format WEB_URL - name: expirationDate | type: string | description: Link expiration time and date. | read-only: true | validation: format date-time - name: priceDescriptionBeforeChange | type: PriceDescriptionBeforeChange | description: Price description before the change. Set only when the price description changed. - name: priceDescription | type: PriceDescription | description: Price description. Absent when the line item had no price description. - name: original | type: string | description: __Required.__ Price description in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). | validation: minLength 1, maxLength 100 - name: translated | type: string | description: Price description translated into the buyer's language. Default: Same as `original`. | validation: minLength 1, maxLength 100 - name: taxInfoBeforeChange | type: TaxInfoBeforeChange | description: Tax info before the change. Set only when the line item's tax group changed. - name: taxInfo | type: LineItemTaxInfo | description: Tax info. Absent when the line item had no tax info. - name: taxAmount | type: Price | description: Calculated tax, based on `taxable_amount` and `tax_rate`. - name: taxableAmount | type: Price | description: Amount for which tax is calculated. - name: taxRate | type: string | description: Tax rate %, as a decimal point. | validation: format DECIMAL_VALUE, decimalValue {"gte":"0","maxScale":6} - name: taxGroupId | type: string | description: Tax group GUID. | validation: format GUID - name: taxIncludedInPrice | type: boolean | description: Indicates whether the price already includes tax. - name: taxBreakdown | type: array | description: Tax information for a line item. | validation: maxItems 7 - name: jurisdiction | type: string | description: Jurisdiction that taxes were calculated for. For example, "New York", or "Quebec". | validation: maxLength 200 - name: rate | type: string | description: Tax rate used for this jurisdiction, as a decimal. For example, 10% tax is 0.1000. | validation: format DECIMAL_VALUE, decimalValue {"gte":"0","maxScale":6} - name: taxAmount | type: Price | description: Amount of tax calculated for this line item. - name: taxType | type: string | description: The type of tax that was calculated. Depends on the jurisdiction's tax laws. For example, "Sales Tax", "Income Tax", "Value Added Tax", etc. | validation: maxLength 200 - name: taxName | type: string | description: The name of the tax against which this tax amount was calculated. For example, "NY State Sales Tax", "Quebec GST", etc. This name should be explicit enough to allow the merchant to understand what tax was calculated. | validation: maxLength 200 - name: jurisdictionType | type: JurisdictionType | description: Type of jurisdiction that taxes were calculated for. - enum: UNDEFINED, COUNTRY, STATE, COUNTY, CITY, SPECIAL - name: nonTaxableAmount | type: Price | description: Non-taxable amount of the line item price. - name: taxableAmount | type: Price | description: Taxable amount of the line item price. - name: inventoryAppIdBeforeChange | type: InventoryAppIdBeforeChange | description: Inventory app GUID before the change. Set only when the inventory app GUID changed. - name: inventoryAppId | type: string | description: Inventory app GUID. Absent when the line item had no inventory app. | validation: format GUID - name: modifierGroupsBeforeChange | type: ModifierGroupsBeforeChange | description: Modifier groups before the change. Set only when the modifier groups changed. - name: modifierGroups | type: array | description: Modifier groups. Empty when the line item had no modifier groups. | validation: maxItems 10 - name: id | type: string | description: Modifier group GUID. | validation: minLength 1, maxLength 36 - name: name | type: TranslatableString | description: Modifier group name. - name: original | type: string | description: __Required.__ String in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). Min: 1 character. Max: 200 characters. | validation: minLength 1, maxLength 200 - name: translated | type: string | description: String translated into the buyer's language. Min: 1 character. Max: 400 characters. Default: Same as `original`. | validation: minLength 1, maxLength 400 - name: modifiers | type: array | description: List of modifiers in this group. | validation: minItems 1, maxItems 10 - name: id | type: string | description: Modifier GUID. | validation: minLength 1, maxLength 36 - name: quantity | type: integer | description: The quantity of this modifier. | validation: minimum 1, maximum 100000, format int32 - name: label | type: TranslatableString | description: Primary display label for the modifier. - name: details | type: TranslatableString | description: Additional details. - name: price | type: Price | description: The price of the modifier. - name: priceUndeterminedBeforeChange | type: PriceUndeterminedBeforeChange | description: Price undetermined flag before the change. Set only when the price undetermined flag changed. - name: priceUndetermined | type: boolean | description: Whether the price of the line item was undetermined. - name: lineItem | type: OrderLineItem | description: Line item. - name: id | type: string | description: Line item GUID. | validation: immutable - name: productName | type: ProductName | description: Item name. + Stores - `product.name` + Bookings - `service.info.name` + Events - `ticket.name` - name: catalogReference | type: CatalogReference | description: References to the line item's origin catalog. Empty for custom line items. - name: catalogItemId | type: string | description: GUID of the item within the catalog it belongs to. | validation: minLength 1, maxLength 36 - name: appId | type: string | description: GUID of the app providing the catalog. You can get your app's GUID from its page in the [app dashboard](https://dev.wix.com/dc3/my-apps/). For items from Wix catalogs, the following values always apply: + Wix Stores: `"215238eb-22a5-4c36-9e7b-e7c08025e04e"` + Wix Bookings: `"13d21c63-b5ec-5912-8397-c3a5ddb27a97"` + Wix Restaurants: `"9a5d83fd-8570-482e-81ab-cfa88942ee60"` | validation: minLength 1 - name: options | type: object | description: Additional item details in `key:value` pairs. Use this optional field for more specificity with item selection. The values of the `options` field differ depending on which catalog is providing the items. For Wix Stores products, learn more about integrating with [Catalog V3](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/e-commerce-integration.md) or [Catalog V1](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v1/catalog/e-commerce-integration.md), depending on [the version the site uses](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-versioning/introduction.md). - name: quantity | type: integer | description: Line item quantity. | validation: minimum 1, maximum 100000 - name: totalDiscount | type: Price | description: Total discount for this line item's entire quantity. | read-only: true - name: descriptionLines | type: array | description: Line item description lines. Used for display purposes for the cart, checkout and order. | validation: minItems 0, maxItems 20 - name: image | type: Image | description: Line item image. - name: id | type: string | description: WixMedia image GUID. - name: url | type: string | description: Image URL. - name: height | type: integer | description: Original image height. | read-only: true - name: width | type: integer | description: Original image width. | read-only: true - name: altText | type: string | description: Image alt text. - name: filename | type: string | description: Image filename. | read-only: true - name: physicalProperties | type: PhysicalProperties | description: Physical properties of the item. When relevant, contains information such as SKU and item weight. - name: itemType | type: ItemType | description: Item type. Either a preset type or custom. - name: fulfillerId | type: string | description: Fulfiller GUID. Field is empty when the line item is self-fulfilled. To get fulfillment information, pass the order GUID to [List Fulfillments For Single Order](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-fulfillments/list-fulfillments-for-single-order.md). | validation: format GUID - name: refundQuantity | type: integer | description: Number of items that were refunded. | validation: minimum 0, maximum 100000, format int32 - name: restockQuantity | type: integer | description: Number of items restocked. For a per-location breakdown, see `restockLocations`. | validation: minimum 0, maximum 100000, format int32 - name: price | type: Price | description: Line item price after line item discounts for display purposes. - name: priceBeforeDiscounts | type: Price | description: Line item price before line item discounts for display purposes. Defaults to `price` when not provided. | read-only: true - name: totalPriceBeforeTax | type: Price | description: Total price after discounts, and before tax. | read-only: true - name: totalPriceAfterTax | type: Price | description: Total price after all discounts and tax. | read-only: true - name: paymentOption | type: PaymentOptionType | description: Type of selected payment option for current item. Default: `FULL_PAYMENT_ONLINE` - enum: - FULL_PAYMENT_ONLINE: The entire payment for this item happens as part of the checkout. - FULL_PAYMENT_OFFLINE: The entire payment for this item happens after checkout. For example, when using cash, check, or other offline payment methods. - MEMBERSHIP: Payment for this item is done by charging a membership. Any remaining amount not covered by the membership, such as item modifiers, is paid online. - DEPOSIT_ONLINE: Partial payment to be paid upfront during checkout. The initial amount to be paid for each line item is specified in `depositAmount`. - MEMBERSHIP_OFFLINE: Payment for this item can only be done by charging a membership and must be manually redeemed in the dashboard by the site admin. When selected, `price` is `0`. - MEMBERSHIP_ONLINE_WITH_OFFLINE_REMAINDER: Item price is charged to online membership. Any remaining amount not covered by the membership, such as item modifiers, is paid offline. - name: taxInfo | type: LineItemTaxInfo | description: Represents all the relevant tax details for a specific line item. - name: digitalFile | type: DigitalFile | description: Digital file identifier, relevant only for items with type DIGITAL. - name: subscriptionInfo | type: SubscriptionInfo | description: Subscription info. - name: id | type: string | description: Subscription GUID. For a subscription bought through Wix eCommerce, this is the GUID of the subscription contract the order was created from. To retrieve the subscription contract, call [Get Subscription Contract](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/subscription-contracts/get-subscription-contract.md). | validation: format GUID - name: cycleNumber | type: integer | description: Billing cycle the order is for. For example, `3` for the third billing cycle of a subscription. When a subscription starts with a free trial, the order created at checkout is for cycle `0`. | validation: minimum 0 - name: subscriptionSettings | type: SubscriptionSettings | description: Subscription detailed information. - name: frequency | type: SubscriptionFrequency | description: Frequency unit of the billing cycle. - enum: UNDEFINED, DAY, WEEK, MONTH, YEAR - name: interval | type: integer | description: Number of frequency units in a billing cycle. For example, frequency `MONTH` with interval `3` means billing every 3 months. | validation: minimum 1, maximum 3650, format int32 - name: autoRenewal | type: boolean | description: Whether the subscription renews automatically at the end of each billing cycle. - name: billingCycles | type: integer | description: Number of billing cycles before the subscription ends. Ignored when `autoRenewal` is `true`. | validation: minimum 1, format int32 - name: enableCustomerCancellation | type: boolean | description: Whether the buyer can cancel the subscription. - name: freeTrialPeriod | type: FreeTrialPeriod | description: Free trial period before the first billing cycle starts. Returned only when the subscription has a free trial. - name: frequency | type: SubscriptionFrequency | description: Frequency unit of the free trial period. - name: interval | type: integer | description: Number of frequency units in the free trial period. For example, frequency `MONTH` with interval `3` means a 3-month free trial. | validation: minimum 1, maximum 3650 - name: chargesDescription | type: string | description: Description of the charges that will be applied for subscription. | validation: maxLength 1000 - name: priceDescription | type: PriceDescription | description: Additional description for the price. For example, when price is 0 but additional details about the actual price are needed - "Starts at $67". - name: depositAmount | type: Price | description: Item's price amount to be charged during checkout. Relevant for items with a `paymentOption` value of `"DEPOSIT_ONLINE"`. | read-only: true - name: locations | type: array | description: Line item locations. The location's total quantity must not exceed the line item quantity. | validation: minItems 0, maxItems 5 - name: id | type: string | description: Location id in the associated owner app. | validation: format GUID - name: quantity | type: integer | description: Quantity for specific location. | validation: minimum 1, maximum 100000 - name: name | type: string | description: Location name. | read-only: true | validation: maxLength 500 - name: lineItemPrice | type: Price | description: Total price **after** catalog discounts and line item discounts. - name: taxableAddress | type: TaxableAddress | description: Address used for tax calculation. - ONE-OF: - name: addressType | type: TaxableAddressType | description: taxable address type. if this field is selected, the address is automatically resolved, and the tax is calculated accordingly. - enum: BUSINESS, BILLING, SHIPPING - name: priceUndetermined | type: boolean | description: Whether the price is not yet defined, and will be updated after the order is created. Default: `false` - name: fixedQuantity | type: boolean | description: Whether the line item quantity is fixed and cannot be changed. Default: `false` - name: decimalQuantity | type: DecimalQuantity | description: Decimal-quantity metadata. Set when the line represents a non-integer purchase (e.g. 2.75 m² of fake grass). When set, the line item must have `fixedQuantity` = true and be set with `quantity` = 1. The decimal value lives in `decimalQuantity.value`. - ONE-OF: - name: measurementUnit | type: MeasurementUnit | description: Unit the value is expressed in, selected from the standard `measurementUnit` enum. - enum: UNSPECIFIED, ML, CL, L, CBM, MG, G, KG, MM, CM, M, SQM, OZ, LB, FLOZ, PT, QT, GAL, IN, FT, YD, SQFT - name: otherUnit | type: string | description: Free-form unit name for standard units not in the `measurementUnit` enum (e.g. "hour", "minute", "session"). | validation: minLength 1, maxLength 50 - name: value | type: string | description: The decimal quantity the buyer / merchant entered. String-encoded decimal. The exact value is preserved — no rounding, no conversion to an integer. Examples: "2.75", "1.5", "0.75". | validation: decimalValue {"gt":"0","lte":"1000000000000000","maxScale":4} - name: description | type: TranslatableString | description: Human-readable, pre-formatted display string for the quantity. For example, "2.75 square meters of fake grass". Always set alongside `value`; use this directly for display rather than composing your own string from `value` and `unit`. - name: extendedFields | type: ExtendedFields | description: Custom extended fields for the line item object. [Extended fields](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/about-schema-plugin-extensions.md) must be configured in the app dashboard before they can be accessed with API calls. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). | validation: format map - name: modifierGroups | type: array | description: Modifier groups that were added to the item. | read-only: true | validation: maxItems 10 - name: changeType | type: ChangeType | description: How the line item changed compared to the subscription contract. - enum: - UNCHANGED: The value didn't change. - ADDED: The value was added. It doesn't exist in the subscription contract. - CHANGED: The value was changed. - REMOVED: The value was removed. - name: discounts | type: array | description: Discounts, each with its source and whether it's applied. | validation: maxItems 100 - name: discount | type: AppliedDiscount | description: Discount. - ONE-OF: - name: coupon | type: Coupon | description: Coupon applied by the customer. - name: id | type: string | description: Coupon GUID. - name: code | type: string | description: Coupon code. - name: name | type: string | description: Coupon name. - name: amount | type: Price | description: Total amount the coupon took off. - name: merchantDiscount | type: MerchantDiscount | description: Discount applied manually by the merchant. - ONE-OF: - name: discountReason | type: DiscountReason | description: Predefined discount reason. - enum: - UNSPECIFIED: Unknown discount reason. - EXCHANGED_ITEMS: Balance adjustment resulting from an item exchange. - BILLING_ADJUSTMENT: Proportional discount for a shortened subscription billing cycle. Applied when a subscription's billing date is moved earlier, reducing the cycle length. - name: description | type: string | description: Custom discount description as free text. | validation: maxLength 200 - name: amount | type: Price | description: Discount amount. - name: discountRule | type: DiscountRule | description: Automatic discount applied by the system based on configured discount rules. - name: id | type: string | description: Discount rule GUID | validation: format GUID - name: name | type: DiscountRuleName | description: Discount rule name - name: original | type: string | description: Original discount rule name (in site's default language). | validation: minLength 1, maxLength 256 - name: translated | type: string | description: Translated discount rule name according to buyer language. Defaults to `original` when not provided. | validation: minLength 1, maxLength 500 - name: amount | type: Price | description: Total amount the discount rule took off. - name: discountType | type: DiscountType | description: Discount type. - enum: - GLOBAL: Discount applies to the entire order. - SPECIFIC_ITEMS: Discount applies to specific items. - SHIPPING: Discount applies to shipping. For example, free shipping. - name: id | type: string | description: Discount GUID. | validation: format GUID, immutable - name: lineItemDiscounts | type: array | description: Line items the discount applies to, including the discount amount for each. | validation: maxItems 300 - name: id | type: string | description: Line item GUID. | validation: format GUID - name: totalDiscount | type: Price | description: Total discount amount for this line item. - name: source | type: SourceType | description: Source of the discount. Discounts are copied from the subscription contract, so `source` is `ORIGINAL_CONTRACT`. - enum: - ORIGINAL_CONTRACT: Copied from the subscription contract. - AUTOMATIC: Additional fee added automatically by the totals recalculation, as a result of changes in the draft subscription contract. A commit adds it to the subscription contract when its `applied` is `true`. - name: applied | type: boolean | description: Whether the discount is applied. Set to `false` when a linked line item is removed, or when its price or catalog reference options change. Exception: when `settings.specificItemsCouponBehavior` is `ITEM_SUBTOTAL_INCLUDES_DISCOUNT`, a `GLOBAL` discount stays applied when a linked line item's price or catalog reference options change, and while it's still linked to another line item. When you commit the draft subscription contract, a discount with `applied` set to `false` is removed from the subscription contract. - name: additionalFees | type: array | description: Additional fees, each with its source and whether it's applied. | validation: maxItems 100 - name: additionalFee | type: AdditionalFee | description: Additional fee. - name: code | type: string | description: Additional fee's unique code for future processing. | validation: minLength 1, maxLength 100 - name: name | type: string | description: Name of additional fee. | validation: minLength 1, maxLength 50 - name: price | type: Price | description: Additional fee's price. - name: taxInfo | type: LineItemTaxInfo | description: Represents all the relevant tax details for additional fee. - name: providerAppId | type: string | description: SPI implementer's `appId`. | validation: format GUID - name: priceBeforeTax | type: Price | description: Additional fee's price before tax. - name: priceAfterTax | type: Price | description: Additional fee's price after tax. - name: id | type: string | description: Additional fee's id. | validation: format GUID, immutable - name: lineItemIds | type: array | description: Optional - Line items associated with this additional fee. If no `lineItemIds` are provided, the fee will be associated with the whole cart/checkout/order. | validation: format GUID - name: source | type: AdditionalFeeSource | description: Specifies the entity that added the additional fee. - enum: - SERVICE_PLUGIN: The additional fee was added by an additional fee service plugin. - ITEM: The additional fee was added to the item by a catalog or custom line item. - MANUAL: The additional fee was added manually on request. - SHIPPING: The additional fee was added by the shipping provider. - PLATFORM: The additional fee was added by the Wix eCommerce platform. - name: taxableAddress | type: TaxableAddress | description: Address type tax was calculated against for this fee. - name: taxDetails | type: AdditionalFeeTaxDetails | description: Tax details of the additional fee. - name: taxable | type: boolean | description: Whether the additional fee is taxable. - name: taxGroupId | type: string | description: GUID of the tax group used to calculate tax for the additional fee. | validation: format GUID - name: source | type: SourceType | description: Source of the additional fee. - name: applied | type: boolean | description: Whether the additional fee is applied. Set to `false` when a line item linked to the additional fee is removed. When you commit the draft subscription contract, an additional fee with `applied` set to `false` is removed from the subscription contract. - name: priceSummary | type: PriceSummary | description: Price summary for the next billing cycle. Recalculated and saved each time the draft subscription contract changes and when it's committed. Retrieving a draft subscription contract with the `DRAFT` status also recalculates it. For a draft subscription contract with the `COMMITTED` status, this is the price summary applied to the subscription contract. | read-only: true - name: subtotal | type: Price | description: Subtotal of all line items, before discounts and before tax. - name: shipping | type: Price | description: Total shipping price, before discounts and before tax. - name: tax | type: Price | description: Total tax applied to the order. - name: discount | type: Price | description: Total discount amount applied to the order. - name: total | type: Price | description: Order's total price after discounts and tax. - name: totalAdditionalFees | type: Price | description: Total additional fees before tax. - name: taxInfo | type: OrderTaxInfo | description: Tax information for the next billing cycle. Recalculated and saved each time the draft subscription contract changes and when it's committed. Retrieving a draft subscription contract with the `DRAFT` status also recalculates it. For a draft subscription contract with the `COMMITTED` status, this is the tax information at the time of the commit. | read-only: true - name: totalTax | type: Price | description: Calculated tax, added from line items. - name: taxBreakdown | type: array | description: The summary of the tax breakdown for all the line items. It will hold for each tax name, the aggregated tax amount paid for it and the tax rate. | validation: minItems 0, maxItems 50 - name: taxName | type: string | description: The name of the tax against which this tax amount was calculated. | validation: maxLength 200 - name: taxType | type: string | description: The type of tax that was calculated. Depends on the company's nexus settings as well as the jurisdiction's tax laws. | validation: maxLength 200 - name: jurisdiction | type: string | description: The name of the jurisdiction in which this tax detail applies. | validation: maxLength 200 - name: jurisdictionType | type: JurisdictionType | description: The type of the jurisdiction in which this tax detail applies (e.g. Country,State,County,City,Special). - name: rate | type: string | description: The rate at which this tax detail was calculated. | validation: format DECIMAL_VALUE, decimalValue {"gte":"0","maxScale":6} - name: aggregatedTaxAmount | type: Price | description: The sum of all the tax from line items that calculated by the tax identifiers. - name: taxExempt | type: boolean | description: Whether the order is exempt from tax calculations. Default: `false` | read-only: true - name: weightUnit | type: WeightUnit | description: Weight measurement unit. | read-only: true - enum: - UNSPECIFIED_WEIGHT_UNIT: Weight unit can't be classified due to an error. - KG: Kilograms. - LB: Pounds. - name: currency | type: string | description: Currency used for the draft subscription contract's pricing, as a three-letter currency code in [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) alphabetic format. | read-only: true | validation: format CURRENCY - name: tags | type: Tags | description: Tags assigned to the draft subscription contract. - name: privateTags | type: TagList | description: Tags that require an additional permission in order to access them, typically restricted from site members and visitors. - name: tagIds | type: array | description: List of tag GUIDs. | validation: maxItems 100, maxLength 5 - name: publicTags | type: TagList | description: Tags that are exposed to anyone with access to the entity, including site members and visitors. - name: extendedFields | type: ExtendedFields | description: Custom field data for the draft subscription contract object. [Extended fields](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/about-schema-plugin-extensions.md) must be configured in the app dashboard before they can be accessed with API calls. Copied from the subscription contract when the draft subscription contract is created. Committing the draft subscription contract doesn't change the subscription contract's extended fields. - name: buyerInfoDetails | type: BuyerInfoDetails | description: Buyer information, with how it changed compared to the subscription contract. - name: buyerInfo | type: BuyerInfo | description: Buyer information for the next billing cycle. - ONE-OF: - name: visitorId | type: string | description: Visitor GUID. Returned when the buyer isn't a logged-in site member. | validation: format GUID - name: memberId | type: string | description: Member GUID. Returned when the buyer is a logged-in site member. | validation: format GUID - name: contactId | type: string | description: Contact GUID. Automatically created if one doesn't exist. For more information, see [Contacts API](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts/contact-v4/introduction.md). | validation: format GUID - name: email | type: string | description: Buyer's email address. | validation: format EMAIL - name: changeType | type: ChangeType | description: How the value changed compared to the subscription contract. - name: shippingInfoDetails | type: ShippingInfoDetails | description: Shipping info, with how it changed compared to the subscription contract. - ONE-OF: - name: changedDetails | type: ShippingInfoChangedDetails | description: Shipping info before the change. - name: shippingInfoBeforeChange | type: ShippingInformation | description: Shipping info before the change. - name: carrierId | type: string | description: App Def Id of external provider which was a source of shipping info | validation: minLength 1, maxLength 100 - name: code | type: string | description: Unique code (or GUID) of selected shipping option. For example, `"usps_std_overnight"`. | validation: minLength 1, maxLength 100 - name: title | type: string | description: Shipping option title. For example, `"USPS Standard Overnight Delivery"`, `"Standard"` or `"First-Class Package International"`. | validation: maxLength 250 - name: logistics | type: DeliveryLogistics | description: Shipping logistics. - ONE-OF: - name: shippingDestination | type: AddressWithContact | description: Shipping destination address and contact details. For pickup orders, this contains the pickup location address, not the recipient's address. - name: address | type: Address | description: Address. - name: country | type: string | description: Two-letter country code in [ISO-3166 alpha-2](https://www.iso.org/obp/ui/#search/code/) format. | validation: format COUNTRY - name: subdivision | type: string | description: Code for a subdivision (such as state, prefecture, or province) in [ISO 3166-2](https://www.iso.org/standard/72483.html) format. | validation: maxLength 50 - name: city | type: string | description: City name. | validation: maxLength 50 - name: postalCode | type: string | description: Postal or zip code. | validation: maxLength 50 - name: streetAddress | type: StreetAddress | description: Street address. - name: number | type: string | description: Street number. - name: name | type: string | description: Street name. - name: addressLine | type: string | description: Main address line (usually street name and number). | validation: maxLength 150 - name: addressLine2 | type: string | description: Free text providing more detailed address info. Usually contains apt, suite, floor. | validation: maxLength 100 - name: geocode | type: AddressLocation | description: Geocode object containing latitude and longitude coordinates. - name: latitude | type: number | description: Address latitude. | validation: format double - name: longitude | type: number | description: Address longitude. | validation: format double - name: countryFullname | type: string | description: Country's full name. | read-only: true - name: subdivisionFullname | type: string | description: Subdivision full-name. | read-only: true - name: contactDetails | type: FullAddressContactDetails | description: Contact details. - name: firstName | type: string | description: First name. | validation: maxLength 100 - name: lastName | type: string | description: Last name. | validation: maxLength 100 - name: phone | type: string | description: Phone number. | validation: format PHONE - name: company | type: string | description: Company name. | validation: maxLength 1000 - name: vatId | type: VatId | description: Tax information (for Brazil only). If GUID is provided, `vatId.type` must also be set, `UNSPECIFIED` is not allowed. - name: id | type: string | description: Customer's tax GUID. - name: type | type: VatType | description: Tax type. Supported values: + `CPF`: for individual tax payers + `CNPJ`: for corporations - enum: - UNSPECIFIED: - CPF: CPF - for individual tax payers. - CNPJ: CNPJ - for corporations - name: pickupDetails | type: PickupDetails | description: Pickup details for store pickup or pickup point orders. - name: address | type: PickupAddress | description: Pickup address. - name: country | type: string | description: Two-letter country code in [ISO-3166 alpha-2](https://www.iso.org/obp/ui/#search/code/) format. | validation: format COUNTRY - name: subdivision | type: string | description: Code for a subdivision (such as state, prefecture, or province) in [ISO 3166-2](https://www.iso.org/standard/72483.html) format. | validation: maxLength 50 - name: city | type: string | description: City name. | validation: maxLength 1000 - name: postalCode | type: string | description: Postal or zip code. | validation: maxLength 1000 - name: streetAddress | type: StreetAddress | description: Street address object, with number, name, and apartment number in separate fields. - name: addressLine | type: string | description: Main address line (usually street name and number). | validation: maxLength 1000 - name: addressLine2 | type: string | description: Free text providing more detailed address info. Usually contains apt, suite, floor. | validation: maxLength 1000 - name: countryFullname | type: string | description: Country's full name. | read-only: true - name: subdivisionFullname | type: string | description: Subdivision full-name. | read-only: true - name: pickupMethod | type: PickupMethod | description: Pickup method - enum: STORE_PICKUP, PICKUP_POINT - name: deliveryTime | type: string | description: Expected delivery time in free text. For example, `"3-5 business days"`. | validation: maxLength 500 - name: instructions | type: string | description: Instructions for the carrier. For example, `"Please knock on the door. If unanswered, please call contact number."`. | validation: maxLength 1000 - name: deliveryTimeSlot | type: DeliveryTimeSlot | description: Expected delivery time slot with start and end times. - name: from | type: string | description: Delivery slot starting time. | validation: format date-time - name: to | type: string | description: Delivery slot ending time. | validation: format date-time - name: cost | type: ShippingPrice | description: Shipping costs. - name: price | type: Price | description: Shipping price for display purposes. - name: totalPriceBeforeTax | type: Price | description: Total price of shipping after discounts (when relevant), and before tax. | read-only: true - name: totalPriceAfterTax | type: Price | description: Shipping price after all discounts (if any exist), and after tax. | read-only: true - name: taxInfo | type: LineItemTaxInfo | description: Represents all the relevant tax details for a shipping. - name: discount | type: Price | description: Shipping discount before tax. | read-only: true - name: region | type: ShippingRegion | description: Shipping region. - name: name | type: string | description: Name of shipping region. For example, `"Metropolitan London"`, or `"Outer Melbourne suburbs"`. | validation: maxLength 100 - name: shippingInfo | type: ShippingInformation | description: Shipping info for the next billing cycle. - name: changeType | type: ChangeType | description: How the value changed compared to the subscription contract. - name: billingInfoDetails | type: BillingInfoDetails | description: Billing address and contact details, with how they changed compared to the subscription contract. - ONE-OF: - name: changedDetails | type: BillingInfoChangedDetails | description: Billing address before the change. - name: billingInfoBeforeChange | type: AddressWithContact | description: Billing address and contact details before the change. - name: billingInfo | type: AddressWithContact | description: Billing address and contact details for the next billing cycle. - name: changeType | type: ChangeType | description: How the value changed compared to the subscription contract. - name: recipientInfoDetails | type: RecipientInfoDetails | description: Recipient address and contact details, with how they changed compared to the subscription contract. - ONE-OF: - name: changedDetails | type: RecipientInfoChangedDetails | description: Recipient address before the change. - name: recipientInfoBeforeChange | type: AddressWithContact | description: Recipient address and contact details before the change. - name: recipientInfo | type: AddressWithContact | description: Recipient address and contact details for the next billing cycle. - name: changeType | type: ChangeType | description: How the value changed compared to the subscription contract. - name: businessLocationDetails | type: BusinessLocationDetails | description: Business location for the next billing cycle. Copied from the subscription contract. - ONE-OF: - name: changedDetails | type: BusinessLocationChangedDetails | description: Business location before the change. - name: businessLocationBeforeChange | type: Location | description: Business location before the change. - name: id | type: string | description: Location GUID. Learn more about the [Wix Locations API](https://dev.wix.com/docs/rest/business-management/locations/introduction.md). | validation: format GUID - name: name | type: string | description: Location name. | read-only: true | validation: minLength 1, maxLength 500 - name: businessLocation | type: Location | description: Business location for the next billing cycle. - name: changeType | type: ChangeType | description: How the value changed compared to the subscription contract. - name: platformFeeSummary | type: PlatformFeeSummary | description: Summary of the platform fees of the order created at checkout, including totals by charge type and a breakdown of individual fees. Copied from the subscription contract. Not recalculated in the draft subscription contract. - name: total | type: Price | description: Total sum of all platform fees. - name: totalPassOn | type: Price | description: Total amount of platform fees with `PASS_ON` charge type. - name: totalAbsorbed | type: Price | description: Total amount of platform fees with `ABSORBED` charge type. - name: fees | type: array | description: Specific information about each platform fee. | validation: maxItems 300 - name: name | type: TranslatableString | description: Platform fee name. - name: amount | type: Price | description: Platform fee amount. - name: lineItemId | type: string | description: GUID of the line item the platform fee applies to. | validation: format GUID - name: chargeType | type: ChargeType | description: Platform fee charge type. - enum: - PASS_ON: Platform fee passed on to buyer. This type increases the order total, and is visible to the buyer and merchant as an additional fee. - ABSORBED: Platform fee absorbed by merchant. This type does not increase the order total, and is only visible to the merchant. - name: percentageRate | type: string | description: Percentage rate charged as platform fee. The fee rate percentage expressed as a decimal fraction between 0 and 1. For example, `0.05` for 5%. | validation: format DECIMAL_VALUE, decimalValue {"gt":"0","lte":"1","maxScale":4} - name: settings | type: DraftSubscriptionContractSettings | description: Draft subscription contract settings. - name: specificItemsCouponBehavior | type: SpecificItemsCouponBehavior | description: How coupons that apply to specific items were calculated for the subscription contract. - enum: - UNDEFINED_COUPON_BEHAVIOR: Coupon calculation behavior was not specified. - ITEM_SUBTOTAL_INCLUDES_DISCOUNT: Item subtotal includes coupon discount. - LEGACY_ITEM_SUBTOTAL_DOES_NOT_INCLUDE_DISCOUNT: Legacy flow. Discount is applied as to specific items after subtotal calculation. - name: subscriptionSettings | type: SubscriptionSettings | description: Billing schedule of the subscription contract. Line items that you add to the draft subscription contract get these settings. | read-only: true - name: calculationErrors | type: CalculationErrors | description: Errors returned by the totals recalculation. The draft subscription contract is saved even when the recalculation returns errors. Fix the errors before you commit. Commit Draft Subscription Contract recalculates the totals again, and fails on any calculation error except a tax calculation error for a missing subdivision. A missing billing or shipping address fails with `BILLING_ADDRESS_REQUIRED` or `SHIPPING_ADDRESS_REQUIRED`. Any other calculation error fails with `CALCULATION_ERROR`. - name: taxCalculationError | type: Details | description: Tax calculation error. Holds the error that tax calculation returned. For example, tax calculation fails when it needs a billing or shipping address, or an address subdivision, that the draft subscription contract doesn't have. - ONE-OF: - name: applicationError | type: ApplicationError | description: - name: code | type: string | description: Error code. - name: description | type: string | description: Description of the error. - name: data | type: object | description: Data related to the error. - name: validationError | type: ValidationError | description: - name: fieldViolations | type: array | description: - name: field | type: string | description: - name: description | type: string | description: - name: violatedRule | type: RuleType | description: - enum: VALIDATION, OTHER, MAX, MIN, MAX_LENGTH, MIN_LENGTH, MAX_SIZE, MIN_SIZE, FORMAT, DECIMAL_LTE, DECIMAL_GTE, DECIMAL_LT, DECIMAL_GT, DECIMAL_MAX_SCALE, INVALID_ENUM_VALUE, REQUIRED_FIELD, FIELD_NOT_ALLOWED, ONE_OF_ALIGNMENT, EXACT_LENGTH, EXACT_SIZE, REQUIRED_ONE_OF_FIELD - name: ruleName | type: string | description: applicable when violated_rule=OTHER - name: data | type: object | description: - name: systemError | type: SystemError | description: - name: errorCode | type: string | description: Error code. - name: preexistingDraftSubscriptionContract | type: boolean | description: Whether the response contains a draft subscription contract that existed before the request. `true`: Your existing draft subscription contract is returned. `false`: A new draft subscription contract is created. Possible Errors: HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: SUBSCRIPTION_CONTRACT_NOT_FOUND | Description: Couldn't find the subscription contract. HTTP Code: 409 | Status Code: ALREADY_EXISTS | Application Code: DRAFT_ALREADY_EXISTS_FOR_ANOTHER_TARGET | Description: You already have a draft subscription contract for this subscription contract with a different `target`. The error details return its GUID. Commit or delete it, or create the draft subscription contract with the same `target`. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: INVALID_NEXT_CYCLE_NUMBER | Description: `target.contractTarget.nextCycleNumber` isn't the next billing cycle of the subscription. Call [Get Subscription Contract Draftability](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/get-subscription-contract-draftability.md) and set it to `currentCycleNumber` + 1. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: CYCLE_ALREADY_STARTED | Description: The billing cycle that the draft subscription contract targets has already started. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: SUBSCRIPTION_CONTRACT_NOT_DRAFTABLE | Description: Subscription contract can't be edited. The error details list the reasons in `nonDraftableReasons`. ``` ### Examples ### Create a draft for all future cycles Creates a draft of a subscription contract that applies from billing cycle 2 onward. The draft starts with the contract's current line item, unchanged. ```curl curl -X POST \ 'https://www.wixapis.com/ecom/v1/draft-subscription-contracts' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -d '{ "subscriptionContractId": "9ac67bb1-6bd5-4205-8a1c-e2d4ca6745c1", "target": { "contractTarget": { "nextCycleNumber": 2 } } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.ecom.draftSubscriptionContracts.createDraftSubscriptionContract(subscriptionContractId, options) Description: Creates a draft subscription contract from an existing subscription contract. The draft subscription contract starts as a copy of the subscription contract's line items, discounts, additional fees, and buyer, billing, shipping, and recipient details. Discounts and additional fees that end before the next billing cycle aren't copied. The response includes the totals recalculated for the next billing cycle. A subscription contract can have 1 draft subscription contract with the `DRAFT` status at a time, whoever created it. Before you create a draft subscription contract, call [Get Subscription Contract Draftability](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/get-subscription-contract-draftability.md) to check that the subscription contract can be edited. If another identity has a draft subscription contract with the `DRAFT` status for this subscription contract, the call fails with `SUBSCRIPTION_CONTRACT_NOT_DRAFTABLE`, and the error details list `DRAFT_ALREADY_EXISTS_FOR_ANOTHER_OWNER`. When you already created a draft subscription contract for this subscription contract with the same `target`, this method returns the existing draft subscription contract instead of creating another one, and `preexistingDraftSubscriptionContract` is `true`. A draft subscription contract expires when it has no changes for 24 hours, or when the billing cycle in its `target.contractTarget.nextCycleNumber` has already started. When anyone then creates a draft subscription contract for the same subscription contract, the expired draft subscription contract is deleted and replaced. A site member can create a draft subscription contract only for a subscription contract they bought. Otherwise, the call fails with `SUBSCRIPTION_CONTRACT_NOT_DRAFTABLE`, and the error details list `NOT_SUBSCRIPTION_CONTRACT_BUYER`. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: subscriptionContractId, options.target, options.target.contractTarget.nextCycleNumber, options Method parameters: param name: options | type: CreateDraftSubscriptionContractOptions none | required: true - name: target | type: Target | description: Billing cycles that the draft subscription contract applies to. | required: true - ONE-OF: - required: true - name: contractTarget | type: ContractTarget | description: Applies the changes to the subscription contract, from the next billing cycle onward. - name: nextCycleNumber | type: integer | description: Number of the next billing cycle. Set it to `currentCycleNumber` + 1, where `currentCycleNumber` is returned by [Get Subscription Contract Draftability](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/get-subscription-contract-draftability.md). | validation: format int32 param name: subscriptionContractId | type: string | description: GUID of the subscription contract to create the draft subscription contract from. | required: true | validation: format GUID Return type: PROMISE - name: calculatedDraftSubscriptionContract | type: CalculatedDraftSubscriptionContract | description: Created draft subscription contract with recalculated totals. When you already have a draft subscription contract for this subscription contract with the same `target`, the existing draft subscription contract is returned. - name: draftSubscriptionContract | type: DraftSubscriptionContract | description: Draft subscription contract. - name: _id | type: string | description: Draft subscription contract GUID. | read-only: true | validation: format GUID - name: subscriptionContractId | type: string | description: GUID of the subscription contract that the draft subscription contract was created from. | validation: format GUID, immutable - name: target | type: Target | description: Billing cycles that the draft subscription contract applies to. - ONE-OF: - name: contractTarget | type: ContractTarget | description: Applies the changes to the subscription contract, from the next billing cycle onward. - name: nextCycleNumber | type: integer | description: Number of the next billing cycle. Set it to `currentCycleNumber` + 1, where `currentCycleNumber` is returned by [Get Subscription Contract Draftability](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/get-subscription-contract-draftability.md). | validation: format int32 - name: _createdDate | type: Date | description: Date and time the draft subscription contract was created. | read-only: true - name: _updatedDate | type: Date | description: Date and time the draft subscription contract was updated. A draft subscription contract with the `DRAFT` status expires 24 hours after this time. | read-only: true - name: createdBy | type: CreatedBy | description: Identity that created the draft subscription contract. Only this identity can retrieve, update, commit, or delete the draft subscription contract. | read-only: true - ONE-OF: - name: userId | type: string | description: User GUID. Returned when a Wix user created the draft subscription contract. | validation: format GUID - name: appId | type: string | description: App GUID. Returned when an app created the draft subscription contract. | validation: format GUID - name: memberId | type: string | description: Member GUID. Returned when a site member created the draft subscription contract. | validation: format GUID - name: identityType | type: IdentityType | description: Type of identity that created the draft subscription contract. - enum: - USER: A Wix user. - APP: An app. - MEMBER: A site member. - name: status | type: DraftStatus | description: Status of the draft subscription contract. | read-only: true - enum: - DRAFT: The draft subscription contract can be edited and committed. - COMMITTED: The draft subscription contract was committed and its changes were applied to the subscription contract. It can't be edited or deleted. - name: lineItems | type: array | description: Line items, each with how it changed compared to the subscription contract. Removed line items are returned with `changeType` set to `REMOVED`. In a draft subscription contract, `lineItem.subscriptionInfo.cycleNumber` is `0`. | validation: maxItems 100 - ONE-OF: - name: changedDetails | type: LineItemChangedDetails | description: Line item values before the change. - name: quantityBeforeChange | type: integer | description: Quantity before the change. Set only when the quantity changed. | validation: format int32 - name: priceBeforeChange | type: Price | description: Price before the change. Set only when the price changed. - name: amount | type: string | description: Amount. | validation: decimalValue {"gte":"0","lte":"1000000000000000"} - name: formattedAmount | type: string | description: Amount formatted with currency symbol. | read-only: true - name: catalogReferenceOptionsBeforeChange | type: CatalogReferenceOptionsBeforeChange | description: Catalog reference options before the change. Set only when the catalog reference options changed. - name: options | type: object | description: Catalog reference options. Absent when the line item had no options. - name: productNameBeforeChange | type: ProductNameBeforeChange | description: Product name before the change. Set only when the product name changed. - name: productName | type: ProductName | description: Product name. Absent when the line item had no product name. - name: original | type: string | description: __Required.__ Item name in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). Min: 1 character. Max: 200 characters. | validation: minLength 1, maxLength 200 - name: translated | type: string | description: Item name translated into the buyer's language. Min: 1 character. Max: 400 characters. Default: Same as `original`. | validation: minLength 1, maxLength 400 - name: descriptionLinesBeforeChange | type: DescriptionLinesBeforeChange | description: Description lines before the change. Set only when the description lines changed. - name: descriptionLines | type: array | description: Description lines. Empty when the line item had no description lines. | validation: minItems 0, maxItems 20 - ONE-OF: - name: plainText | type: PlainTextValue | description: Description line plain text value. - name: original | type: string | description: Description line plain text value in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). | validation: maxLength 600 - name: translated | type: string | description: Description line plain text value translated into the buyer's language. Default: Same as `original`. | validation: maxLength 600 - name: colorInfo | type: Color | description: Description line color value. - name: original | type: string | description: Description line color name in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). | validation: maxLength 500 - name: translated | type: string | description: Description line color name translated into the buyer's language. Default: Same as `original`. | validation: maxLength 500 - name: code | type: string | description: HEX or RGB color code for display. - name: name | type: DescriptionLineName | description: Description line name. - name: original | type: string | description: Description line name in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). | validation: maxLength 100 - name: translated | type: string | description: Description line name translated into the buyer's language. Default: Same as `original`. | validation: maxLength 200 - name: imageBeforeChange | type: ImageBeforeChange | description: Image before the change. Set only when the image changed. - name: image | type: string | description: Image. Absent when the line item had no image. - name: physicalPropertiesBeforeChange | type: PhysicalPropertiesBeforeChange | description: Physical properties before the change. Set only when the physical properties changed. - name: physicalProperties | type: PhysicalProperties | description: Physical properties. Absent when the line item had no physical properties. - name: weight | type: number | description: Line item weight. Measurement unit matches the weight unit specified in `weightUnit` in the request. - name: sku | type: string | description: Stock-keeping unit. Learn more about [SKUs](https://www.wix.com/encyclopedia/definition/stock-keeping-unit-sku). | validation: maxLength 40 - name: shippable | type: boolean | description: Whether this line item is shippable. - name: itemTypeBeforeChange | type: ItemTypeBeforeChange | description: Item type before the change. Set only when the item type changed. - name: itemType | type: ItemType | description: Item type. Absent when the line item had no item type. - ONE-OF: - name: preset | type: ItemTypePreset | description: Preset item type. - enum: UNRECOGNISED, PHYSICAL, DIGITAL, GIFT_CARD, SERVICE - name: custom | type: string | description: Custom item type. When none of the preset types are suitable, specifies the custom type. - name: fulfillerIdBeforeChange | type: FulfillerIdBeforeChange | description: Fulfiller GUID before the change. Set only when the fulfiller GUID changed. - name: fulfillerId | type: string | description: Fulfiller GUID. Absent when the line item had no fulfiller. | validation: format GUID - name: digitalFileBeforeChange | type: DigitalFileBeforeChange | description: Digital file before the change. Set only when the digital file changed. - name: digitalFile | type: DigitalFile | description: Digital file. Absent when the line item had no digital file. - name: fileId | type: string | description: GUID of the secure file in media. | validation: minLength 1, maxLength 100 - name: link | type: string | description: Link will exist after the digital links have been generated on the order. | validation: minLength 1, maxLength 2000, format WEB_URL - name: expirationDate | type: Date | description: Link expiration time and date. | read-only: true - name: priceDescriptionBeforeChange | type: PriceDescriptionBeforeChange | description: Price description before the change. Set only when the price description changed. - name: priceDescription | type: PriceDescription | description: Price description. Absent when the line item had no price description. - name: original | type: string | description: __Required.__ Price description in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). | validation: minLength 1, maxLength 100 - name: translated | type: string | description: Price description translated into the buyer's language. Default: Same as `original`. | validation: minLength 1, maxLength 100 - name: taxInfoBeforeChange | type: TaxInfoBeforeChange | description: Tax info before the change. Set only when the line item's tax group changed. - name: taxInfo | type: LineItemTaxInfo | description: Tax info. Absent when the line item had no tax info. - name: taxAmount | type: Price | description: Calculated tax, based on `taxable_amount` and `tax_rate`. - name: taxableAmount | type: Price | description: Amount for which tax is calculated. - name: taxRate | type: string | description: Tax rate %, as a decimal point. | validation: format DECIMAL_VALUE, decimalValue {"gte":"0","maxScale":6} - name: taxGroupId | type: string | description: Tax group GUID. | validation: format GUID - name: taxIncludedInPrice | type: boolean | description: Indicates whether the price already includes tax. - name: taxBreakdown | type: array | description: Tax information for a line item. | validation: maxItems 7 - name: jurisdiction | type: string | description: Jurisdiction that taxes were calculated for. For example, "New York", or "Quebec". | validation: maxLength 200 - name: rate | type: string | description: Tax rate used for this jurisdiction, as a decimal. For example, 10% tax is 0.1000. | validation: format DECIMAL_VALUE, decimalValue {"gte":"0","maxScale":6} - name: taxAmount | type: Price | description: Amount of tax calculated for this line item. - name: taxType | type: string | description: The type of tax that was calculated. Depends on the jurisdiction's tax laws. For example, "Sales Tax", "Income Tax", "Value Added Tax", etc. | validation: maxLength 200 - name: taxName | type: string | description: The name of the tax against which this tax amount was calculated. For example, "NY State Sales Tax", "Quebec GST", etc. This name should be explicit enough to allow the merchant to understand what tax was calculated. | validation: maxLength 200 - name: jurisdictionType | type: JurisdictionType | description: Type of jurisdiction that taxes were calculated for. - enum: UNDEFINED, COUNTRY, STATE, COUNTY, CITY, SPECIAL - name: nonTaxableAmount | type: Price | description: Non-taxable amount of the line item price. - name: taxableAmount | type: Price | description: Taxable amount of the line item price. - name: inventoryAppIdBeforeChange | type: InventoryAppIdBeforeChange | description: Inventory app GUID before the change. Set only when the inventory app GUID changed. - name: inventoryAppId | type: string | description: Inventory app GUID. Absent when the line item had no inventory app. | validation: format GUID - name: modifierGroupsBeforeChange | type: ModifierGroupsBeforeChange | description: Modifier groups before the change. Set only when the modifier groups changed. - name: modifierGroups | type: array | description: Modifier groups. Empty when the line item had no modifier groups. | validation: maxItems 10 - name: _id | type: string | description: Modifier group GUID. | validation: minLength 1, maxLength 36 - name: name | type: TranslatableString | description: Modifier group name. - name: original | type: string | description: __Required.__ String in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). Min: 1 character. Max: 200 characters. | validation: minLength 1, maxLength 200 - name: translated | type: string | description: String translated into the buyer's language. Min: 1 character. Max: 400 characters. Default: Same as `original`. | validation: minLength 1, maxLength 400 - name: modifiers | type: array | description: List of modifiers in this group. | validation: minItems 1, maxItems 10 - name: _id | type: string | description: Modifier GUID. | validation: minLength 1, maxLength 36 - name: quantity | type: integer | description: The quantity of this modifier. | validation: minimum 1, maximum 100000, format int32 - name: label | type: TranslatableString | description: Primary display label for the modifier. - name: details | type: TranslatableString | description: Additional details. - name: price | type: Price | description: The price of the modifier. - name: priceUndeterminedBeforeChange | type: PriceUndeterminedBeforeChange | description: Price undetermined flag before the change. Set only when the price undetermined flag changed. - name: priceUndetermined | type: boolean | description: Whether the price of the line item was undetermined. - name: lineItem | type: OrderLineItem | description: Line item. - name: _id | type: string | description: Line item GUID. | validation: immutable - name: productName | type: ProductName | description: Item name. + Stores - `product.name` + Bookings - `service.info.name` + Events - `ticket.name` - name: catalogReference | type: CatalogReference | description: References to the line item's origin catalog. Empty for custom line items. - name: catalogItemId | type: string | description: GUID of the item within the catalog it belongs to. | validation: minLength 1, maxLength 36 - name: appId | type: string | description: GUID of the app providing the catalog. You can get your app's GUID from its page in the [app dashboard](https://dev.wix.com/dc3/my-apps/). For items from Wix catalogs, the following values always apply: + Wix Stores: `"215238eb-22a5-4c36-9e7b-e7c08025e04e"` + Wix Bookings: `"13d21c63-b5ec-5912-8397-c3a5ddb27a97"` + Wix Restaurants: `"9a5d83fd-8570-482e-81ab-cfa88942ee60"` | validation: minLength 1 - name: options | type: object | description: Additional item details in `key:value` pairs. Use this optional field for more specificity with item selection. The values of the `options` field differ depending on which catalog is providing the items. For Wix Stores products, learn more about integrating with [Catalog V3](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/e-commerce-integration.md) or [Catalog V1](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v1/catalog/e-commerce-integration.md), depending on [the version the site uses](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-versioning/introduction.md). - name: quantity | type: integer | description: Line item quantity. | validation: minimum 1, maximum 100000 - name: totalDiscount | type: Price | description: Total discount for this line item's entire quantity. | read-only: true - name: descriptionLines | type: array | description: Line item description lines. Used for display purposes for the cart, checkout and order. | validation: minItems 0, maxItems 20 - name: image | type: string | description: Line item image. - name: physicalProperties | type: PhysicalProperties | description: Physical properties of the item. When relevant, contains information such as SKU and item weight. - name: itemType | type: ItemType | description: Item type. Either a preset type or custom. - name: fulfillerId | type: string | description: Fulfiller GUID. Field is empty when the line item is self-fulfilled. To get fulfillment information, pass the order GUID to [List Fulfillments For Single Order](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-fulfillments/list-fulfillments-for-single-order.md). | validation: format GUID - name: refundQuantity | type: integer | description: Number of items that were refunded. | validation: minimum 0, maximum 100000, format int32 - name: restockQuantity | type: integer | description: Number of items restocked. For a per-location breakdown, see `restockLocations`. | validation: minimum 0, maximum 100000, format int32 - name: price | type: Price | description: Line item price after line item discounts for display purposes. - name: priceBeforeDiscounts | type: Price | description: Line item price before line item discounts for display purposes. Defaults to `price` when not provided. | read-only: true - name: totalPriceBeforeTax | type: Price | description: Total price after discounts, and before tax. | read-only: true - name: totalPriceAfterTax | type: Price | description: Total price after all discounts and tax. | read-only: true - name: paymentOption | type: PaymentOptionType | description: Type of selected payment option for current item. Default: `FULL_PAYMENT_ONLINE` - enum: - FULL_PAYMENT_ONLINE: The entire payment for this item happens as part of the checkout. - FULL_PAYMENT_OFFLINE: The entire payment for this item happens after checkout. For example, when using cash, check, or other offline payment methods. - MEMBERSHIP: Payment for this item is done by charging a membership. Any remaining amount not covered by the membership, such as item modifiers, is paid online. - DEPOSIT_ONLINE: Partial payment to be paid upfront during checkout. The initial amount to be paid for each line item is specified in `depositAmount`. - MEMBERSHIP_OFFLINE: Payment for this item can only be done by charging a membership and must be manually redeemed in the dashboard by the site admin. When selected, `price` is `0`. - MEMBERSHIP_ONLINE_WITH_OFFLINE_REMAINDER: Item price is charged to online membership. Any remaining amount not covered by the membership, such as item modifiers, is paid offline. - name: taxInfo | type: LineItemTaxInfo | description: Represents all the relevant tax details for a specific line item. - name: digitalFile | type: DigitalFile | description: Digital file identifier, relevant only for items with type DIGITAL. - name: subscriptionInfo | type: SubscriptionInfo | description: Subscription info. - name: _id | type: string | description: Subscription GUID. For a subscription bought through Wix eCommerce, this is the GUID of the subscription contract the order was created from. To retrieve the subscription contract, call [Get Subscription Contract](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/subscription-contracts/get-subscription-contract.md). | validation: format GUID - name: cycleNumber | type: integer | description: Billing cycle the order is for. For example, `3` for the third billing cycle of a subscription. When a subscription starts with a free trial, the order created at checkout is for cycle `0`. | validation: minimum 0 - name: subscriptionSettings | type: SubscriptionSettings | description: Subscription detailed information. - name: frequency | type: SubscriptionFrequency | description: Frequency unit of the billing cycle. - enum: UNDEFINED, DAY, WEEK, MONTH, YEAR - name: interval | type: integer | description: Number of frequency units in a billing cycle. For example, frequency `MONTH` with interval `3` means billing every 3 months. | validation: minimum 1, maximum 3650, format int32 - name: autoRenewal | type: boolean | description: Whether the subscription renews automatically at the end of each billing cycle. - name: billingCycles | type: integer | description: Number of billing cycles before the subscription ends. Ignored when `autoRenewal` is `true`. | validation: minimum 1, format int32 - name: enableCustomerCancellation | type: boolean | description: Whether the buyer can cancel the subscription. - name: freeTrialPeriod | type: FreeTrialPeriod | description: Free trial period before the first billing cycle starts. Returned only when the subscription has a free trial. - name: frequency | type: SubscriptionFrequency | description: Frequency unit of the free trial period. - name: interval | type: integer | description: Number of frequency units in the free trial period. For example, frequency `MONTH` with interval `3` means a 3-month free trial. | validation: minimum 1, maximum 3650 - name: chargesDescription | type: string | description: Description of the charges that will be applied for subscription. | validation: maxLength 1000 - name: priceDescription | type: PriceDescription | description: Additional description for the price. For example, when price is 0 but additional details about the actual price are needed - "Starts at $67". - name: depositAmount | type: Price | description: Item's price amount to be charged during checkout. Relevant for items with a `paymentOption` value of `"DEPOSIT_ONLINE"`. | read-only: true - name: locations | type: array | description: Line item locations. The location's total quantity must not exceed the line item quantity. | validation: minItems 0, maxItems 5 - name: _id | type: string | description: Location id in the associated owner app. | validation: format GUID - name: quantity | type: integer | description: Quantity for specific location. | validation: minimum 1, maximum 100000 - name: name | type: string | description: Location name. | read-only: true | validation: maxLength 500 - name: lineItemPrice | type: Price | description: Total price **after** catalog discounts and line item discounts. - name: taxableAddress | type: TaxableAddress | description: Address used for tax calculation. - ONE-OF: - name: addressType | type: TaxableAddressType | description: taxable address type. if this field is selected, the address is automatically resolved, and the tax is calculated accordingly. - enum: BUSINESS, BILLING, SHIPPING - name: priceUndetermined | type: boolean | description: Whether the price is not yet defined, and will be updated after the order is created. Default: `false` - name: fixedQuantity | type: boolean | description: Whether the line item quantity is fixed and cannot be changed. Default: `false` - name: decimalQuantity | type: DecimalQuantity | description: Decimal-quantity metadata. Set when the line represents a non-integer purchase (e.g. 2.75 m² of fake grass). When set, the line item must have `fixedQuantity` = true and be set with `quantity` = 1. The decimal value lives in `decimalQuantity.value`. - ONE-OF: - name: measurementUnit | type: MeasurementUnit | description: Unit the value is expressed in, selected from the standard `measurementUnit` enum. - enum: UNSPECIFIED, ML, CL, L, CBM, MG, G, KG, MM, CM, M, SQM, OZ, LB, FLOZ, PT, QT, GAL, IN, FT, YD, SQFT - name: otherUnit | type: string | description: Free-form unit name for standard units not in the `measurementUnit` enum (e.g. "hour", "minute", "session"). | validation: minLength 1, maxLength 50 - name: value | type: string | description: The decimal quantity the buyer / merchant entered. String-encoded decimal. The exact value is preserved — no rounding, no conversion to an integer. Examples: "2.75", "1.5", "0.75". | validation: decimalValue {"gt":"0","lte":"1000000000000000","maxScale":4} - name: description | type: TranslatableString | description: Human-readable, pre-formatted display string for the quantity. For example, "2.75 square meters of fake grass". Always set alongside `value`; use this directly for display rather than composing your own string from `value` and `unit`. - name: extendedFields | type: ExtendedFields | description: Custom extended fields for the line item object. [Extended fields](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/about-schema-plugin-extensions.md) must be configured in the app dashboard before they can be accessed with API calls. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). | validation: format map - name: modifierGroups | type: array | description: Modifier groups that were added to the item. | read-only: true | validation: maxItems 10 - name: changeType | type: ChangeType | description: How the line item changed compared to the subscription contract. - enum: - UNCHANGED: The value didn't change. - ADDED: The value was added. It doesn't exist in the subscription contract. - CHANGED: The value was changed. - REMOVED: The value was removed. - name: discounts | type: array | description: Discounts, each with its source and whether it's applied. | validation: maxItems 100 - name: discount | type: AppliedDiscount | description: Discount. - ONE-OF: - name: coupon | type: Coupon | description: Coupon applied by the customer. - name: _id | type: string | description: Coupon GUID. - name: code | type: string | description: Coupon code. - name: name | type: string | description: Coupon name. - name: amount | type: Price | description: Total amount the coupon took off. - name: merchantDiscount | type: MerchantDiscount | description: Discount applied manually by the merchant. - ONE-OF: - name: discountReason | type: DiscountReason | description: Predefined discount reason. - enum: - UNSPECIFIED: Unknown discount reason. - EXCHANGED_ITEMS: Balance adjustment resulting from an item exchange. - BILLING_ADJUSTMENT: Proportional discount for a shortened subscription billing cycle. Applied when a subscription's billing date is moved earlier, reducing the cycle length. - name: description | type: string | description: Custom discount description as free text. | validation: maxLength 200 - name: amount | type: Price | description: Discount amount. - name: discountRule | type: DiscountRule | description: Automatic discount applied by the system based on configured discount rules. - name: _id | type: string | description: Discount rule GUID | validation: format GUID - name: name | type: DiscountRuleName | description: Discount rule name - name: original | type: string | description: Original discount rule name (in site's default language). | validation: minLength 1, maxLength 256 - name: translated | type: string | description: Translated discount rule name according to buyer language. Defaults to `original` when not provided. | validation: minLength 1, maxLength 500 - name: amount | type: Price | description: Total amount the discount rule took off. - name: discountType | type: DiscountType | description: Discount type. - enum: - GLOBAL: Discount applies to the entire order. - SPECIFIC_ITEMS: Discount applies to specific items. - SHIPPING: Discount applies to shipping. For example, free shipping. - name: _id | type: string | description: Discount GUID. | validation: format GUID, immutable - name: lineItemDiscounts | type: array | description: Line items the discount applies to, including the discount amount for each. | validation: maxItems 300 - name: _id | type: string | description: Line item GUID. | validation: format GUID - name: totalDiscount | type: Price | description: Total discount amount for this line item. - name: source | type: SourceType | description: Source of the discount. Discounts are copied from the subscription contract, so `source` is `ORIGINAL_CONTRACT`. - enum: - ORIGINAL_CONTRACT: Copied from the subscription contract. - AUTOMATIC: Additional fee added automatically by the totals recalculation, as a result of changes in the draft subscription contract. A commit adds it to the subscription contract when its `applied` is `true`. - name: applied | type: boolean | description: Whether the discount is applied. Set to `false` when a linked line item is removed, or when its price or catalog reference options change. Exception: when `settings.specificItemsCouponBehavior` is `ITEM_SUBTOTAL_INCLUDES_DISCOUNT`, a `GLOBAL` discount stays applied when a linked line item's price or catalog reference options change, and while it's still linked to another line item. When you commit the draft subscription contract, a discount with `applied` set to `false` is removed from the subscription contract. - name: additionalFees | type: array | description: Additional fees, each with its source and whether it's applied. | validation: maxItems 100 - name: additionalFee | type: AdditionalFee | description: Additional fee. - name: code | type: string | description: Additional fee's unique code for future processing. | validation: minLength 1, maxLength 100 - name: name | type: string | description: Name of additional fee. | validation: minLength 1, maxLength 50 - name: price | type: Price | description: Additional fee's price. - name: taxInfo | type: LineItemTaxInfo | description: Represents all the relevant tax details for additional fee. - name: providerAppId | type: string | description: SPI implementer's `appId`. | validation: format GUID - name: priceBeforeTax | type: Price | description: Additional fee's price before tax. - name: priceAfterTax | type: Price | description: Additional fee's price after tax. - name: _id | type: string | description: Additional fee's id. | validation: format GUID, immutable - name: lineItemIds | type: array | description: Optional - Line items associated with this additional fee. If no `lineItemIds` are provided, the fee will be associated with the whole cart/checkout/order. | validation: format GUID - name: source | type: AdditionalFeeSource | description: Specifies the entity that added the additional fee. - enum: - SERVICE_PLUGIN: The additional fee was added by an additional fee service plugin. - ITEM: The additional fee was added to the item by a catalog or custom line item. - MANUAL: The additional fee was added manually on request. - SHIPPING: The additional fee was added by the shipping provider. - PLATFORM: The additional fee was added by the Wix eCommerce platform. - name: taxableAddress | type: TaxableAddress | description: Address type tax was calculated against for this fee. - name: taxDetails | type: AdditionalFeeTaxDetails | description: Tax details of the additional fee. - name: taxable | type: boolean | description: Whether the additional fee is taxable. - name: taxGroupId | type: string | description: GUID of the tax group used to calculate tax for the additional fee. | validation: format GUID - name: source | type: SourceType | description: Source of the additional fee. - name: applied | type: boolean | description: Whether the additional fee is applied. Set to `false` when a line item linked to the additional fee is removed. When you commit the draft subscription contract, an additional fee with `applied` set to `false` is removed from the subscription contract. - name: priceSummary | type: PriceSummary | description: Price summary for the next billing cycle. Recalculated and saved each time the draft subscription contract changes and when it's committed. Retrieving a draft subscription contract with the `DRAFT` status also recalculates it. For a draft subscription contract with the `COMMITTED` status, this is the price summary applied to the subscription contract. | read-only: true - name: subtotal | type: Price | description: Subtotal of all line items, before discounts and before tax. - name: shipping | type: Price | description: Total shipping price, before discounts and before tax. - name: tax | type: Price | description: Total tax applied to the order. - name: discount | type: Price | description: Total discount amount applied to the order. - name: total | type: Price | description: Order's total price after discounts and tax. - name: totalAdditionalFees | type: Price | description: Total additional fees before tax. - name: taxInfo | type: OrderTaxInfo | description: Tax information for the next billing cycle. Recalculated and saved each time the draft subscription contract changes and when it's committed. Retrieving a draft subscription contract with the `DRAFT` status also recalculates it. For a draft subscription contract with the `COMMITTED` status, this is the tax information at the time of the commit. | read-only: true - name: totalTax | type: Price | description: Calculated tax, added from line items. - name: taxBreakdown | type: array | description: The summary of the tax breakdown for all the line items. It will hold for each tax name, the aggregated tax amount paid for it and the tax rate. | validation: minItems 0, maxItems 50 - name: taxName | type: string | description: The name of the tax against which this tax amount was calculated. | validation: maxLength 200 - name: taxType | type: string | description: The type of tax that was calculated. Depends on the company's nexus settings as well as the jurisdiction's tax laws. | validation: maxLength 200 - name: jurisdiction | type: string | description: The name of the jurisdiction in which this tax detail applies. | validation: maxLength 200 - name: jurisdictionType | type: JurisdictionType | description: The type of the jurisdiction in which this tax detail applies (e.g. Country,State,County,City,Special). - name: rate | type: string | description: The rate at which this tax detail was calculated. | validation: format DECIMAL_VALUE, decimalValue {"gte":"0","maxScale":6} - name: aggregatedTaxAmount | type: Price | description: The sum of all the tax from line items that calculated by the tax identifiers. - name: taxExempt | type: boolean | description: Whether the order is exempt from tax calculations. Default: `false` | read-only: true - name: weightUnit | type: WeightUnit | description: Weight measurement unit. | read-only: true - enum: - UNSPECIFIED_WEIGHT_UNIT: Weight unit can't be classified due to an error. - KG: Kilograms. - LB: Pounds. - name: currency | type: string | description: Currency used for the draft subscription contract's pricing, as a three-letter currency code in [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) alphabetic format. | read-only: true | validation: format CURRENCY - name: tags | type: Tags | description: Tags assigned to the draft subscription contract. - name: privateTags | type: TagList | description: Tags that require an additional permission in order to access them, typically restricted from site members and visitors. - name: tagIds | type: array | description: List of tag GUIDs. | validation: maxItems 100, maxLength 5 - name: publicTags | type: TagList | description: Tags that are exposed to anyone with access to the entity, including site members and visitors. - name: extendedFields | type: ExtendedFields | description: Custom field data for the draft subscription contract object. [Extended fields](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/about-schema-plugin-extensions.md) must be configured in the app dashboard before they can be accessed with API calls. Copied from the subscription contract when the draft subscription contract is created. Committing the draft subscription contract doesn't change the subscription contract's extended fields. - name: buyerInfoDetails | type: BuyerInfoDetails | description: Buyer information, with how it changed compared to the subscription contract. - name: buyerInfo | type: BuyerInfo | description: Buyer information for the next billing cycle. - ONE-OF: - name: visitorId | type: string | description: Visitor GUID. Returned when the buyer isn't a logged-in site member. | validation: format GUID - name: memberId | type: string | description: Member GUID. Returned when the buyer is a logged-in site member. | validation: format GUID - name: contactId | type: string | description: Contact GUID. Automatically created if one doesn't exist. For more information, see [Contacts API](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts/contact-v4/introduction.md). | validation: format GUID - name: email | type: string | description: Buyer's email address. | validation: format EMAIL - name: changeType | type: ChangeType | description: How the value changed compared to the subscription contract. - name: shippingInfoDetails | type: ShippingInfoDetails | description: Shipping info, with how it changed compared to the subscription contract. - ONE-OF: - name: changedDetails | type: ShippingInfoChangedDetails | description: Shipping info before the change. - name: shippingInfoBeforeChange | type: ShippingInformation | description: Shipping info before the change. - name: carrierId | type: string | description: App Def Id of external provider which was a source of shipping info | validation: minLength 1, maxLength 100 - name: code | type: string | description: Unique code (or GUID) of selected shipping option. For example, `"usps_std_overnight"`. | validation: minLength 1, maxLength 100 - name: title | type: string | description: Shipping option title. For example, `"USPS Standard Overnight Delivery"`, `"Standard"` or `"First-Class Package International"`. | validation: maxLength 250 - name: logistics | type: DeliveryLogistics | description: Shipping logistics. - ONE-OF: - name: shippingDestination | type: AddressWithContact | description: Shipping destination address and contact details. For pickup orders, this contains the pickup location address, not the recipient's address. - name: address | type: Address | description: Address. - name: streetAddress | type: StreetAddress | description: none - name: name | type: string | description: none - name: number | type: string | description: none - name: city | type: string | description: none - name: subdivision | type: string | description: none - name: country | type: string | description: none - name: postalCode | type: string | description: none - name: addressLine2 | type: string | description: none - name: contactDetails | type: FullAddressContactDetails | description: Contact details. - name: firstName | type: string | description: First name. | validation: maxLength 100 - name: lastName | type: string | description: Last name. | validation: maxLength 100 - name: phone | type: string | description: Phone number. | validation: format PHONE - name: company | type: string | description: Company name. | validation: maxLength 1000 - name: vatId | type: VatId | description: Tax information (for Brazil only). If GUID is provided, `vatId.type` must also be set, `UNSPECIFIED` is not allowed. - name: _id | type: string | description: Customer's tax GUID. - name: type | type: VatType | description: Tax type. Supported values: + `CPF`: for individual tax payers + `CNPJ`: for corporations - enum: - UNSPECIFIED: - CPF: CPF - for individual tax payers. - CNPJ: CNPJ - for corporations - name: pickupDetails | type: PickupDetails | description: Pickup details for store pickup or pickup point orders. - name: address | type: PickupAddress | description: Pickup address. - name: streetAddress | type: StreetAddress | description: none - name: city | type: string | description: none - name: subdivision | type: string | description: none - name: country | type: string | description: none - name: postalCode | type: string | description: none - name: addressLine2 | type: string | description: none - name: pickupMethod | type: PickupMethod | description: Pickup method - enum: STORE_PICKUP, PICKUP_POINT - name: deliveryTime | type: string | description: Expected delivery time in free text. For example, `"3-5 business days"`. | validation: maxLength 500 - name: instructions | type: string | description: Instructions for the carrier. For example, `"Please knock on the door. If unanswered, please call contact number."`. | validation: maxLength 1000 - name: deliveryTimeSlot | type: DeliveryTimeSlot | description: Expected delivery time slot with start and end times. - name: from | type: Date | description: Delivery slot starting time. - name: to | type: Date | description: Delivery slot ending time. - name: cost | type: ShippingPrice | description: Shipping costs. - name: price | type: Price | description: Shipping price for display purposes. - name: totalPriceBeforeTax | type: Price | description: Total price of shipping after discounts (when relevant), and before tax. | read-only: true - name: totalPriceAfterTax | type: Price | description: Shipping price after all discounts (if any exist), and after tax. | read-only: true - name: taxInfo | type: LineItemTaxInfo | description: Represents all the relevant tax details for a shipping. - name: discount | type: Price | description: Shipping discount before tax. | read-only: true - name: region | type: ShippingRegion | description: Shipping region. - name: name | type: string | description: Name of shipping region. For example, `"Metropolitan London"`, or `"Outer Melbourne suburbs"`. | validation: maxLength 100 - name: shippingInfo | type: ShippingInformation | description: Shipping info for the next billing cycle. - name: changeType | type: ChangeType | description: How the value changed compared to the subscription contract. - name: billingInfoDetails | type: BillingInfoDetails | description: Billing address and contact details, with how they changed compared to the subscription contract. - ONE-OF: - name: changedDetails | type: BillingInfoChangedDetails | description: Billing address before the change. - name: billingInfoBeforeChange | type: AddressWithContact | description: Billing address and contact details before the change. - name: billingInfo | type: AddressWithContact | description: Billing address and contact details for the next billing cycle. - name: changeType | type: ChangeType | description: How the value changed compared to the subscription contract. - name: recipientInfoDetails | type: RecipientInfoDetails | description: Recipient address and contact details, with how they changed compared to the subscription contract. - ONE-OF: - name: changedDetails | type: RecipientInfoChangedDetails | description: Recipient address before the change. - name: recipientInfoBeforeChange | type: AddressWithContact | description: Recipient address and contact details before the change. - name: recipientInfo | type: AddressWithContact | description: Recipient address and contact details for the next billing cycle. - name: changeType | type: ChangeType | description: How the value changed compared to the subscription contract. - name: businessLocationDetails | type: BusinessLocationDetails | description: Business location for the next billing cycle. Copied from the subscription contract. - ONE-OF: - name: changedDetails | type: BusinessLocationChangedDetails | description: Business location before the change. - name: businessLocationBeforeChange | type: Location | description: Business location before the change. - name: _id | type: string | description: Location GUID. Learn more about the [Wix Locations API](https://dev.wix.com/docs/rest/business-management/locations/introduction.md). | validation: format GUID - name: name | type: string | description: Location name. | read-only: true | validation: minLength 1, maxLength 500 - name: businessLocation | type: Location | description: Business location for the next billing cycle. - name: changeType | type: ChangeType | description: How the value changed compared to the subscription contract. - name: platformFeeSummary | type: PlatformFeeSummary | description: Summary of the platform fees of the order created at checkout, including totals by charge type and a breakdown of individual fees. Copied from the subscription contract. Not recalculated in the draft subscription contract. - name: total | type: Price | description: Total sum of all platform fees. - name: totalPassOn | type: Price | description: Total amount of platform fees with `PASS_ON` charge type. - name: totalAbsorbed | type: Price | description: Total amount of platform fees with `ABSORBED` charge type. - name: fees | type: array | description: Specific information about each platform fee. | validation: maxItems 300 - name: name | type: TranslatableString | description: Platform fee name. - name: amount | type: Price | description: Platform fee amount. - name: lineItemId | type: string | description: GUID of the line item the platform fee applies to. | validation: format GUID - name: chargeType | type: ChargeType | description: Platform fee charge type. - enum: - PASS_ON: Platform fee passed on to buyer. This type increases the order total, and is visible to the buyer and merchant as an additional fee. - ABSORBED: Platform fee absorbed by merchant. This type does not increase the order total, and is only visible to the merchant. - name: percentageRate | type: string | description: Percentage rate charged as platform fee. The fee rate percentage expressed as a decimal fraction between 0 and 1. For example, `0.05` for 5%. | validation: format DECIMAL_VALUE, decimalValue {"gt":"0","lte":"1","maxScale":4} - name: settings | type: DraftSubscriptionContractSettings | description: Draft subscription contract settings. - name: specificItemsCouponBehavior | type: SpecificItemsCouponBehavior | description: How coupons that apply to specific items were calculated for the subscription contract. - enum: - UNDEFINED_COUPON_BEHAVIOR: Coupon calculation behavior was not specified. - ITEM_SUBTOTAL_INCLUDES_DISCOUNT: Item subtotal includes coupon discount. - LEGACY_ITEM_SUBTOTAL_DOES_NOT_INCLUDE_DISCOUNT: Legacy flow. Discount is applied as to specific items after subtotal calculation. - name: subscriptionSettings | type: SubscriptionSettings | description: Billing schedule of the subscription contract. Line items that you add to the draft subscription contract get these settings. | read-only: true - name: calculationErrors | type: CalculationErrors | description: Errors returned by the totals recalculation. The draft subscription contract is saved even when the recalculation returns errors. Fix the errors before you commit. Commit Draft Subscription Contract recalculates the totals again, and fails on any calculation error except a tax calculation error for a missing subdivision. A missing billing or shipping address fails with `BILLING_ADDRESS_REQUIRED` or `SHIPPING_ADDRESS_REQUIRED`. Any other calculation error fails with `CALCULATION_ERROR`. - name: taxCalculationError | type: Details | description: Tax calculation error. Holds the error that tax calculation returned. For example, tax calculation fails when it needs a billing or shipping address, or an address subdivision, that the draft subscription contract doesn't have. - ONE-OF: - name: applicationError | type: ApplicationError | description: - name: code | type: string | description: Error code. - name: description | type: string | description: Description of the error. - name: data | type: object | description: Data related to the error. - name: validationError | type: ValidationError | description: - name: fieldViolations | type: array | description: - name: field | type: string | description: - name: description | type: string | description: - name: violatedRule | type: RuleType | description: - enum: VALIDATION, OTHER, MAX, MIN, MAX_LENGTH, MIN_LENGTH, MAX_SIZE, MIN_SIZE, FORMAT, DECIMAL_LTE, DECIMAL_GTE, DECIMAL_LT, DECIMAL_GT, DECIMAL_MAX_SCALE, INVALID_ENUM_VALUE, REQUIRED_FIELD, FIELD_NOT_ALLOWED, ONE_OF_ALIGNMENT, EXACT_LENGTH, EXACT_SIZE, REQUIRED_ONE_OF_FIELD - name: ruleName | type: string | description: applicable when violated_rule=OTHER - name: data | type: object | description: - name: systemError | type: SystemError | description: - name: errorCode | type: string | description: Error code. - name: preexistingDraftSubscriptionContract | type: boolean | description: Whether the response contains a draft subscription contract that existed before the request. `true`: Your existing draft subscription contract is returned. `false`: A new draft subscription contract is created. Possible Errors: HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: SUBSCRIPTION_CONTRACT_NOT_FOUND | Description: Couldn't find the subscription contract. HTTP Code: 409 | Status Code: ALREADY_EXISTS | Application Code: DRAFT_ALREADY_EXISTS_FOR_ANOTHER_TARGET | Description: You already have a draft subscription contract for this subscription contract with a different `target`. The error details return its GUID. Commit or delete it, or create the draft subscription contract with the same `target`. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: INVALID_NEXT_CYCLE_NUMBER | Description: `target.contractTarget.nextCycleNumber` isn't the next billing cycle of the subscription. Call [Get Subscription Contract Draftability](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/get-subscription-contract-draftability.md) and set it to `currentCycleNumber` + 1. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: CYCLE_ALREADY_STARTED | Description: The billing cycle that the draft subscription contract targets has already started. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: SUBSCRIPTION_CONTRACT_NOT_DRAFTABLE | Description: Subscription contract can't be edited. The error details list the reasons in `nonDraftableReasons`. ``` ### Examples ### Create a draft for all future cycles Creates a draft of a subscription contract that applies from billing cycle 2 onward. The draft starts with the contract's current line item, unchanged. ```javascript import { draftSubscriptionContracts } from "@wix/ecom"; async function createDraftSubscriptionContract() { const response = await draftSubscriptionContracts.createDraftSubscriptionContract( "9ac67bb1-6bd5-4205-8a1c-e2d4ca6745c1", { target: { contractTarget: { nextCycleNumber: 2, }, }, }, ); } ``` ### createDraftSubscriptionContract (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { draftSubscriptionContracts } from '@wix/ecom'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { draftSubscriptionContracts }, // Include the auth strategy and host as relevant }); async function createDraftSubscriptionContract(subscriptionContractId,options) { const response = await myWixClient.draftSubscriptionContracts.createDraftSubscriptionContract(subscriptionContractId,options); }; ``` ---