> 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 # GetValidationViolations # Package: validations # Namespace: ValidationsSPI # Method link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/validations/validations-integration-service-plugin/get-validation-violations.md ## Permission Scopes: Manage eCommerce - all permissions: SCOPE.DC-ECOM-MEGA.MANAGE-ECOM ## Introduction This method retrieves validation violations from your app. Wix calls this method when certain actions are performed on a visitor's cart and checkout. For example, when an item is added to the cart, or when a coupon is added to a checkout. This method validates a visitor's cart and checkout, and returns any validation violations (using the structure provided by Wix eCommerce). Site visitors can see the validation violations in their cart and checkout pages. If there aren't any validation violations, the method returns an object containing an empty list. > __Notes:__ > + Do not call the Estimate Cart Totals, Estimate Current Cart Totals or Get Checkout methods from your implementation code for Get Validation Violations. Doing so will result in an error. > + By default, this method only retrieves validation violations from a visitor's checkout. If you want to also retrieve validation violations from a visitor's cart, set the `validateInCart` parameter to `true` in the Ecom Validations Integration's config file. --- ## REST API ### Schema ``` Method: getValidationViolations Description: This method retrieves validation violations from your app. Wix calls this method when certain actions are performed on a visitor's cart and checkout. For example, when an item is added to the cart, or when a coupon is added to a checkout. This method validates a visitor's cart and checkout, and returns any validation violations (using the structure provided by Wix eCommerce). Site visitors can see the validation violations in their cart and checkout pages. If there aren't any validation violations, the method returns an object containing an empty list. > __Notes:__ > + Do not call the Estimate Cart Totals, Estimate Current Cart Totals or Get Checkout methods from your implementation code for Get Validation Violations. Doing so will result in an error. > + By default, this method only retrieves validation violations from a visitor's checkout. If you want to also retrieve validation violations from a visitor's cart, set the `validateInCart` parameter to `true` in the Ecom Validations Integration's config file. URL: null Method: POST Method parameters: param name: extendedFields | type: ExtendedFields - 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). param name: sourceInfo | type: SourceInfo - name: source | type: Source | description: Source of the request. - enum: - OTHER: Context cannot be recognized - CART: Called from Ecom's Cart service - CHECKOUT: Called from Ecom's Checkout service - name: purchaseFlowId | type: string | description: Persistent GUID that correlates between the various eCommerce elements: cart, checkout, and order. param name: validationInfo | type: ValidationInfo | description: ValidationsData is the main entity of ValidationsSPI, which contains all the data required for validations - name: buyerDetails | type: BuyerDetails | description: Buyer details. - name: email | type: string | description: Buyer's email address. - name: contactId | type: string | description: Contact GUID if one exists. - name: lineItems | type: array | description: Line items. Max: 300 line items - name: id | type: string | description: Line item GUID. - name: quantity | type: integer | description: Item quantity. Min: `0` Max: `100000` - name: catalogReference | type: CatalogReference | description: Catalog and item reference. Includes GUIDs for the item and the catalog it came from, as well as further optional info. - name: catalogItemId | type: string | description: GUID of the item within the catalog it belongs to. - 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"` - 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: productName | type: ProductName | description: Product name. For example, + 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. - name: translated | type: string | description: Item name translated into the buyer's language. Min: 1 character. Max: 400 characters. Default: Same as `original`. - name: price | type: MultiCurrencyPrice | description: Price of the item **after** catalog-defined discount and line item discounts. - name: amount | type: string | description: Amount. - name: physicalProperties | type: PhysicalProperties | description: Physical properties of the item. When relevant, contains information such as SKU, item weight, and shippability. - 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). - name: shippable | type: boolean | description: Whether this line item is shippable. - name: itemType | type: ItemType | description: Item type. - ONE-OF: - name: preset | type: ItemTypePreset | description: Preset item type. - enum: UNRECOGNISED, PHYSICAL, DIGITAL, GIFT_CARD, SERVICE - name: custom | type: string | description: Custom item type. When none of the preset types are suitable, specifies the custom type. - name: subscriptionOptionInfo | type: SubscriptionOptionInfo | description: [Subscription option](https://dev.wix.com/api/rest/wix-stores/subscription-options/introduction) information. A subscription is a product that is sold on a recurring basis. - name: subscriptionSettings | type: SubscriptionSettings | description: Subscription option settings. - name: frequency | type: SubscriptionFrequency | description: Frequency of recurring payment. - enum: UNDEFINED, DAY, WEEK, MONTH, YEAR - name: interval | type: integer | description: Interval of recurring payment. Default: `1`. If SubscriptionFrequency is Day the minimum interval is 7 - name: autoRenewal | type: boolean | description: Whether subscription is renewed automatically at the end of each period. - name: billingCycles | type: integer | description: Number of billing cycles before subscription ends. Ignored if `autoRenewal` is `true`. - name: enableCustomerCancellation | type: boolean | description: Whether to allow the customer to cancel the subscription.. - name: freeTrialPeriod | type: FreeTrialPeriod | description: Period until first cycle starts. If applied payNow will be 0 If None => no free trial - name: frequency | type: SubscriptionFrequency | description: Frequency of period. Values: DAY, WEEK, MONTH, YEAR - 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. - name: title | type: Title | description: Subscription option title. - name: original | type: string | description: Subscription option 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). - name: translated | type: string | description: Subscription option name translated into the buyer's language. Default: Same as `original`. - name: description | type: Description | description: Subscription option description. - name: original | type: string | description: Subscription option description. - name: translated | type: string | description: Translated subscription option description. - name: pricesBreakdown | type: LineItemPricesData | description: Price breakdown for this line item. - name: totalPriceAfterTax | type: MultiCurrencyPrice | description: Total price after discounts and after tax. - name: totalPriceBeforeTax | type: MultiCurrencyPrice | description: Total price after discounts, and before tax. - name: taxDetails | type: ItemTaxFullDetails | description: Tax details. - name: taxableAmount | type: MultiCurrencyPrice | description: The portion of the total amount of this estimate that was taxable. - name: totalTax | type: MultiCurrencyPrice | description: Calculated tax, based on `taxable_amount`. - name: isTaxIncluded | type: boolean | description: Indicates whether the price already includes tax. - name: taxBreakdown | type: array | description: A detailed description of all the tax authorities applied on this item. - name: jurisdiction | type: string | description: The name of the jurisdiction to which this tax detail applies. For example, "New York" or "Quebec". - name: nonTaxableAmount | type: MultiCurrencyPrice | description: The amount of this line item price that was considered nontaxable. (Decimal value) - name: rate | type: string | description: The rate at which this tax detail was calculated, e.g 0.1000 signifies 10% tax and 2.0000 signifies 200% tax. (Decimal value) - name: taxAmount | type: MultiCurrencyPrice | description: The amount of tax estimated for this line item. (Decimal value) - name: taxableAmount | type: MultiCurrencyPrice | description: The taxable amount of 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. - 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. - name: jurisdictionType | type: JurisdictionType | description: The type of the jurisdiction in which this tax detail applies. - enum: - UNDEFINED: Undefined jurisdiction type. - COUNTRY: Country jurisdiction. - STATE: State jurisdiction. - COUNTY: County jurisdiction. - CITY: City jurisdiction. - SPECIAL: Special jurisdiction. - name: totalDiscount | type: MultiCurrencyPrice | description: Total discount applied for the line item. - name: price | type: MultiCurrencyPrice | description: Catalog price **after** catalog-defined discount and automatic discounts. - name: priceBeforeDiscounts | type: MultiCurrencyPrice | description: Item price **before** automatic discounts, coupons, and global discounts, **after** catalog-defined discount. Defaults to `price` when not provided. - name: lineItemPrice | type: MultiCurrencyPrice | description: Total price **after** catalog-defined discount and automatic discounts, taking line item's quantity into account. - name: fullPrice | type: MultiCurrencyPrice | description: Item price **before** all discounts. Defaults to `price` when not provided. - name: giftCard | type: GiftCard | description: Applied gift card details. >**Note:** Gift cards are supported through the Wix UI, though the service plugin is not currently available. Learn more about [Wix Gift Cards](https://support.wix.com/en/article/wix-stores-setting-up-wix-gift-cards). - name: obfuscatedCode | type: string | description: Gift card obfuscated code. - name: amount | type: MultiCurrencyPrice | description: Gift card value. - name: appId | type: string | description: App GUID of the gift card provider. - 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: priceSummary | type: PriceSummary | description: Price summary. - name: subtotal | type: MultiCurrencyPrice | description: Subtotal of all line items, before discounts and before tax. - name: shipping | type: MultiCurrencyPrice | description: Total shipping price, before discounts and before tax. - name: tax | type: MultiCurrencyPrice | description: Total tax. - name: discount | type: MultiCurrencyPrice | description: Total calculated discount value. - name: total | type: MultiCurrencyPrice | description: Total price **after** discounts, gift cards, and tax. - name: additionalFees | type: MultiCurrencyPrice | description: Total additional fees price **before** tax. - name: billingInfo | type: AddressWithContact | description: Billing information. - 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. - 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. - name: city | type: string | description: City name. - name: postalCode | type: string | description: Postal or zip code. - 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). - name: addressLine2 | type: string | description: Free text providing more detailed address info. Usually contains apt, suite, floor. - name: geocode | type: AddressLocation | description: Geocode object containing latitude and longitude coordinates. - name: latitude | type: number | description: Address latitude. - name: longitude | type: number | description: Address longitude. - name: contactDetails | type: FullAddressContactDetails | description: Contact details. - name: firstName | type: string | description: First name. - name: lastName | type: string | description: Last name. - name: phone | type: string | description: Phone number. - name: company | type: string | description: Company name. - 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: shippingAddress | type: AddressWithContact | description: Shipping address and contact details. - name: shippingInfo | type: ShippingInfo | description: Shipping information. - name: selectedCarrierServiceOption | type: SelectedCarrierServiceOption | description: Selected option out of the options allowed for the `region`. - name: code | type: string | description: Unique identifier of selected option. For example, `usps_std_overnight`. - name: title | type: string | description: Title of the option, such as USPS Standard Overnight Delivery (in the requested locale). For example, "Standard" or "First-Class Package International". - name: cost | type: SelectedCarrierServiceOptionPrices | description: Shipping costs. - name: totalPriceAfterTax | type: MultiCurrencyPrice | description: Total shipping price, after discount and after tax. - name: totalPriceBeforeTax | type: MultiCurrencyPrice | description: Total price of shipping after discounts (when relevant), and before tax. - name: taxDetails | type: ItemTaxFullDetails | description: Tax details. - name: totalDiscount | type: MultiCurrencyPrice | description: Shipping discount before tax. - name: price | type: MultiCurrencyPrice | description: Shipping price before discount and before tax. - name: deliveryAllocations | type: array | description: Delivery solution allocations to different delivery carriers and delivery regions - name: deliveryCarrier | type: Carrier | description: The delivery option's carrier details, could be multiple if the delivery option is a combination of multiple carriers - name: appId | type: string | description: The carrier app id - name: code | type: string | description: Unique code that acts as an GUID for a shipping rate. For example, `"usps_std_overnight"`. - name: deliveryRegion | type: Region | description: The delivery region that are relevant for this delivery solution. - name: id | type: string | description: The delivery region id. - name: name | type: string | description: The delivery region name. - name: applicableLineItems | type: ApplicableLineItems | description: Populated if the delivery solution is a partially supplied by this carrier. - name: lineItemIds | type: array | description: Line items that the delivery solution is for. - name: partial | type: boolean | description: If the delivery solution is a partial and doesn't apply to all items. - name: deliveryTimeSlot | type: DeliveryTimeSlot | description: Expected delivery time slot. - name: from | type: string | description: starting time of the delivery time slot - name: to | type: string | description: ending time of the delivery time slot - name: customFields | type: CustomFields | description: Custom fields. - name: fields | type: array | description: List of custom fields - 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. - name: translatedTitle | type: string | description: Translated custom field title. - name: appliedDiscounts | type: array | description: Applied discounts. - ONE-OF: - name: coupon | type: Coupon | description: Coupon details. - name: id | type: string | description: Coupon GUID. - name: code | type: string | description: Coupon code. - name: name | type: string | description: Coupon name. - name: amount | type: string | description: - name: merchantDiscount | type: MerchantDiscount | description: Merchant discount. - name: amount | type: string | description: - name: discountRule | type: DiscountRule | description: Discount rule. - name: id | type: string | description: Discount rule GUID. - name: name | type: DiscountRuleName | description: Discount rule name. - name: original | type: string | description: Original discount rule name (in site's default language). - name: translated | type: string | description: Translated discount rule name according to buyer language. Defaults to `original` when not provided. - name: amount | type: string | description: - name: discountType | type: DiscountType | description: Discount type. - enum: - GLOBAL: Global discount. - SPECIFIC_ITEMS: Discount for specific items. - SHIPPING: Shipping discount. - name: lineItemIds | type: array | description: IDs of the line items the discount applies to. - name: externalReference | type: ExternalReference | description: References to an external app and resource associated with this checkout. Used for integration and tracking across different platforms. - name: appId | type: string | description: GUID of the app associated with the purchase flow. For example, the Wix Pay Links app GUID. - name: resourceId | type: string | description: Reference to an external resource GUID. Used to link the purchase flow to a specific entity in an external system. For example, a Wix Pay Link GUID. Return type: GetValidationViolationsResponse - name: violations | type: array | description: List of validation violations. - name: severity | type: Severity | description: Severity of the violation. The violations are shown on the cart and checkout pages. A warning is displayed as yellow, and allows a site visitor to proceed with caution. An error is displayed as red, and doesn't allow a site visitor to proceed with the eCommerce flow. - enum: - WARNING: The user is allowed to move forward in the flow. - ERROR: The user is blocked from moving forward in the flow. For example, if callerContext is CART - moving to checkout is blocked. if callerContext is CHECKOUT, placing an order is blocked. - name: target | type: Target | description: Target location on a checkout or cart page where the violation will be displayed. - ONE-OF: - name: other | type: Other | description: General (other) violation. - name: name | type: NameInOther | description: Location on a checkout or a cart page where a general (other) violation will be displayed. - enum: - OTHER_DEFAULT: Default location, in case no specific location is specified. - name: lineItem | type: LineItem | description: Specific line item violation. - name: name | type: NameInLineItem | description: Location on a checkout or a cart page where the specific line item violation will be displayed. - enum: - LINE_ITEM_DEFAULT: Default location, in case no specific location is specified. - name: id | type: string | description: GUID of the line item containing the violation. - name: description | type: string | description: Violation description. Can include rich text. Only HTTP or HTTPS links in the following format are allowed: `Click me`. ``` ### Examples ### Get Validation Violations ```curl curl -X POST https://provider.example.com/v1/get-violations \ -H 'user-agent: Wix' \ -H 'accept-encoding: gzip, deflate' \ -H 'content-type: text/plain; charset=utf-8' \ -d '{ sourceInfo: { source: 'CART', purchaseFlowId: 'a22ebad0-11ef-4a4d-a567-691fa7cb264c' }, validationInfo: { appliedDiscounts: [ { lineItemIds: [], discountType: 'GLOBAL', coupon: { id: '435409da-d374-4c44-b08b-6c703c546960', code: 'couponCode', name: 'couponName' } } ], billingInfo: { address: { country: 'USA', subdivision: 'US-California', city: 'Los Angeles', postalCode: '123456' }, contactDetails: { firstName: 'John', lastName: 'Doe', phone: '12345678', company: 'Wix', vatId: { id: 'a35409de-d374-4c4b-bf8b-6c703c5b6960', type: 'CPF' } } }, buyerDetails: { contactId: 'f463b4ee-0545-45ac-a273-23bf02d38a07', email: 'Johnne@wix.com' }, customFields: { fields: [ { name: 'John', title: 'Name', translatedTitle: '名前' } ] }, giftCard: { id: 'e463b4ee-0145-45ac-a263-23bf02d38a07', appId: '215238eb-22a5-4c36-9e7b-e7c08025e04e', amount: { amount: '2' } }, lineItems: [ { catalogReference: { appId: '215238eb-22a5-4c36-9e7b-e7c08025e04e', catalogItemId: 'e35409da-d374-4c4b-b08b-6c703c5b6960' }, id: '00000000-0000-0000-0000-000000000001', itemType: { preset: 'PHYSICAL' }, physicalProperties: { shippable: true, sku: '', weight: 11 }, price: { amount: '1' }, productName: { original: 'Cute Silk Worm', translated: 'Cute Silk Worm' }, quantity: 4 }, { catalogReference: { appId: '215238eb-22a5-4c36-9e7b-e7c08025e04e', catalogItemId: '74bfa1c0-ce2a-49b7-8cd8-a4c0e0b2af6e' }, id: '00000000-0000-0000-0000-000000000002', itemType: { preset: 'PHYSICAL' }, physicalProperties: { shippable: true, sku: '', weight: '12' }, price: { amount: '600' }, productName: { original: 'Tea Leaves', translated: 'Tea Leaves' }, quantity: 50 } ], priceSummary: { additionalFees: { amount: '0' }, discount: { amount: '0' }, shipping: { amount: '0.41' }, subtotal: { amount: '3.72' }, tax: { amount: '0.87' }, total: { amount: '5.00' } }, shippingAddress: { address: { country: 'USA', subdivision: 'US-California', city: 'Los Angeles', postalCode: '123456' }, contactDetails: { firstName: 'John', lastName: 'Doe', phone: '12345678', company: 'Wix', vatId: { id: 'a35409de-d374-4c4b-bf8b-6c703c5b6960', type: 'CPF' } } }, shippingInfo: { selectedCarrierServiceOption: { code: '8d782b64-bda4-93f6-d9c4-e40b497b0ec3' }, weightUnit: 'KG' } } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.validations.ValidationsSPI.getValidationViolations(request, metadata) Description: This method retrieves validation violations from your app. Wix calls this method when certain actions are performed on a visitor's cart and checkout. For example, when an item is added to the cart, or when a coupon is added to a checkout. This method validates a visitor's cart and checkout, and returns any validation violations (using the structure provided by Wix eCommerce). Site visitors can see the validation violations in their cart and checkout pages. If there aren't any validation violations, the method returns an object containing an empty list. > __Notes:__ > + Do not call the Estimate Cart Totals, Estimate Current Cart Totals or Get Checkout methods from your implementation code for Get Validation Violations. Doing so will result in an error. > + By default, this method only retrieves validation violations from a visitor's checkout. If you want to also retrieve validation violations from a visitor's cart, set the `validateInCart` parameter to `true` in the Ecom Validations Integration's config file. Method parameters: param name: metadata | type: Context | description: this message is not directly used by any service, it exists to describe the expected parameters that SHOULD be provided to invoked Velo methods as part of open-platform. e.g. SPIs, event-handlers, etc.. NOTE: this context object MUST be provided as the last argument in each Velo method signature. Example: ```typescript export function wixStores_onOrderCanceled({ event, metadata }: OrderCanceledEvent) { ... } ``` - name: requestId | type: string | description: A unique identifier of the request. You may print this GUID to your logs to help with future debugging and easier correlation with Wix's logs. - name: currency | type: string | description: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code. - name: identity | type: IdentificationData | description: An object that describes the identity that triggered this request. - ONE-OF: - name: anonymousVisitorId | type: string | description: GUID of a site visitor that has not logged in to the site. - name: memberId | type: string | description: GUID of a site visitor that has logged in to the site. - name: wixUserId | type: string | description: GUID of a Wix user (site owner, contributor, etc.). - name: appId | type: string | description: GUID of an app. - name: languages | type: array | description: A string representing a language and region in the format of `"xx-XX"`. First 2 letters represent the language code according to ISO 639-1. This is followed by a dash "-", and then a by 2 capital letters representing the region according to ISO 3166-2. For example, `"en-US"`. - name: instanceId | type: string | description: The service provider app's instance GUID. param name: request | type: GetValidationViolationsRequest - name: sourceInfo | type: SourceInfo | description: Information about the source of the request. - name: source | type: Source | description: Source of the request. - enum: - OTHER: Context cannot be recognized - CART: Called from Ecom's Cart service - CHECKOUT: Called from Ecom's Checkout service - name: purchaseFlowId | type: string | description: Persistent GUID that correlates between the various eCommerce elements: cart, checkout, and order. - name: validationInfo | type: ValidationInfo | description: Information to validate. - name: buyerDetails | type: BuyerDetails | description: Buyer details. - name: email | type: string | description: Buyer's email address. - name: contactId | type: string | description: Contact GUID if one exists. - name: lineItems | type: array | description: Line items. Max: 300 line items - name: _id | type: string | description: Line item GUID. - name: quantity | type: integer | description: Item quantity. Min: `0` Max: `100000` - name: catalogReference | type: CatalogReference | description: Catalog and item reference. Includes GUIDs for the item and the catalog it came from, as well as further optional info. - name: catalogItemId | type: string | description: GUID of the item within the catalog it belongs to. - 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"` - 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: productName | type: ProductName | description: Product name. For example, + 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. - name: translated | type: string | description: Item name translated into the buyer's language. Min: 1 character. Max: 400 characters. Default: Same as `original`. - name: price | type: MultiCurrencyPrice | description: Price of the item **after** catalog-defined discount and line item discounts. - name: amount | type: string | description: Amount. - name: physicalProperties | type: PhysicalProperties | description: Physical properties of the item. When relevant, contains information such as SKU, item weight, and shippability. - 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). - name: shippable | type: boolean | description: Whether this line item is shippable. - name: itemType | type: ItemType | description: Item type. - ONE-OF: - name: preset | type: ItemTypePreset | description: Preset item type. - enum: UNRECOGNISED, PHYSICAL, DIGITAL, GIFT_CARD, SERVICE - name: custom | type: string | description: Custom item type. When none of the preset types are suitable, specifies the custom type. - name: subscriptionOptionInfo | type: SubscriptionOptionInfo | description: [Subscription option](https://dev.wix.com/api/rest/wix-stores/subscription-options/introduction) information. A subscription is a product that is sold on a recurring basis. - name: subscriptionSettings | type: SubscriptionSettings | description: Subscription option settings. - name: frequency | type: SubscriptionFrequency | description: Frequency of recurring payment. - enum: UNDEFINED, DAY, WEEK, MONTH, YEAR - name: interval | type: integer | description: Interval of recurring payment. Default: `1`. If SubscriptionFrequency is Day the minimum interval is 7 - name: autoRenewal | type: boolean | description: Whether subscription is renewed automatically at the end of each period. - name: billingCycles | type: integer | description: Number of billing cycles before subscription ends. Ignored if `autoRenewal` is `true`. - name: enableCustomerCancellation | type: boolean | description: Whether to allow the customer to cancel the subscription.. - name: freeTrialPeriod | type: FreeTrialPeriod | description: Period until first cycle starts. If applied payNow will be 0 If None => no free trial - name: frequency | type: SubscriptionFrequency | description: Frequency of period. Values: DAY, WEEK, MONTH, YEAR - 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. - name: title | type: Title | description: Subscription option title. - name: original | type: string | description: Subscription option 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). - name: translated | type: string | description: Subscription option name translated into the buyer's language. Default: Same as `original`. - name: description | type: Description | description: Subscription option description. - name: original | type: string | description: Subscription option description. - name: translated | type: string | description: Translated subscription option description. - name: pricesBreakdown | type: LineItemPricesData | description: Price breakdown for this line item. - name: totalPriceAfterTax | type: MultiCurrencyPrice | description: Total price after discounts and after tax. - name: totalPriceBeforeTax | type: MultiCurrencyPrice | description: Total price after discounts, and before tax. - name: taxDetails | type: ItemTaxFullDetails | description: Tax details. - name: taxableAmount | type: MultiCurrencyPrice | description: The portion of the total amount of this estimate that was taxable. - name: totalTax | type: MultiCurrencyPrice | description: Calculated tax, based on `taxable_amount`. - name: isTaxIncluded | type: boolean | description: Indicates whether the price already includes tax. - name: taxBreakdown | type: array | description: A detailed description of all the tax authorities applied on this item. - name: jurisdiction | type: string | description: The name of the jurisdiction to which this tax detail applies. For example, "New York" or "Quebec". - name: nonTaxableAmount | type: MultiCurrencyPrice | description: The amount of this line item price that was considered nontaxable. (Decimal value) - name: rate | type: string | description: The rate at which this tax detail was calculated, e.g 0.1000 signifies 10% tax and 2.0000 signifies 200% tax. (Decimal value) - name: taxAmount | type: MultiCurrencyPrice | description: The amount of tax estimated for this line item. (Decimal value) - name: taxableAmount | type: MultiCurrencyPrice | description: The taxable amount of 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. - 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. - name: jurisdictionType | type: JurisdictionType | description: The type of the jurisdiction in which this tax detail applies. - enum: - UNDEFINED: Undefined jurisdiction type. - COUNTRY: Country jurisdiction. - STATE: State jurisdiction. - COUNTY: County jurisdiction. - CITY: City jurisdiction. - SPECIAL: Special jurisdiction. - name: totalDiscount | type: MultiCurrencyPrice | description: Total discount applied for the line item. - name: price | type: MultiCurrencyPrice | description: Catalog price **after** catalog-defined discount and automatic discounts. - name: priceBeforeDiscounts | type: MultiCurrencyPrice | description: Item price **before** automatic discounts, coupons, and global discounts, **after** catalog-defined discount. Defaults to `price` when not provided. - name: lineItemPrice | type: MultiCurrencyPrice | description: Total price **after** catalog-defined discount and automatic discounts, taking line item's quantity into account. - name: fullPrice | type: MultiCurrencyPrice | description: Item price **before** all discounts. Defaults to `price` when not provided. - name: giftCard | type: GiftCard | description: Applied gift card details. >**Note:** Gift cards are supported through the Wix UI, though the service plugin is not currently available. Learn more about [Wix Gift Cards](https://support.wix.com/en/article/wix-stores-setting-up-wix-gift-cards). - name: obfuscatedCode | type: string | description: Gift card obfuscated code. - name: amount | type: MultiCurrencyPrice | description: Gift card value. - name: appId | type: string | description: App GUID of the gift card provider. - 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: priceSummary | type: PriceSummary | description: Price summary. - name: subtotal | type: MultiCurrencyPrice | description: Subtotal of all line items, before discounts and before tax. - name: shipping | type: MultiCurrencyPrice | description: Total shipping price, before discounts and before tax. - name: tax | type: MultiCurrencyPrice | description: Total tax. - name: discount | type: MultiCurrencyPrice | description: Total calculated discount value. - name: total | type: MultiCurrencyPrice | description: Total price **after** discounts, gift cards, and tax. - name: additionalFees | type: MultiCurrencyPrice | description: Total additional fees price **before** tax. - name: billingInfo | type: AddressWithContact | description: Billing information. - 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. - name: lastName | type: string | description: Last name. - name: phone | type: string | description: Phone number. - name: company | type: string | description: Company name. - 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: shippingAddress | type: AddressWithContact | description: Shipping address and contact details. - name: shippingInfo | type: ShippingInfo | description: Shipping information. - name: selectedCarrierServiceOption | type: SelectedCarrierServiceOption | description: Selected option out of the options allowed for the `region`. - name: code | type: string | description: Unique identifier of selected option. For example, `usps_std_overnight`. - name: title | type: string | description: Title of the option, such as USPS Standard Overnight Delivery (in the requested locale). For example, "Standard" or "First-Class Package International". - name: cost | type: SelectedCarrierServiceOptionPrices | description: Shipping costs. - name: totalPriceAfterTax | type: MultiCurrencyPrice | description: Total shipping price, after discount and after tax. - name: totalPriceBeforeTax | type: MultiCurrencyPrice | description: Total price of shipping after discounts (when relevant), and before tax. - name: taxDetails | type: ItemTaxFullDetails | description: Tax details. - name: totalDiscount | type: MultiCurrencyPrice | description: Shipping discount before tax. - name: price | type: MultiCurrencyPrice | description: Shipping price before discount and before tax. - name: deliveryAllocations | type: array | description: Delivery solution allocations to different delivery carriers and delivery regions - name: deliveryCarrier | type: Carrier | description: The delivery option's carrier details, could be multiple if the delivery option is a combination of multiple carriers - name: appId | type: string | description: The carrier app id - name: code | type: string | description: Unique code that acts as an GUID for a shipping rate. For example, `"usps_std_overnight"`. - name: deliveryRegion | type: Region | description: The delivery region that are relevant for this delivery solution. - name: _id | type: string | description: The delivery region id. - name: name | type: string | description: The delivery region name. - name: applicableLineItems | type: ApplicableLineItems | description: Populated if the delivery solution is a partially supplied by this carrier. - name: lineItemIds | type: array | description: Line items that the delivery solution is for. - name: partial | type: boolean | description: If the delivery solution is a partial and doesn't apply to all items. - name: deliveryTimeSlot | type: DeliveryTimeSlot | description: Expected delivery time slot. - name: from | type: Date | description: starting time of the delivery time slot - name: to | type: Date | description: ending time of the delivery time slot - name: customFields | type: CustomFields | description: Custom fields. - name: fields | type: array | description: List of custom fields - 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. - name: translatedTitle | type: string | description: Translated custom field title. - name: appliedDiscounts | type: array | description: Applied discounts. - ONE-OF: - name: coupon | type: Coupon | description: Coupon details. - name: _id | type: string | description: Coupon GUID. - name: code | type: string | description: Coupon code. - name: name | type: string | description: Coupon name. - name: amount | type: string | description: - name: merchantDiscount | type: MerchantDiscount | description: Merchant discount. - name: amount | type: string | description: - name: discountRule | type: DiscountRule | description: Discount rule. - name: _id | type: string | description: Discount rule GUID. - name: name | type: DiscountRuleName | description: Discount rule name. - name: original | type: string | description: Original discount rule name (in site's default language). - name: translated | type: string | description: Translated discount rule name according to buyer language. Defaults to `original` when not provided. - name: amount | type: string | description: - name: discountType | type: DiscountType | description: Discount type. - enum: - GLOBAL: Global discount. - SPECIFIC_ITEMS: Discount for specific items. - SHIPPING: Shipping discount. - name: lineItemIds | type: array | description: IDs of the line items the discount applies to. - name: externalReference | type: ExternalReference | description: References to an external app and resource associated with this checkout. Used for integration and tracking across different platforms. - name: appId | type: string | description: GUID of the app associated with the purchase flow. For example, the Wix Pay Links app GUID. - name: resourceId | type: string | description: Reference to an external resource GUID. Used to link the purchase flow to a specific entity in an external system. For example, a Wix Pay Link GUID. - name: extendedFields | type: ExtendedFields | description: Custom field data to validate. [Extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md) must be configured in the [app dashboard](https://dev.wix.com/dc3/my-apps/) 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). Return type: PROMISE - name: violations | type: array | description: List of validation violations. - name: severity | type: Severity | description: Severity of the violation. The violations are shown on the cart and checkout pages. A warning is displayed as yellow, and allows a site visitor to proceed with caution. An error is displayed as red, and doesn't allow a site visitor to proceed with the eCommerce flow. - enum: - WARNING: The user is allowed to move forward in the flow. - ERROR: The user is blocked from moving forward in the flow. For example, if callerContext is CART - moving to checkout is blocked. if callerContext is CHECKOUT, placing an order is blocked. - name: target | type: Target | description: Target location on a checkout or cart page where the violation will be displayed. - ONE-OF: - name: other | type: Other | description: General (other) violation. - name: name | type: NameInOther | description: Location on a checkout or a cart page where a general (other) violation will be displayed. - enum: - OTHER_DEFAULT: Default location, in case no specific location is specified. - name: lineItem | type: LineItem | description: Specific line item violation. - name: name | type: NameInLineItem | description: Location on a checkout or a cart page where the specific line item violation will be displayed. - enum: - LINE_ITEM_DEFAULT: Default location, in case no specific location is specified. - name: _id | type: string | description: GUID of the line item containing the violation. - name: description | type: string | description: Violation description. Can include rich text. Only HTTP or HTTPS links in the following format are allowed: `Click me`. ``` ### Examples ### Example of a `violations` return value ```javascript import { validations } from '@wix/ecom/service-plugins'; validations.provideHandlers({ getValidationViolations: async ( payload ) => { const {request, metadata} = payload; // Use the `request` and `metadata` received from Wix and // apply custom logic. return { // Return your response exactly as documented to integrate with Wix. // Return value example: violations: [ { description: "You must purchase at least 100 items.", severity: "WARNING", target: { other: { name: "OTHER_DEFAULT" } } } ] } } }); ``` ### getValidationViolations (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 { validations } from '@wix/ecom/service-plugins'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { validations }, // Include the auth strategy and host as relevant }); async function getValidationViolations(request,metadata) { const response = await myWixClient.validations.getValidationViolations(request,metadata); }; ``` ---