> 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 # QuerySubscriptionContracts # Package: subscriptions # Namespace: SubscriptionContracts # Method link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/subscription-contracts/query-subscription-contracts.md ## Permission Scopes: Read subscription contracts: SCOPE.ECOM.SUBSCRIPTION-CONTRACT-READ ## Introduction Retrieves a list of up to 100 subscription contracts, given the provided paging, filtering, and sorting. Query Subscription Contracts runs with these defaults, which you can override: - `id` is sorted in `ASC` order - `cursorPaging.limit` is `50` You can filter and sort by `id` and `buyerInfo.contactId`. For example, to retrieve all of a buyer's subscription contracts, filter by `buyerInfo.contactId`. To learn about working with Query methods, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md) and [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md). --- ## REST API ### Schema ``` Method: querySubscriptionContracts Description: Retrieves a list of up to 100 subscription contracts, given the provided paging, filtering, and sorting. Query Subscription Contracts runs with these defaults, which you can override: - `id` is sorted in `ASC` order - `cursorPaging.limit` is `50` You can filter and sort by `id` and `buyerInfo.contactId`. For example, to retrieve all of a buyer's subscription contracts, filter by `buyerInfo.contactId`. To learn about working with Query methods, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md) and [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md). URL: https://www.wixapis.com/ecom/subscription-contracts/v1/subscription-contracts/query Method: POST Method parameters: param name: query | type: CursorQuery - name: cursorPaging | type: CursorPaging | description: Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not `filter` or `sort`. - name: limit | type: integer | description: Maximum number of items to return in the results. | validation: minimum 0, maximum 100, format int32 - name: cursor | type: string | description: Pointer to the next or previous page in the list of results. Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. | validation: maxLength 16000 - name: filter | type: object | description: Filter object. See [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md) for more information. Supported properties: `id`, `buyerInfo.contactId` - name: sort | type: array | description: Sort object in the following format: `[{"fieldName":"sortField1","order":"ASC"},{"fieldName":"sortField2","order":"DESC"}]` Learn more about [sorting](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md). | validation: maxItems 5 - name: fieldName | type: string | description: Field to sort by. Supported properties: `id`, `buyerInfo.contactId` | validation: maxLength 512 - name: order | type: SortOrder | description: Sort order. Use `ASC` for ascending order or `DESC` for descending order. Default: `ASC` - enum: ASC, DESC Query fields: - field: id | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte, $startsWith | sort: ASC, DESC | aggregatable: undefined | searchable: undefined - field: buyerInfo.contactId | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte, $startsWith | sort: ASC, DESC | aggregatable: undefined | searchable: undefined Return type: QuerySubscriptionContractsResponse - name: subscriptionContracts | type: array | description: Retrieved subscription contracts. - name: id | type: string | description: Subscription contract GUID. | read-only: true | validation: format GUID - name: revision | type: string | description: Revision number, which increments by 1 each time the subscription contract is updated. | read-only: true | validation: format int64 - name: createdDate | type: string | description: Date and time the subscription contract was created. | read-only: true | validation: format date-time - name: updatedDate | type: string | description: Date and time the subscription contract was last updated. | read-only: true | validation: format date-time - name: subscriptionDescription | type: SubscriptionDescription | description: Subscription description, in the site's default language and translated into the buyer's language. For example, `"1kg of selected coffee, once a month"`. For a subscription contract with more than one line item, holds a general name for the subscription. - name: original | type: string | description: Subscription description in the site's default language. | validation: maxLength 500 - name: translated | type: string | description: Subscription description translated into the buyer's language. | validation: maxLength 500 - name: subscriptionSettings | type: SubscriptionSettings | description: Subscription terms, such as the billing frequency, the number of billing cycles, and whether the subscription renews automatically. - name: frequency | type: SubscriptionFrequency | description: Frequency unit of the billing cycle. - enum: - UNDEFINED: - DAY: Day. - WEEK: Week. - MONTH: Month. - YEAR: 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. | 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: lineItems | type: array | description: Subscription line items. The order for each billing cycle is created with these line items. In a subscription contract: + `lineItems.subscriptionInfo.id` is the subscription contract's own GUID. + `lineItems.subscriptionInfo.cycleNumber` is always `0`. The billing cycle is set on the line items of each cycle's order. + `subscriptionInfo.title` and `subscriptionInfo.description` hold the subscription contract's title and description, not the line item's own subscription option. + `refundQuantity`, `restockQuantity`, and `depositAmount` aren't updated after the line item is added. Refunds, restocks, and fulfillment are recorded on each billing cycle's order. + `extendedFields` and `decimalQuantity` aren't returned. + When coupons were included in item prices at checkout, `price` is the price before coupons, and the coupons are in `appliedDiscounts`. | validation: minItems 1, maxItems 100 - 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: 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: 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: 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: descriptionLines | type: array | description: Line item description lines. Used for display purposes for the cart, checkout and order. | 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: 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: 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: itemType | type: ItemType | description: Item type. Either a preset type or custom. - 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: 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: 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: digitalFile | type: DigitalFile | description: Digital file identifier, relevant only for items with type DIGITAL. - 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: 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: 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: 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: 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: 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: id | type: string | description: Modifier group GUID. | validation: minLength 1, maxLength 36 - name: name | type: TranslatableString | description: Modifier group name. - 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: buyerInfo | type: BuyerInfo | description: Buyer information. - 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: buyerLanguage | type: string | description: Language for communication with the buyer. For a site that supports multiple languages, this is the language the buyer selected. Default: Site language | validation: maxLength 10 - name: weightUnit | type: WeightUnit | description: Weight measurement unit. Default: Site's weight unit - 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 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. | validation: format CURRENCY, immutable - name: currencyConversionDetails | type: CurrencyConversionDetails | description: Multi-currency details for a subscription paid in a currency other than the site's currency. - name: originalCurrency | type: string | description: Currency used for the pricing of this order, in [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) format. This currency is used to calculate the pricing before conversion to the buyer's payment currency. | read-only: true | validation: format CURRENCY, immutable - name: conversionRate | type: string | description: The rate used for converting the original currency to the currency used for payment. Returned only when a single rate produced every amount on the order. This is the case for an order converted once at checkout. | read-only: true | validation: decimalValue {"gt":"0","lte":"1000000000000000"} - name: taxIncludedInPrices | type: boolean | description: Whether tax is included in line item prices. Default: `false` | validation: immutable - name: priceSummary | type: PriceSummary | description: Price summary of a single billing cycle. | 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: platformFeeSummary | type: PlatformFeeSummary | description: Summary of platform fees calculated at checkout, including totals by charge type and a breakdown of individual fees. Not updated when draft changes are committed. Each billing cycle's order holds the platform fees for that cycle. - 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: billingInfo | type: AddressWithContact | description: Billing address and contact details. - 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: shippingInfo | type: ShippingInformation | description: Shipping information and selected shipping option details. - 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: 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: appliedDiscounts | type: array | description: Discounts applied to the subscription contract. | validation: maxItems 100 - 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: channelInfo | type: ChannelInfo | description: Information about the sales channel the subscription was purchased through. - name: type | type: ChannelType | description: Sales channel that submitted the order. When creating an order via the API to record an external order, use the channel type that matches the original source. If no matching type exists, use `OTHER_PLATFORM`. - enum: - UNSPECIFIED: Unspecified sales channel. This value is not supported. - WEB: A web client. - POS: [Point of sale solutions](https://support.wix.com/en/wix-mobile-pos-2196395). - EBAY: [eBay shop](https://support.wix.com/en/article/wix-stores-connecting-and-setting-up-an-ebay-shop). - AMAZON: [Amazon shop](https://support.wix.com/en/article/wix-stores-connecting-and-setting-up-an-amazon-shop). - OTHER_PLATFORM: Other sales platform. - WIX_APP_STORE: [Wix Owner app](https://support.wix.com/article/wix-owner-app-an-overview). - WIX_INVOICES: Wix Invoices app in [your dashboard](https://www.wix.com/my-account/site-selector/?buttonText=Select%20Site&title=Select%20a%20Site&autoSelectOnSingleSite=true&actionUrl=https:%2F%2Fwww.wix.com%2Fdashboard%2F%7B%7BmetaSiteId%7D%7D%2Finvoices/settings/general-settings) - BACKOFFICE_MERCHANT: Wix merchant backoffice. - WISH: Wish sales channel. - CLASS_PASS: [ClassPass sales channel](https://support.wix.com/en/article/wix-bookings-letting-clients-book-your-services-with-classpass). - GLOBAL_E: Global-E sales channel. - FACEBOOK: [Facebook shop](https://support.wix.com/en/article/wix-stores-changes-to-facebook-shops). - ETSY: [Etsy sales channel](https://support.wix.com/en/article/wix-stores-request-adding-etsy-as-a-sales-channel). - TIKTOK: [TikTok sales channel](https://support.wix.com/en/article/wix-stores-request-adding-tiktok-as-a-sales-channel). - FAIRE_COM: [Faire marketplace integration](https://support.wix.com/en/article/wix-stores-creating-a-faire-store-using-the-faire-integration-app). - PAYPAL_AGENTIC_CHECKOUT: PayPal Agentic Checkout sales channel. - STRIPE_AGENTIC_CHECKOUT: Stripe Agentic Checkout sales channel. - name: externalOrderId | type: string | description: Reference to an order GUID from an external system. Relevant when recording orders from external platforms. | validation: maxLength 100 - name: externalOrderUrl | type: string | description: URL to the order in the external system. Relevant when recording orders from external platforms. | validation: maxLength 300 - name: customFields | type: array | description: Custom fields. | validation: maxItems 100 - name: value | type: Value | description: Custom field value. - ONE-OF: - name: nullValue | type: | description: - name: numberValue | type: number | description: - name: stringValue | type: string | description: - name: boolValue | type: boolean | description: - name: structValue | type: object | description: - name: listValue | type: ListValue | description: - name: values | type: array | description: - name: title | type: string | description: Custom field title. | validation: minLength 1, maxLength 500 - name: translatedTitle | type: string | description: Translated custom field title. | validation: minLength 1, maxLength 500 - name: recipientInfo | type: AddressWithContact | description: Recipient address and contact details. This field may differ from the address in `shippingInfo.logistics` when: + The chosen shipping option is pickup point or store pickup. + No shipping option is selected. - name: extendedFields | type: ExtendedFields | description: Custom field data for the 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. - name: subscriptionTitle | type: SubscriptionTitle | description: Subscription title, in the site's default language and translated into the buyer's language. For example, `"Monthly coffee subscription"`. For a subscription contract with more than one line item, holds a general name for the subscription. - name: original | type: string | description: Subscription title in the site's default language. | validation: minLength 1, maxLength 150 - name: translated | type: string | description: Subscription title translated into the buyer's language. | validation: minLength 1, maxLength 150 - name: additionalFees | type: array | description: Additional fees applied to the subscription contract. | validation: maxItems 100 - 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: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata. - name: count | type: integer | description: Number of items returned in the response. | validation: format int32 - name: cursors | type: Cursors | description: Cursor strings that point to the next page, previous page, or both. - name: next | type: string | description: Cursor string pointing to the next page in the list of results. | validation: maxLength 16000 - name: prev | type: string | description: Cursor pointing to the previous page in the list of results. | validation: maxLength 16000 - name: hasNext | type: boolean | description: Whether there are more pages to retrieve following the current page. + `true`: Another page of results can be retrieved. + `false`: This is the last page. ``` ### Examples ### Query a buyer's subscription contracts Retrieves the subscription contracts of one buyer contact, 1 per page, sorted by ID. ```curl curl -X POST \ 'https://www.wixapis.com/ecom/v1/subscription-contracts/query' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -d '{ "query": { "filter": { "buyerInfo.contactId": "3c7b1f5e-8d2a-4e6b-9f1c-2a4d6e8b0c13" }, "sort": [ { "fieldName": "id", "order": "ASC" } ], "cursorPaging": { "limit": 1 } } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.ecom.subscriptionContracts.querySubscriptionContracts(query) Description: Retrieves a list of up to 100 subscription contracts, given the provided paging, filtering, and sorting. Query Subscription Contracts runs with these defaults, which you can override: - `id` is sorted in `ASC` order - `cursorPaging.limit` is `50` You can filter and sort by `id` and `buyerInfo.contactId`. For example, to retrieve all of a buyer's subscription contracts, filter by `buyerInfo.contactId`. To learn about working with Query methods, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md) and [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md). # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: query Method parameters: param name: query | type: SubscriptionContractQuery | required: true - name: cursorPaging | type: CursorPaging | description: Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not `filter` or `sort`. - name: limit | type: integer | description: Maximum number of items to return in the results. | validation: minimum 0, maximum 100, format int32 - name: cursor | type: string | description: Pointer to the next or previous page in the list of results. Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. | validation: maxLength 16000 - name: filter | type: object | description: Filter object. See [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md) for more information. Supported properties: `id`, `buyerInfo.contactId` - name: sort | type: array | description: Sort object in the following format: `[{"fieldName":"sortField1","order":"ASC"},{"fieldName":"sortField2","order":"DESC"}]` Learn more about [sorting](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md). | validation: maxItems 5 - name: fieldName | type: string | description: Field to sort by. Supported properties: `id`, `buyerInfo.contactId` | validation: maxLength 512 - name: order | type: SortOrder | description: Sort order. Use `ASC` for ascending order or `DESC` for descending order. Default: `ASC` - enum: ASC, DESC Query fields: - field: _id | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte, $startsWith | sort: ASC, DESC | aggregatable: undefined | searchable: undefined - field: buyerInfo.contactId | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte, $startsWith | sort: ASC, DESC | aggregatable: undefined | searchable: undefined Return type: PROMISE - name: subscriptionContracts | type: array | description: Retrieved subscription contracts. - name: _id | type: string | description: Subscription contract GUID. | read-only: true | validation: format GUID - name: revision | type: string | description: Revision number, which increments by 1 each time the subscription contract is updated. | read-only: true | validation: format int64 - name: _createdDate | type: Date | description: Date and time the subscription contract was created. | read-only: true - name: _updatedDate | type: Date | description: Date and time the subscription contract was last updated. | read-only: true - name: subscriptionDescription | type: SubscriptionDescription | description: Subscription description, in the site's default language and translated into the buyer's language. For example, `"1kg of selected coffee, once a month"`. For a subscription contract with more than one line item, holds a general name for the subscription. - name: original | type: string | description: Subscription description in the site's default language. | validation: maxLength 500 - name: translated | type: string | description: Subscription description translated into the buyer's language. | validation: maxLength 500 - name: subscriptionSettings | type: SubscriptionSettings | description: Subscription terms, such as the billing frequency, the number of billing cycles, and whether the subscription renews automatically. - name: frequency | type: SubscriptionFrequency | description: Frequency unit of the billing cycle. - enum: - UNDEFINED: - DAY: Day. - WEEK: Week. - MONTH: Month. - YEAR: 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. | 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: lineItems | type: array | description: Subscription line items. The order for each billing cycle is created with these line items. In a subscription contract: + `lineItems.subscriptionInfo.id` is the subscription contract's own GUID. + `lineItems.subscriptionInfo.cycleNumber` is always `0`. The billing cycle is set on the line items of each cycle's order. + `subscriptionInfo.title` and `subscriptionInfo.description` hold the subscription contract's title and description, not the line item's own subscription option. + `refundQuantity`, `restockQuantity`, and `depositAmount` aren't updated after the line item is added. Refunds, restocks, and fulfillment are recorded on each billing cycle's order. + `extendedFields` and `decimalQuantity` aren't returned. + When coupons were included in item prices at checkout, `price` is the price before coupons, and the coupons are in `appliedDiscounts`. | validation: minItems 1, maxItems 100 - 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: 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: 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: 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: descriptionLines | type: array | description: Line item description lines. Used for display purposes for the cart, checkout and order. | 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: 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: 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: itemType | type: ItemType | description: Item type. Either a preset type or custom. - 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: 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: 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: digitalFile | type: DigitalFile | description: Digital file identifier, relevant only for items with type DIGITAL. - 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: 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: 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: 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: 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: 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: _id | type: string | description: Modifier group GUID. | validation: minLength 1, maxLength 36 - name: name | type: TranslatableString | description: Modifier group name. - 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: buyerInfo | type: BuyerInfo | description: Buyer information. - 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: buyerLanguage | type: string | description: Language for communication with the buyer. For a site that supports multiple languages, this is the language the buyer selected. Default: Site language | validation: maxLength 10 - name: weightUnit | type: WeightUnit | description: Weight measurement unit. Default: Site's weight unit - 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 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. | validation: format CURRENCY, immutable - name: currencyConversionDetails | type: CurrencyConversionDetails | description: Multi-currency details for a subscription paid in a currency other than the site's currency. - name: originalCurrency | type: string | description: Currency used for the pricing of this order, in [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) format. This currency is used to calculate the pricing before conversion to the buyer's payment currency. | read-only: true | validation: format CURRENCY, immutable - name: conversionRate | type: string | description: The rate used for converting the original currency to the currency used for payment. Returned only when a single rate produced every amount on the order. This is the case for an order converted once at checkout. | read-only: true | validation: decimalValue {"gt":"0","lte":"1000000000000000"} - name: taxIncludedInPrices | type: boolean | description: Whether tax is included in line item prices. Default: `false` | validation: immutable - name: priceSummary | type: PriceSummary | description: Price summary of a single billing cycle. | 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: platformFeeSummary | type: PlatformFeeSummary | description: Summary of platform fees calculated at checkout, including totals by charge type and a breakdown of individual fees. Not updated when draft changes are committed. Each billing cycle's order holds the platform fees for that cycle. - 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: billingInfo | type: AddressWithContact | description: Billing address and contact details. - 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: shippingInfo | type: ShippingInformation | description: Shipping information and selected shipping option details. - 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: 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: appliedDiscounts | type: array | description: Discounts applied to the subscription contract. | validation: maxItems 100 - 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: channelInfo | type: ChannelInfo | description: Information about the sales channel the subscription was purchased through. - name: type | type: ChannelType | description: Sales channel that submitted the order. When creating an order via the API to record an external order, use the channel type that matches the original source. If no matching type exists, use `OTHER_PLATFORM`. - enum: - UNSPECIFIED: Unspecified sales channel. This value is not supported. - WEB: A web client. - POS: [Point of sale solutions](https://support.wix.com/en/wix-mobile-pos-2196395). - EBAY: [eBay shop](https://support.wix.com/en/article/wix-stores-connecting-and-setting-up-an-ebay-shop). - AMAZON: [Amazon shop](https://support.wix.com/en/article/wix-stores-connecting-and-setting-up-an-amazon-shop). - OTHER_PLATFORM: Other sales platform. - WIX_APP_STORE: [Wix Owner app](https://support.wix.com/article/wix-owner-app-an-overview). - WIX_INVOICES: Wix Invoices app in [your dashboard](https://www.wix.com/my-account/site-selector/?buttonText=Select%20Site&title=Select%20a%20Site&autoSelectOnSingleSite=true&actionUrl=https:%2F%2Fwww.wix.com%2Fdashboard%2F%7B%7BmetaSiteId%7D%7D%2Finvoices/settings/general-settings) - BACKOFFICE_MERCHANT: Wix merchant backoffice. - WISH: Wish sales channel. - CLASS_PASS: [ClassPass sales channel](https://support.wix.com/en/article/wix-bookings-letting-clients-book-your-services-with-classpass). - GLOBAL_E: Global-E sales channel. - FACEBOOK: [Facebook shop](https://support.wix.com/en/article/wix-stores-changes-to-facebook-shops). - ETSY: [Etsy sales channel](https://support.wix.com/en/article/wix-stores-request-adding-etsy-as-a-sales-channel). - TIKTOK: [TikTok sales channel](https://support.wix.com/en/article/wix-stores-request-adding-tiktok-as-a-sales-channel). - FAIRE_COM: [Faire marketplace integration](https://support.wix.com/en/article/wix-stores-creating-a-faire-store-using-the-faire-integration-app). - PAYPAL_AGENTIC_CHECKOUT: PayPal Agentic Checkout sales channel. - STRIPE_AGENTIC_CHECKOUT: Stripe Agentic Checkout sales channel. - name: externalOrderId | type: string | description: Reference to an order GUID from an external system. Relevant when recording orders from external platforms. | validation: maxLength 100 - name: externalOrderUrl | type: string | description: URL to the order in the external system. Relevant when recording orders from external platforms. | validation: maxLength 300 - name: customFields | type: array | description: Custom fields. | validation: maxItems 100 - name: value | type: Value | description: Custom field value. - ONE-OF: - name: nullValue | type: | description: - name: numberValue | type: number | description: - name: stringValue | type: string | description: - name: boolValue | type: boolean | description: - name: structValue | type: object | description: - name: listValue | type: ListValue | description: - name: values | type: array | description: - name: title | type: string | description: Custom field title. | validation: minLength 1, maxLength 500 - name: translatedTitle | type: string | description: Translated custom field title. | validation: minLength 1, maxLength 500 - name: recipientInfo | type: AddressWithContact | description: Recipient address and contact details. This field may differ from the address in `shippingInfo.logistics` when: + The chosen shipping option is pickup point or store pickup. + No shipping option is selected. - name: extendedFields | type: ExtendedFields | description: Custom field data for the 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. - name: subscriptionTitle | type: SubscriptionTitle | description: Subscription title, in the site's default language and translated into the buyer's language. For example, `"Monthly coffee subscription"`. For a subscription contract with more than one line item, holds a general name for the subscription. - name: original | type: string | description: Subscription title in the site's default language. | validation: minLength 1, maxLength 150 - name: translated | type: string | description: Subscription title translated into the buyer's language. | validation: minLength 1, maxLength 150 - name: additionalFees | type: array | description: Additional fees applied to the subscription contract. | validation: maxItems 100 - 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: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata. - name: count | type: integer | description: Number of items returned in the response. | validation: format int32 - name: cursors | type: Cursors | description: Cursor strings that point to the next page, previous page, or both. - name: next | type: string | description: Cursor string pointing to the next page in the list of results. | validation: maxLength 16000 - name: prev | type: string | description: Cursor pointing to the previous page in the list of results. | validation: maxLength 16000 - name: hasNext | type: boolean | description: Whether there are more pages to retrieve following the current page. + `true`: Another page of results can be retrieved. + `false`: This is the last page. ``` ### Examples ### Query a buyer's subscription contracts Retrieves the subscription contracts of one buyer contact, 1 per page, sorted by ID. ```javascript import { subscriptionContracts } from "@wix/ecom"; async function querySubscriptionContracts() { const response = await subscriptionContracts.querySubscriptionContracts({ filter: { "buyerInfo.contactId": "3c7b1f5e-8d2a-4e6b-9f1c-2a4d6e8b0c13" }, sort: [{ fieldName: "_id", order: "ASC" }], cursorPaging: { limit: 1 }, }); } /* Promise resolves to: * { * "subscriptionContracts": [ * { * "_id": "01d10356-9188-4ab2-90c1-acfcfeb488c1", * "revision": "3", * "_createdDate": "2026-01-26T11:38:59.118Z", * "_updatedDate": "2026-01-26T11:39:08.344Z", * "subscriptionTitle": { * "original": "Monthly sun hat subscription", * "translated": "Monthly sun hat subscription" * }, * "subscriptionDescription": { * "original": "A black sun hat delivered once a month for 12 months.", * "translated": "A black sun hat delivered once a month for 12 months." * }, * "subscriptionSettings": { * "frequency": "MONTH", * "interval": 1, * "autoRenewal": false, * "billingCycles": 12, * "enableCustomerCancellation": false * }, * "lineItems": [ * { * "_id": "00000000-0000-0000-0000-000000000001", * "productName": { * "original": "Simple Black Sun Hat", * "translated": "Simple Black Sun Hat" * }, * "catalogReference": { * "catalogItemId": "25199b84-ed2f-4ced-a4cb-532f3df0968c", * "appId": "0a0a36eb-ec3b-4f06-89cd-07ac85c0c761" * }, * "quantity": 1, * "totalDiscount": { * "amount": "5.00", * "formattedAmount": "$5.00" * }, * "descriptionLines": [ * { * "name": { * "original": "Color", * "translated": "Color" * }, * "colorInfo": { * "original": "Black", * "translated": "Black", * "code": "#000000" * } * } * ], * "itemType": { * "preset": "PHYSICAL" * }, * "priceBeforeDiscounts": { * "amount": "20.00", * "formattedAmount": "$20.00" * }, * "price": { * "amount": "20.00", * "formattedAmount": "$20.00" * }, * "subscriptionInfo": { * "_id": "01d10356-9188-4ab2-90c1-acfcfeb488c1", * "cycleNumber": 0, * "subscriptionSettings": { * "frequency": "MONTH", * "interval": 1, * "autoRenewal": false, * "billingCycles": 12, * "enableCustomerCancellation": false * } * }, * "totalPriceBeforeTax": { * "amount": "15.00", * "formattedAmount": "$15.00" * }, * "totalPriceAfterTax": { * "amount": "15.00", * "formattedAmount": "$15.00" * }, * "paymentOption": "FULL_PAYMENT_ONLINE", * "locations": [], * "lineItemPrice": { * "amount": "20.00", * "formattedAmount": "$20.00" * }, * "taxInfo": { * "taxAmount": { * "amount": "0.00", * "formattedAmount": "$0.00" * }, * "taxableAmount": { * "amount": "0.00", * "formattedAmount": "$0.00" * }, * "taxRate": "0.0000", * "taxIncludedInPrice": true, * "taxBreakdown": [] * }, * "taxableAddress": { * "addressType": "SHIPPING" * }, * "priceUndetermined": false, * "fixedQuantity": false, * "modifierGroups": [], * "physicalProperties": { * "weight": 0.5, * "sku": "HAT-BLK-001", * "shippable": true * } * } * ], * "buyerInfo": { * "contactId": "3c7b1f5e-8d2a-4e6b-9f1c-2a4d6e8b0c13", * "email": "jane.doe@example.com", * "memberId": "3c7b1f5e-8d2a-4e6b-9f1c-2a4d6e8b0c13" * }, * "buyerLanguage": "en", * "weightUnit": "LB", * "currency": "USD", * "taxIncludedInPrices": true, * "priceSummary": { * "subtotal": { * "amount": "20.00", * "formattedAmount": "$20.00" * }, * "shipping": { * "amount": "5.00", * "formattedAmount": "$5.00" * }, * "tax": { * "amount": "0.00", * "formattedAmount": "$0.00" * }, * "discount": { * "amount": "5.00", * "formattedAmount": "$5.00" * }, * "total": { * "amount": "20.00", * "formattedAmount": "$20.00" * }, * "totalAdditionalFees": { * "amount": "0.00", * "formattedAmount": "$0.00" * } * }, * "platformFeeSummary": { * "total": { * "amount": "2.00", * "formattedAmount": "$2.00" * }, * "totalAbsorbed": { * "amount": "2.00", * "formattedAmount": "$2.00" * }, * "fees": [ * { * "name": { * "original": "1st item Platform Fee" * }, * "amount": { * "amount": "2.00", * "formattedAmount": "$2.00" * }, * "lineItemId": "00000000-0000-0000-0000-000000000001", * "chargeType": "ABSORBED", * "percentageRate": "0.1" * } * ] * }, * "billingInfo": { * "address": { * "country": "US", * "subdivision": "US-NY", * "city": "New York", * "postalCode": "10011", * "streetAddress": { * "number": "235", * "name": "W 23rd St" * }, * "addressLine": "235 W 23rd St", * "addressLine2": "Apartment 4", * "countryFullname": "United States", * "subdivisionFullname": "New York" * }, * "contactDetails": { * "firstName": "Jane", * "lastName": "Doe", * "phone": "2125555217", * "company": "Doe Hats LLC" * } * }, * "shippingInfo": { * "code": "standard-shipping", * "title": "Standard Shipping", * "logistics": { * "deliveryTime": "3-5 business days", * "shippingDestination": { * "address": { * "country": "US", * "subdivision": "US-NY", * "city": "New York", * "postalCode": "10011", * "streetAddress": { * "number": "235", * "name": "W 23rd St" * }, * "addressLine": "235 W 23rd St", * "addressLine2": "Apartment 4", * "countryFullname": "United States", * "subdivisionFullname": "New York" * }, * "contactDetails": { * "firstName": "Jane", * "lastName": "Doe", * "phone": "2125555217", * "company": "Doe Hats LLC" * } * } * }, * "cost": { * "price": { * "amount": "5.00", * "formattedAmount": "$5.00" * }, * "totalPriceBeforeTax": { * "amount": "5.00", * "formattedAmount": "$5.00" * }, * "totalPriceAfterTax": { * "amount": "5.00", * "formattedAmount": "$5.00" * }, * "discount": { * "amount": "0.00", * "formattedAmount": "$0.00" * } * }, * "region": { * "name": "United States" * } * }, * "appliedDiscounts": [ * { * "discountType": "GLOBAL", * "coupon": { * "_id": "e4a7c2b9-1d3f-4b6e-8a5c-7f9d2e0b3c61", * "code": "HAT5", * "name": "5 off a hat subscription", * "amount": { * "amount": "5.00", * "formattedAmount": "$5.00" * } * }, * "_id": "c2e6a9d1-4f8b-4b3e-a7c5-9d1f3e5b7a20", * "lineItemDiscounts": [ * { * "_id": "00000000-0000-0000-0000-000000000001", * "totalDiscount": { * "amount": "5.00", * "formattedAmount": "$5.00" * } * } * ] * } * ], * "channelInfo": { * "type": "WEB" * }, * "customFields": [ * { * "value": "Leave at the front desk.", * "title": "Delivery note", * "translatedTitle": "Delivery note" * } * ], * "recipientInfo": { * "address": { * "country": "US", * "subdivision": "US-NY", * "city": "New York", * "postalCode": "10011", * "streetAddress": { * "number": "235", * "name": "W 23rd St" * }, * "addressLine": "235 W 23rd St", * "addressLine2": "Apartment 4", * "countryFullname": "United States", * "subdivisionFullname": "New York" * }, * "contactDetails": { * "firstName": "Jane", * "lastName": "Doe", * "phone": "2125555217", * "company": "Doe Hats LLC" * } * }, * "extendedFields": { * "namespaces": {} * }, * "additionalFees": [] * } * ], * "pagingMetadata": { * "count": 1, * "cursors": { * "next": "5b1e8c2f7a9d4e06b3c1f8a2d7e4b9c0a6f3d1e8.EkEqPwo9ChNidXllckluZm8uY29udGFjdElkEiYaJDNjN2IxZjVl" * }, * "hasNext": true * } * } */ ``` ### querySubscriptionContracts (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 { subscriptionContracts } from '@wix/ecom'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { subscriptionContracts }, // Include the auth strategy and host as relevant }); async function querySubscriptionContracts(query) { const response = await myWixClient.subscriptionContracts.querySubscriptionContracts(query); }; ``` ---