diff --git a/billing-tax-calculation/billing-tax-calculation.service.json b/billing-tax-calculation/billing-tax-calculation.service.json new file mode 100644 index 0000000000..c2df70daea --- /dev/null +++ b/billing-tax-calculation/billing-tax-calculation.service.json @@ -0,0 +1,559 @@ +{ "name": "billing-tax-calculation", + "mixes": [], + "labels": + [ "changed" ], + "location": + { "lineno": 1, + "filename": "tax-calculation-index.js" }, + "docs": + { "summary": "The Tax Calculation service plugin.", + "description": + [ "The Tax Calculation service plugin (formerly SPI) allows you to integrate a custom tax calculation service with Wix. ", + "", + "Use the Tax Calculation service plugin together with the [Tax Groups API](https://dev.wix.com/docs/velo/api-reference/wix-billing-v2/tax-groups) and the [Tax Regions API](https://dev.wix.com/docs/velo/api-reference/wix-billing-v2/tax-regions) to customize your tax calculations. ", + "", + "Learn more:", + "+ [Velo: Custom App Extensions Using service plugins](https://support.wix.com/en/article/velo-custom-business-app-extensions-using-spis-beta)", + "", + "### To add a service plugin", + "1. [Add the plugin to your site](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/integrations/custom-extensions-spis/custom-app-extensions-using-sp-is#step-1-create-a-new-extension-on-your-wix-site).", + "2. Update the [`getConfig()`](https://dev.wix.com/docs/velo/api-reference/wix-billing-v2/service-plugins-spis/billing-tax-calculation/get-config) function in the **-config.js** file that is added to your site during step 1.", + "3. Update the [`calculateTax()`](https://dev.wix.com/docs/velo/api-reference/wix-billing-v2/service-plugins-spis/billing-tax-calculation/calculate-tax) function in the **.js** file that is added to your site during step 1.", + "", + "### Terminology", + "", + "+ **Tax Group:** A category of products that share the same tax treatment. Tax is calculated based on the tax group and the tax region associated with a line item. See the [Tax Groups API](https://dev.wix.com/docs/velo/api-reference/wix-billing-v2/tax-groups).", + "+ **Tax Region:** A location, defined by `country` and `subdivision` with a specific tax treatment. Tax is calculated based on the tax region and the tax group associated with a line item. See the [Tax Regions API](https://dev.wix.com/docs/velo/api-reference/wix-billing-v2/tax-regions).", + "+ **Tax Calculator:** An app that is used under the hood to calculate tax for a Wix site. The app calculates tax based on the tax group of the product and the tax region of the sale. Use the Tax Calculation service plugin to become a tax calculator." ], + "links": [], + "examples": [], + "extra": + { } }, + "properties": [], + "operations": + [ { "name": "calculateTax", + "labels": [], + "nameParams": [], + "params": + [ { "name": "options", + "type": "billing-tax-calculation.Options", + "doc": "Order information to calculate tax for." }, + { "name": "context", + "type": "billing-tax-calculation.Context", + "doc": "Metadata about the request." } ], + "ret": + { "type": + { "name": "Promise", + "typeParams": + [ "billing-tax-calculation.TaxCalculationResponse" ] }, + "doc": "Fulfilled - Retrieved tax calculations." }, + "locations": + [ { "lineno": 25, + "filename": "tax-calculation-spi.js" } ], + "docs": + { "summary": "Calculates tax for the provided line items.", + "description": + [ "Tax is calculated for each line item based on the [tax region](https://dev.wix.com/docs/velo/api-reference/wix-billing-v2/tax-regions) ", + "in `lineItems.taxRegionId` and the [tax group](https://dev.wix.com/docs/velo/api-reference/wix-billing-v2/tax-groups) in `lineItems.taxGroupId`. ", + "", + "The breakdown of calculated tax returned, includes:", + "+ `taxSummary`: The overall total tax calculated.", + "+ `lineItemTaxDetails.taxBreakdown`: The tax calculated for each line item in each jurisdiction.", + "+ `lineItemTaxDetails.taxSummary`: The total tax calculated for each line item.", + "", + "### Where to find `calculateTax()`", + "When you [add the Tax Calculation service plugin](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/integrations/custom-extensions-spis/custom-app-extensions-using-sp-is#step-1-create-a-new-extension-on-your-wix-site), ", + "a folder is automatically added to your site. Use the `.js` file in the folder to write the code to determine how to calculate tax for an order." ], + "links": [], + "examples": + [ { "title": "Example of a `calculateTax()` return value", + "body": + [ "export const calculateTax = async (options, context) => {", + " return {", + " \"currency\": \"USD\",", + " \"taxSummary\": {", + " \"totalAmount\": \"170.00\",", + " \"totalTax\": \"21.00\",", + " \"totalTaxableAmount\": \"170.00\",", + " \"totalTaxIncludedInPrice\": \"0.00\"", + " },", + " \"lineItemTaxDetails\": [{", + " \"_id\": \"00000000-0000-0000-0000-000000000001\",", + " \"itemName\": \"some\",", + " \"quantity\": 1,", + " \"taxBreakdown\": [{", + " \"jurisdiction\": \"TEXAS\",", + " \"jurisdictionType\": taxCalculationProvider.JurisdictionType.STATE,", + " \"nonTaxableAmount\": \"0.00\",", + " \"rate\": \"0.20\",", + " \"taxAmount\": \"15.00\",", + " \"taxableAmount\": \"120.00\",", + " \"taxType\": \"Sales\",", + " \"taxName\": \"TX STATE TAX\"", + " }],", + " \"taxSummary\": {", + " \"fullPrice\": \"120.00\",", + " \"taxAmount\": \"12.00\",", + " \"taxableAmount\": \"120.00\"", + " }", + " },", + " {", + " \"_id\": \"shipping\",", + " \"itemName\": \"Free Shipping\",", + " \"quantity\": 1,", + " \"taxBreakdown\": [", + " {", + " \"jurisdiction\": \"\",", + " \"nonTaxableAmount\": \"0\",", + " \"rate\": \"0.12\",", + " \"taxAmount\": \"6.00\",", + " \"taxName\": \"\",", + " \"taxType\": \"\",", + " \"taxableAmount\": \"50\"", + " }", + " ],", + " \"taxSummary\": {", + " \"fullPrice\": \"50\",", + " \"taxAmount\": \"6.00\",", + " \"taxableAmount\": \"50.00\"", + " }", + " }", + " ]", + " }", + "};" ], + "extra": + { } } ], + "extra": + { } }, + "extra": + { "customLabels": + [ { "id": "maturity-beta" } ] } }, + { "name": "getConfig", + "labels": [], + "nameParams": [], + "params": [], + "ret": + { "type": + { "name": "Promise", + "typeParams": + [ "billing-tax-calculation.TaxCalculationConfigResponse" ] }, + "doc": "Fulfilled - The configuration settings." }, + "locations": + [ { "lineno": 1, + "filename": "tax-calculation-spi.js" } ], + "docs": + { "summary": "Retrieves the configuration of your tax calculation plugin.", + "description": + [ "Set your tax calculation configuration in the `return` of the `getConfig()` function. Wix calls this function when you publish your site. ", + "Changes to the configuration don't take effect until you publish your site.", + "", + "### Where to find `getConfig()`", + "When you [add the Tax Calculation service plugin](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/integrations/custom-extensions-spis/custom-app-extensions-using-sp-is#step-1-create-a-new-extension-on-your-wix-site), ", + "a folder is automatically added to your site. Use the `-config.js` file in the folder to set the default configuration for your ", + "implementation of the service plugin." ], + "links": [], + "examples": + [ { "title": "Example of a configuration file", + "body": + [ "// Place this code in the -config.js file", + "// in the 'tax-calculation-provider' folder of the", + "// Service Plugins section on your site.", + "", + "export function getConfig() {", + " return {", + " calculatorDisplayName: \"Custom Sales Tax\",", + " unsupportedCountries: \"IN\"", + " };", + "};" ], + "extra": + { } } ], + "extra": + { } }, + "extra": + { "customLabels": + [ { "id": "maturity-beta" } ] } } ], + "callbacks": [], + "messages": + [ { "name": "Address", + "locations": + [ { "lineno": 129, + "filename": "tax-calculation-spi.js" } ], + "docs": + { "links": [], + "examples": [], + "extra": + { } }, + "members": + [ { "name": "addressLine", + "type": "string", + "doc": "Main address line (usually street name and number).", + "optional": true }, + { "name": "addressLine2", + "type": "string", + "doc": "Free text providing more detailed address info. Usually contains apt, suite, floor.", + "optional": true }, + { "name": "city", + "type": "string", + "doc": "City name.", + "optional": true }, + { "name": "country", + "type": "string", + "doc": "Two-letter country code in [ISO-3166 alpha-2](https://www.iso.org/obp/ui/#search/code/) format.", + "optional": true }, + { "name": "postalCode", + "type": "string", + "doc": "Postal or zip code.", + "optional": true }, + { "name": "subdivision", + "type": "string", + "doc": "Code for a subdivision (such as state, prefecture, or province) in [ISO 3166-2](https://www.iso.org/standard/72483.html) format.", + "optional": true } ], + "extra": + { }, + "labels": [] }, + { "name": "Context", + "locations": + [ { "lineno": 49, + "filename": "tax-calculation-spi.js" } ], + "docs": + { "links": [], + "examples": [], + "extra": + { } }, + "members": + [ { "name": "currency", + "type": "string", + "doc": "[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code representing the currency used in the request sent from Wix. The response should be returned in the same currency." }, + { "name": "identity", + "type": "billing-tax-calculation.Identity", + "doc": "The identity that describes the identity that triggered this request." }, + { "name": "languages", + "type": + { "name": "Array", + "typeParams": + [ "string" ] }, + "doc": "An array of languages in which the response should be returned. Languages are strings in concatenated [ISO 639-1: 2 Alpha language-code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) and [ISO 3166-1: 2 Alpha country-code](https://en.wikipedia.org/wiki/ISO_3166-1) format, such as \"en-US\"." }, + { "name": "requestId", + "type": "string", + "doc": "A unique identifier of the request. You may print this ID to your logs to help with future debugging and easier correlation with Wix's logs." } ], + "extra": + { }, + "labels": + [ "changed" ] }, + { "name": "Identity", + "locations": + [ { "lineno": 58, + "filename": "tax-calculation-spi.js" } ], + "docs": + { "links": [], + "examples": [], + "extra": + { } }, + "members": + [ { "name": "identityType", + "type": "string", + "doc": "Type of identity that triggered the request. Possible values are:\n+ `UNKNOWN`\n+ `ANONYMOUS_VISITOR`\n+ `MEMBER`\n+ `WIX_USER`\n+ `APP`" }, + { "name": "anonymousVisitorId", + "type": "string", + "doc": "ID of a site visitor who has not logged in to the site. Only provided if `identityType` is `ANONYMOUS_VISITOR`.", + "optional": true }, + { "name": "memberId", + "type": "string", + "doc": "ID of a site visitor who has logged in to the site. Only provided if `identityType` is `MEMBER`.", + "optional": true }, + { "name": "wixUserId", + "type": "string", + "doc": "ID of a Wix user (site owner, contributor, etc.). Only provided if `identityType` is `WIX_USER`.", + "optional": true }, + { "name": "appId", + "type": "string", + "doc": "ID of an app. Only provided if `identityType` is `APP`.", + "optional": true } ], + "extra": + { "oneOfGroups": + [ { "name": "id", + "members": + [ "anonymousVisitorId", + "memberId", + "wixUserId", + "appId" ] } ] }, + "labels": + [ "changed" ] }, + { "name": "LineItem", + "locations": + [ { "lineno": 140, + "filename": "tax-calculation-spi.js" } ], + "docs": + { "links": [], + "examples": [], + "extra": + { } }, + "members": + [ { "name": "_id", + "type": "string", + "doc": "Line item ID." }, + { "name": "itemName", + "type": "string", + "doc": "Line item name to display." }, + { "name": "quantity", + "type": "number", + "doc": "Line item quantity." }, + { "name": "itemCode", + "type": "string", + "doc": "Stock keeping unit for this line item. Learn more about [SKUs](https://www.wix.com/encyclopedia/definition/stock-keeping-unit-sku)." }, + { "name": "taxGroupId", + "type": "string", + "doc": "Tax group ID for this line item. If not provided, the default tax group applies." }, + { "name": "taxIncludedInPrice", + "type": "boolean", + "doc": "Whether tax is included in the price." }, + { "name": "price", + "type": "string", + "doc": "Line item price." }, + { "name": "taxRegionId", + "type": "string", + "doc": "Tax region ID for this line item." }, + { "name": "addressIndex", + "type": "billing-tax-calculation.addressIndex", + "doc": "Index of the address from `addresses` to use to calculate tax for this specific line item. The index is zero-based." } ], + "extra": + { }, + "labels": [] }, + { "name": "LineItemTaxDetails", + "locations": + [ { "lineno": 97, + "filename": "tax-calculation-spi.js" } ], + "docs": + { "links": [], + "examples": [], + "extra": + { } }, + "members": + [ { "name": "_id", + "type": "string", + "doc": "Line item ID." }, + { "name": "itemName", + "type": "string", + "doc": "Total amount of tax calculated for all line items. Note that due to rounding, `totalTax` may not equal the sum of `lineItemTaxDetails.taxSummary.taxAmount`." }, + { "name": "quantity", + "type": "number", + "doc": "Line item quantity." }, + { "name": "taxBreakdown", + "type": + { "name": "Array", + "typeParams": + [ "billing-tax-calculation.TaxBreakdown" ] }, + "doc": "Array of each tax applied, grouped by `jurisdiction`, `jurisdictionType`, `taxName`, `taxRate`, and `taxType`." }, + { "name": "taxSummary", + "type": "billing-tax-calculation.LineItemTaxSummary", + "doc": "Summary of this line item's total price and tax." } ], + "extra": + { }, + "labels": [] }, + { "name": "LineItemTaxSummary", + "locations": + [ { "lineno": 120, + "filename": "tax-calculation-spi.js" } ], + "docs": + { "summary": "Summary of this line item's total price and tax.", + "links": [], + "examples": [], + "extra": + { } }, + "members": + [ { "name": "fullPrice", + "type": "string", + "doc": "Total price for this line item. To determine the price for each individual unit of this line item, divide by `quantity`." }, + { "name": "taxAmount", + "type": "string", + "doc": "The total amount of tax calculated for this line item." }, + { "name": "taxableAmount", + "type": "string", + "doc": "Total taxable amount for this line item." } ], + "extra": + { }, + "labels": [] }, + { "name": "MultipleAddresses", + "locations": + [ { "lineno": 163, + "filename": "tax-calculation-spi.js" } ], + "docs": + { "links": [], + "examples": [], + "extra": + { } }, + "members": + [ { "name": "origin", + "type": "number", + "doc": "Index of the origin address." }, + { "name": "destination", + "type": "number", + "doc": "Index of the destination address." } ], + "extra": + { }, + "labels": [] }, + { "name": "Options", + "locations": + [ { "lineno": 73, + "filename": "tax-calculation-spi.js" } ], + "docs": + { "links": [], + "examples": [], + "extra": + { } }, + "members": + [ { "name": "currency", + "type": "string", + "doc": "3-letter currency code in [ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#active_codes) format." }, + { "name": "addresses", + "type": + { "name": "Array", + "typeParams": + [ "billing-tax-calculation.Address" ] }, + "doc": "Array of addresses. Each line item can individually reference the address to apply with `lineItems.addressIndex`." }, + { "name": "lineItems", + "type": + { "name": "Array", + "typeParams": + [ "billing-tax-calculation.LineItem" ] }, + "doc": "Line items to calculate tax for." } ], + "extra": + { }, + "labels": [] }, + { "name": "TaxBreakdown", + "locations": + [ { "lineno": 106, + "filename": "tax-calculation-spi.js" } ], + "docs": + { "links": [], + "examples": [], + "extra": + { } }, + "members": + [ { "name": "jurisdiction", + "type": "string", + "doc": "Jurisdiction that taxes were calculated for." }, + { "name": "jurisdictionType", + "type": "string", + "doc": "Type of jurisdiction that taxes were calculated for. For example, `\"State\"`, `\"Çounty\"`, `\"City\"`, `\"Special\"`, etc. \nSupported values: `\"CITY\"`, `\"COUNTRY\"`, `\"COUNTY\"`, `\"SPECIAL\"`, `\"STATE\"`, `\"UNDEFINED\"`" }, + { "name": "nonTaxableAmount", + "type": "string", + "doc": "Non-taxable amount of the price." }, + { "name": "rate", + "type": "string", + "doc": "Tax rate used for this jurisdiction, as a decimal. For example, 10% tax is `\"0.1000\"` and 200% tax is `\"2.0000\"`." }, + { "name": "taxableAmount", + "type": "string", + "doc": "Taxable amount of the price." }, + { "name": "taxAmount", + "type": "string", + "doc": "Amount of this tax calculated for this jurisdiction." }, + { "name": "taxName", + "type": "string", + "doc": "Name of the tax that was calculated. For example, `\"NY State Sales Tax\"`, `\"Quebec GST\"`, etc." }, + { "name": "taxType", + "type": "string", + "doc": "Type of tax that was calculated. For example, `\"Sales Tax\"`, `\"Income Tax\"`, `\"Value Added Tax\"`, etc." } ], + "extra": + { }, + "labels": [] }, + { "name": "TaxCalculationConfigResponse", + "locations": + [ { "lineno": 19, + "filename": "tax-calculation-spi.js" } ], + "docs": + { "links": [], + "examples": [], + "extra": + { } }, + "members": + [ { "name": "calculatorDisplayName", + "type": "string", + "doc": "Display name of the tax calculator." }, + { "name": "unsupportedCountries", + "type": + { "name": "Array", + "typeParams": + [ "string" ] }, + "doc": "List of countries, in [ISO-3166 alpha-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#officially_assigned_code_elements) format, that the calculator does not support." } ], + "extra": + { }, + "labels": [] }, + { "name": "TaxCalculationResponse", + "locations": + [ { "lineno": 81, + "filename": "tax-calculation-spi.js" } ], + "docs": + { "links": [], + "examples": [], + "extra": + { } }, + "members": + [ { "name": "currency", + "type": "string", + "doc": "3-letter currency code in [ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#active_codes) format. If this code doesn't match the `currency` passed in the request, then the response is invalid." }, + { "name": "taxSummary", + "type": "billing-tax-calculation.TaxSummary", + "doc": "Summary of the tax calculated." }, + { "name": "lineItemTaxDetails", + "type": + { "name": "Array", + "typeParams": + [ "billing-tax-calculation.LineItemTaxDetails" ] }, + "doc": "Details of each tax applied to each line item." } ], + "extra": + { }, + "labels": [] }, + { "name": "TaxSummary", + "locations": + [ { "lineno": 89, + "filename": "tax-calculation-spi.js" } ], + "docs": + { "links": [], + "examples": [], + "extra": + { } }, + "members": + [ { "name": "totalAmount", + "type": "string", + "doc": "Total price for all line items." }, + { "name": "totalTax", + "type": "string", + "doc": "Total amount of tax calculated for all line items. Note that due to rounding, `totalTax` may not equal the sum of `lineItemTaxDetails.taxSummary.taxAmount`." }, + { "name": "totalTaxableAmount", + "type": "string", + "doc": "Total taxable amount for all line items." }, + { "name": "totalTaxIncludedInPrice", + "type": "string", + "doc": "Total amount of `totalTax` that is included in price. Applies to line items with `taxIncludedInPrice` set to `true`." } ], + "extra": + { }, + "labels": [] }, + { "name": "addressIndex", + "locations": + [ { "lineno": 154, + "filename": "tax-calculation-spi.js" } ], + "docs": + { "summary": "Index of the address from `addresses` to use to calculate tax for this specific line item. The index is zero-based.", + "links": [], + "examples": [], + "extra": + { } }, + "members": + [ { "name": "singleAddress", + "type": "number", + "doc": "Single address to use for a sale location when only one address is required for tax calculations. The index is zero-based.", + "optional": true }, + { "name": "multipleAddresses", + "type": "billing-tax-calculation.MultipleAddresses", + "doc": "Multiple addresses to use for a sale. For example, some tax calculations may require both the address where an item is shipped from, as well as the address the item is shipped to.", + "optional": true } ], + "extra": + { "oneOfGroups": + [ { "name": "addressIndexOptions", + "members": + [ "singleAddress", + "multipleAddresses" ] } ] }, + "labels": [] } ], + "extra": + { } } \ No newline at end of file