{"id":"9bb1ec77-09c3-4607-8c34-2e6989cca008","createdDate":"2024-05-23T13:00:26.789Z","updatedDate":"2024-05-23T13:00:26.789Z","resourceId":"6af34c5d-ea5a-47dd-a73f-bb201b356a3d","api":{"schema":{"object":{"displayName":" Object","description":"","slug":"object","$ref":"","legacyExamples":[],"sourceRepo":"git@github.com:wix-private/premium.git","SPIService":"wix.premium.customcharges.spi.v1.CustomChargesProvider"},"methods":[{"summary":"Get Charge Limit","description":"Wix calls this endpoint to retrieve the initial charge limit for a paid instance\nof your app. This happens every time a customer is upgrading to a paid version of\nyour app.\n\nYou can't update the charge limit after you've set an initial\nvalue. Customers can increase the limit in their site's dashboard, currently they\naren't allowed to decrease it.","operationId":"wix.premium.customcharges.spi.v1.CustomChargesProvider.GetChargeLimit","parameters":[],"responses":{"200":{"$ref":"#/components/schemas/wix.premium.customcharges.spi.v1.GetChargeLimitResponse","description":""}},"deprecated":false,"servers":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"GetChargeLimitRequest","description":"","properties":{"subscriptionId":{"description":"ID of the subscription for which Wix retrieves the charge limit. Equals\n`null` in case Wix hasn't created the subscription when retrieving an\ninitial charge limit. To track usage and billing for apps, we recommend to\nuse `instanceId` instead of the `subscriptionId`.","format":"GUID","title":"subscriptionId","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"currency":{"description":"Supported values: `AUD`, `BRL`, `CAD`, `EUR`, `GBP`, `ILS`, `INR`, `JPY`, `MXN`, `PLN`, `RUB`, `TRY`, `USD`.\n\n3-letter currency code in\n[ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes)\nformat of the charge limit. Wix may add supported currencies in the future.","format":"CURRENCY","title":"currency","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}}},"deprecated":false}}}},"x-wix-docs":{"triggeredEvents":[],"serviceName":"wix.premium.customcharges.spi.v1.CustomChargesProvider","errors":[],"exposure":"PUBLIC","maturity":"BETA","permissions":[],"externalPermissionScopes":[],"protoArtifactId":"com.wixpress.premium.customcharges:custom-charges-spi","serviceArtifactId":"com.wixpress.premium.customcharges.spi.custom-charges","labels":[{"identifier":"BETA"},{"identifier":"exposure","values":["PUBLIC"]}],"rpcMethodDetails":{"requestMessage":"wix.premium.customcharges.spi.v1.GetChargeLimitRequest","responseMessage":"wix.premium.customcharges.spi.v1.GetChargeLimitResponse"},"legacyExamples":[{"name":"GetChargeLimit","type":"METHOD","content":{"title":"Return an app instance's initial charge limit.","description":"The data payload includes the following object as an encoded JWT. Here, we show the request and response objects decoded.","request":"curl -X POST \\\n'https://provider.example.com/v1/charge-limit' \\\n-H 'Authorization: ' \\\n-d '{\n \"data\": {\n \"request\": {\n \"subscriptionId\": \"efa6b37d-74c6-44bb-b639-28c4af3957dd\",\n \"currency\": \"USD\"\n },\n \"metadata\": {\n \"requestId\": \"1680014776.67327419774788218037\",\n \"identity\": {\n \"identityType\": \"APP\",\n \"appId\": \"365288ae-38f4-4932-92d5-d45c596c7260\"\n },\n \"instanceId\": \"3aa496c3-aa49-4369-84e6-3fa1876f191d\"\n }\n },\n \"aud\": \"6675724b-bf3e-482a-9a00-65616953b570\",\n \"iss\": \"wix.com\",\n \"iat\": 1680014777,\n \"exp\": 1683614777\n}'","response":"{\n \"chargeLimit\": \"1000.00\"\n}"}}],"sourceRepo":"git@github.com:wix-private/premium.git"},"httpMethod":"post","path":"/v1/charge-limit","rpcOnly":false,"triggeredEvents":[],"serviceName":"wix.premium.customcharges.spi.v1.CustomChargesProvider","errors":[],"exposure":"PUBLIC","maturity":"BETA","permissions":[],"externalPermissionScopes":[],"protoArtifactId":"com.wixpress.premium.customcharges:custom-charges-spi","serviceArtifactId":"com.wixpress.premium.customcharges.spi.custom-charges","labels":[{"identifier":"BETA"},{"identifier":"exposure","values":["PUBLIC"]}],"rpcMethodDetails":{"requestMessage":"wix.premium.customcharges.spi.v1.GetChargeLimitRequest","responseMessage":"wix.premium.customcharges.spi.v1.GetChargeLimitResponse"},"legacyExamples":[{"name":"GetChargeLimit","type":"METHOD","content":{"title":"Return an app instance's initial charge limit.","description":"The data payload includes the following object as an encoded JWT. Here, we show the request and response objects decoded.","request":"curl -X POST \\\n'https://provider.example.com/v1/charge-limit' \\\n-H 'Authorization: ' \\\n-d '{\n \"data\": {\n \"request\": {\n \"subscriptionId\": \"efa6b37d-74c6-44bb-b639-28c4af3957dd\",\n \"currency\": \"USD\"\n },\n \"metadata\": {\n \"requestId\": \"1680014776.67327419774788218037\",\n \"identity\": {\n \"identityType\": \"APP\",\n \"appId\": \"365288ae-38f4-4932-92d5-d45c596c7260\"\n },\n \"instanceId\": \"3aa496c3-aa49-4369-84e6-3fa1876f191d\"\n }\n },\n \"aud\": \"6675724b-bf3e-482a-9a00-65616953b570\",\n \"iss\": \"wix.com\",\n \"iat\": 1680014777,\n \"exp\": 1683614777\n}'","response":"{\n \"chargeLimit\": \"1000.00\"\n}"}}],"sourceRepo":"git@github.com:wix-private/premium.git","contentLink":{"displayName":"Get Charge Limit","slugifiedName":"get-charge-limit"}},{"summary":"List Charges","description":"Wix calls this endpoint to retrieve a list of charges for a paid instance\nof your app. This happens when Wix creates an invoice or in case the customer\nwants to preview how much your app would charge them at the moment.\n\nYou must return the charges in the currency that's specified in the request,\nyou aren't allowed to return more than 5 charges, and their sum must be lower\nthan the charge limit.\n\nYou may not bill customers for any usage that didn’t occur during the period\nWix specifies when retrieving the charges. If Wix discovers that your app has\ncharged customers for usage outside of an invoice's specified period, we may\ntake action such as blocking your app from charging the customer, removing\nyour app from the Wix App Market, revoking your access to the Wix developer\nprogram, or pursuing legal action to recover damages caused by overcharging.\nWe understand that mistakes can happen and encourage you to contact\n[the Wix App Market team](https://devforum.wix.com/kb/en/contact) immediately if you\nbecome aware of any overcharging issues so that we can work together to\nresolve the situation.","operationId":"wix.premium.customcharges.spi.v1.CustomChargesProvider.ListCharges","parameters":[],"responses":{"200":{"$ref":"#/components/schemas/wix.premium.customcharges.spi.v1.ListChargesResponse","description":""}},"deprecated":false,"servers":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"ListChargesRequest","description":"","properties":{"subscriptionId":{"description":"ID of the subscription for which Wix retrieves your custom charges.\nTo track usage and billing for apps, we recommend to use `instanceId` instead\nof the `subscriptionId`.","format":"GUID","title":"subscriptionId","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"currency":{"description":"Supported values: `AUD`, `BRL`, `CAD`, `EUR`, `GBP`, `ILS`, `INR`, `JPY`, `MXN`, `PLN`, `RUB`, `TRY`, `USD`.\n\n3-letter currency code in\n[ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes)\nformat of your charges to return. Wix may add supported currencies in the future.","format":"CURRENCY","title":"currency","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"periodStart":{"description":"Begin of the period Wix retrieves the app instance's charges for in\n`YYYY-MM-DDThh:mm:ss.sssZ` format.","title":"periodStart","type":"string","format":"date-time","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"periodEnd":{"description":"End of the period Wix retrieves the app instance's charges for in\n`YYYY-MM-DDThh:mm:ss.sssZ` format.","title":"periodEnd","type":"string","format":"date-time","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"intent":{"description":"Information about what Wix intends to do with the retrieved charges.\n\n+ `\"DISPLAY_ONLY\"`: Inform the customer about how much your app would charge them at the moment. Wix doesn't create an invoice.\n+ `\"CREATE_INVOICE\"`: Create an invoice for the customer.","title":"intent","type":"string","$ref":"#/components/schemas/wix.premium.customcharges.spi.v1.ListChargesRequest.Intent","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}}},"deprecated":false}}}},"x-wix-docs":{"triggeredEvents":[],"serviceName":"wix.premium.customcharges.spi.v1.CustomChargesProvider","errors":[],"exposure":"PUBLIC","maturity":"BETA","permissions":[],"externalPermissionScopes":[],"protoArtifactId":"com.wixpress.premium.customcharges:custom-charges-spi","serviceArtifactId":"com.wixpress.premium.customcharges.spi.custom-charges","labels":[{"identifier":"BETA"},{"identifier":"exposure","values":["PUBLIC"]}],"rpcMethodDetails":{"requestMessage":"wix.premium.customcharges.spi.v1.ListChargesRequest","responseMessage":"wix.premium.customcharges.spi.v1.ListChargesResponse"},"legacyExamples":[{"name":"ListCharges","type":"METHOD","content":{"title":"Return your app's custom charges.","description":"The data payload includes the following object as an encoded JWT. Here, we show the request and response objects decoded.","request":"curl -X POST \\\n'https://provider.example.com/v1/charges' \\\n-H 'Authorization: ' \\\n-d '{\n \"data\": {\n \"request\": {\n \"subscriptionId\": \"efa6b37d-74c6-44bb-b639-28c4af3957dd\",\n \"currency\": \"USD\",\n \"periodStart\": 1677674012000,\n \"periodEnd\": 1680179612000,\n \"intent\": \"CREATE_INVOICE\"\n },\n \"metadata\": {\n \"requestId\": \"1680014776.67327419774788218037\",\n \"identity\": {\n \"identityType\": \"APP\",\n \"appId\": \"365288ae-38f4-4932-92d5-d45c596c7260\"\n },\n \"instanceId\": \"3aa496c3-aa49-4369-84e6-3fa1876f191d\"\n }\n },\n \"aud\": \"6675724b-bf3e-482a-9a00-65616953b570\",\n \"iss\": \"wix.com\",\n \"iat\": 1680014777,\n \"exp\": 1683614777\n}'","response":"{\n \"charges\": [\n {\n \"id\": \"Some Charge Id 1\",\n \"description\": \"Setup fee\",\n \"amount\": \"200.00\"\n },\n {\n \"id\": \"Some Charge Id 2\",\n \"description\": \"Usage charges\",\n \"amount\": \"300.00\"\n }\n ]\n}"}}],"sourceRepo":"git@github.com:wix-private/premium.git"},"httpMethod":"post","path":"/v1/charges","rpcOnly":false,"triggeredEvents":[],"serviceName":"wix.premium.customcharges.spi.v1.CustomChargesProvider","errors":[],"exposure":"PUBLIC","maturity":"BETA","permissions":[],"externalPermissionScopes":[],"protoArtifactId":"com.wixpress.premium.customcharges:custom-charges-spi","serviceArtifactId":"com.wixpress.premium.customcharges.spi.custom-charges","labels":[{"identifier":"BETA"},{"identifier":"exposure","values":["PUBLIC"]}],"rpcMethodDetails":{"requestMessage":"wix.premium.customcharges.spi.v1.ListChargesRequest","responseMessage":"wix.premium.customcharges.spi.v1.ListChargesResponse"},"legacyExamples":[{"name":"ListCharges","type":"METHOD","content":{"title":"Return your app's custom charges.","description":"The data payload includes the following object as an encoded JWT. Here, we show the request and response objects decoded.","request":"curl -X POST \\\n'https://provider.example.com/v1/charges' \\\n-H 'Authorization: ' \\\n-d '{\n \"data\": {\n \"request\": {\n \"subscriptionId\": \"efa6b37d-74c6-44bb-b639-28c4af3957dd\",\n \"currency\": \"USD\",\n \"periodStart\": 1677674012000,\n \"periodEnd\": 1680179612000,\n \"intent\": \"CREATE_INVOICE\"\n },\n \"metadata\": {\n \"requestId\": \"1680014776.67327419774788218037\",\n \"identity\": {\n \"identityType\": \"APP\",\n \"appId\": \"365288ae-38f4-4932-92d5-d45c596c7260\"\n },\n \"instanceId\": \"3aa496c3-aa49-4369-84e6-3fa1876f191d\"\n }\n },\n \"aud\": \"6675724b-bf3e-482a-9a00-65616953b570\",\n \"iss\": \"wix.com\",\n \"iat\": 1680014777,\n \"exp\": 1683614777\n}'","response":"{\n \"charges\": [\n {\n \"id\": \"Some Charge Id 1\",\n \"description\": \"Setup fee\",\n \"amount\": \"200.00\"\n },\n {\n \"id\": \"Some Charge Id 2\",\n \"description\": \"Usage charges\",\n \"amount\": \"300.00\"\n }\n ]\n}"}}],"sourceRepo":"git@github.com:wix-private/premium.git","contentLink":{"displayName":"List Charges","slugifiedName":"list-charges"}},{"summary":"Charges Rejected Event","description":"Triggered in case Wix doesn't accept the charges you've returned in the\n[List Charges](https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/custom-charges-provider-v1/list-charges)\nendpoint.\n\n\nYou aren't allowed to charge a site owner more than the charge limit. Wix\ncall List Charges in regular intervals until the sum of all charges is lower than the\ncharge limit. Wix doesn't create an invoice in case the charges aren't accepted.","operationId":"wix.premium.customcharges.spi.v1.CustomChargesProvider.ChargesRejectedEvent","parameters":[],"responses":{"200":{"$ref":"#/components/schemas/wix.premium.customcharges.spi.v1.ChargesRejectedResponse","description":""}},"deprecated":false,"servers":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"ChargesRejectedRequest","description":"","properties":{"subscriptionId":{"description":"ID of the subscription for which Wix hasn't accepted your custom charges.\nTo track usage and billing for apps, we recommend to use `instanceId` instead\nof the `subscriptionId`.","format":"GUID","title":"subscriptionId","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"currency":{"description":"Supported values: `AUD`, `BRL`, `CAD`, `EUR`, `GBP`, `ILS`, `INR`, `JPY`, `MXN`, `PLN`, `RUB`, `TRY`, `USD`.\n\n3-letter currency code in\n[ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes)\nformat of the charges. Wix may add supported currencies in the future.","format":"CURRENCY","title":"currency","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"chargeIds":{"description":"IDs of the rejected charges.\n\nMax: 5 charges","maxItems":5,"title":"chargeIds","type":"array","items":{"type":"string"},"x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"chargeLimit":{"description":"Maximum amount that your app may charge the customer per billing cycle.\n\nMin: `0.50`","format":"DECIMAL_VALUE","title":"chargeLimit","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA","decimalValue":{"gt":"0.00"}}},"reasons":{"description":"Information about why Wix has rejected your app's charges.\n\n+ `\"UNKNOWN_REASON\"`: There is no information about why Wix has rejected the charges.\n+ `\"CHARGE_LIMIT_EXCEEDED\"`: The sum of the charges is higher than the limit that you may charge the customer per billing cycle.\n+ `\"TOO_MANY_CHARGES\"`: You can't provide more than 5 charges per invoice.\n+ `\"INVALID_FORMAT\"`: You must submit charges as whole numbers or use a dot to separate major and minor units. For example, `10` or `1.50`. Currently, Wix doesn't validate whether the submitted number of decimals for the minor unit is supported for the given currency.\n\nMax: 20 reasons","maxItems":20,"title":"reasons","type":"array","enum":true,"items":{"$ref":"#/components/schemas/wix.premium.customcharges.spi.v1.ChargesRejectedRequest.ChargesRejectedReason"},"x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}}},"deprecated":false}}}},"x-wix-docs":{"triggeredEvents":[],"serviceName":"wix.premium.customcharges.spi.v1.CustomChargesProvider","errors":[],"exposure":"PUBLIC","maturity":"BETA","permissions":[],"externalPermissionScopes":[],"protoArtifactId":"com.wixpress.premium.customcharges:custom-charges-spi","serviceArtifactId":"com.wixpress.premium.customcharges.spi.custom-charges","labels":[{"identifier":"BETA"},{"identifier":"exposure","values":["PUBLIC"]}],"rpcMethodDetails":{"requestMessage":"wix.premium.customcharges.spi.v1.ChargesRejectedRequest","responseMessage":"wix.premium.customcharges.spi.v1.ChargesRejectedResponse"},"legacyExamples":[{"name":"ChargesRejectedEvent","type":"METHOD","content":{"title":"Get notified when Wix doesn't accept your custom charges.","description":"The data payload includes the following object as an encoded JWT. Here, we show the request and response objects decoded.","request":"curl -X POST \\\n'https://provider.example.com/v1/charges-rejected' \\\n-H 'Authorization: ' \\\n-d '{\n \"data\": {\n \"request\": {\n \"subscriptionId\": \"efa6b37d-74c6-44bb-b639-28c4af3957dd\",\n \"currency\": \"USD\",\n \"chargeIds\": [\n \"Some Charge Id 1\",\n \"Some Charge Id 2\"\n ],\n \"chargeLimit\": \"1000.00\",\n \"reasons\": [\n \"CHARGE_LIMIT_EXCEEDED\"\n ]\n },\n \"metadata\": {\n \"requestId\": \"1680014776.67327419774788218037\",\n \"identity\": {\n \"identityType\": \"APP\",\n \"appId\": \"365288ae-38f4-4932-92d5-d45c596c7260\"\n },\n \"instanceId\": \"3aa496c3-aa49-4369-84e6-3fa1876f191d\"\n }\n },\n \"aud\": \"6675724b-bf3e-482a-9a00-65616953b570\",\n \"iss\": \"wix.com\",\n \"iat\": 1680014777,\n \"exp\": 1683614777\n}'"}}],"sourceRepo":"git@github.com:wix-private/premium.git"},"httpMethod":"post","path":"/v1/charges-rejected","rpcOnly":false,"triggeredEvents":[],"serviceName":"wix.premium.customcharges.spi.v1.CustomChargesProvider","errors":[],"exposure":"PUBLIC","maturity":"BETA","permissions":[],"externalPermissionScopes":[],"protoArtifactId":"com.wixpress.premium.customcharges:custom-charges-spi","serviceArtifactId":"com.wixpress.premium.customcharges.spi.custom-charges","labels":[{"identifier":"BETA"},{"identifier":"exposure","values":["PUBLIC"]}],"rpcMethodDetails":{"requestMessage":"wix.premium.customcharges.spi.v1.ChargesRejectedRequest","responseMessage":"wix.premium.customcharges.spi.v1.ChargesRejectedResponse"},"legacyExamples":[{"name":"ChargesRejectedEvent","type":"METHOD","content":{"title":"Get notified when Wix doesn't accept your custom charges.","description":"The data payload includes the following object as an encoded JWT. Here, we show the request and response objects decoded.","request":"curl -X POST \\\n'https://provider.example.com/v1/charges-rejected' \\\n-H 'Authorization: ' \\\n-d '{\n \"data\": {\n \"request\": {\n \"subscriptionId\": \"efa6b37d-74c6-44bb-b639-28c4af3957dd\",\n \"currency\": \"USD\",\n \"chargeIds\": [\n \"Some Charge Id 1\",\n \"Some Charge Id 2\"\n ],\n \"chargeLimit\": \"1000.00\",\n \"reasons\": [\n \"CHARGE_LIMIT_EXCEEDED\"\n ]\n },\n \"metadata\": {\n \"requestId\": \"1680014776.67327419774788218037\",\n \"identity\": {\n \"identityType\": \"APP\",\n \"appId\": \"365288ae-38f4-4932-92d5-d45c596c7260\"\n },\n \"instanceId\": \"3aa496c3-aa49-4369-84e6-3fa1876f191d\"\n }\n },\n \"aud\": \"6675724b-bf3e-482a-9a00-65616953b570\",\n \"iss\": \"wix.com\",\n \"iat\": 1680014777,\n \"exp\": 1683614777\n}'"}}],"sourceRepo":"git@github.com:wix-private/premium.git","contentLink":{"displayName":"Charges Rejected Event","slugifiedName":"charges-rejected-event"}},{"summary":"Invoice Created Event","description":"Triggered in case Wix creates an invoice that includes charges for an instance\nof your app.","operationId":"wix.premium.customcharges.spi.v1.CustomChargesProvider.InvoiceCreatedEvent","parameters":[],"responses":{"200":{"$ref":"#/components/schemas/wix.premium.customcharges.spi.v1.InvoiceCreatedResponse","description":""}},"deprecated":false,"servers":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"InvoiceCreatedRequest","description":"","properties":{"subscriptionId":{"description":"ID of the subscription for which Wix has created an invoice that includes\nyour custom charges. To track usage and billing for apps, we recommend to use\n`instanceId` instead of the `subscriptionId`.","format":"GUID","title":"subscriptionId","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"currency":{"description":"Supported values: `AUD`, `BRL`, `CAD`, `EUR`, `GBP`, `ILS`, `INR`, `JPY`, `MXN`, `PLN`, `RUB`, `TRY`, `USD`.\n\n3-letter currency code in\n[ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes)\nformat of the charges. Wix may add supported currencies in the future.","format":"CURRENCY","title":"currency","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"invoiceId":{"description":"ID of the created invoice.","title":"invoiceId","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"lineItems":{"description":"Line items included in the invoice.","maxItems":5,"title":"lineItems","type":"array","items":{"$ref":"#/components/schemas/wix.premium.customcharges.spi.v1.InvoiceLineItem"},"x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}}},"deprecated":false}}}},"x-wix-docs":{"triggeredEvents":[],"serviceName":"wix.premium.customcharges.spi.v1.CustomChargesProvider","errors":[],"exposure":"PUBLIC","maturity":"BETA","permissions":[],"externalPermissionScopes":[],"protoArtifactId":"com.wixpress.premium.customcharges:custom-charges-spi","serviceArtifactId":"com.wixpress.premium.customcharges.spi.custom-charges","labels":[{"identifier":"BETA"},{"identifier":"exposure","values":["PUBLIC"]}],"rpcMethodDetails":{"requestMessage":"wix.premium.customcharges.spi.v1.InvoiceCreatedRequest","responseMessage":"wix.premium.customcharges.spi.v1.InvoiceCreatedResponse"},"legacyExamples":[{"name":"InvoiceCreatedEvent","type":"METHOD","content":{"title":"Get notified when Wix creates an invoice with your custom charges.","description":"The data payload includes the following object as an encoded JWT. Here, we show the request and response objects decoded.","request":"curl -X POST \\\n'https://provider.example.com/v1/invoice-created' \\\n-H 'Authorization: ' \\\n-d '{\n \"data\": {\n \"request\": {\n \"subscriptionId\": \"efa6b37d-74c6-44bb-b639-28c4af3957dd\",\n \"currency\": \"USD\",\n \"invoiceId\": 43434213,\n \"lineItems\": [\n {\n \"chargeId\": \"Some Charge Id 1\",\n \"amount\": \"200.00\",\n \"id\": \"f322c4bf-7edb-42f8-b0c2-162b51d4ad75\"\n },\n {\n \"chargeId\": \"Some Charge Id 2\",\n \"amount\": \"300.00\",\n \"id\": \"4faa44b4-654c-411d-803d-be816e03726e\"\n }\n ]\n },\n \"metadata\": {\n \"requestId\": \"1680014776.67327419774788218037\",\n \"identity\": {\n \"identityType\": \"APP\",\n \"appId\": \"365288ae-38f4-4932-92d5-d45c596c7260\"\n },\n \"instanceId\": \"3aa496c3-aa49-4369-84e6-3fa1876f191d\"\n }\n },\n \"aud\": \"6675724b-bf3e-482a-9a00-65616953b570\",\n \"iss\": \"wix.com\",\n \"iat\": 1680014777,\n \"exp\": 1683614777\n}'"}}],"sourceRepo":"git@github.com:wix-private/premium.git"},"httpMethod":"post","path":"/v1/invoice-created","rpcOnly":false,"triggeredEvents":[],"serviceName":"wix.premium.customcharges.spi.v1.CustomChargesProvider","errors":[],"exposure":"PUBLIC","maturity":"BETA","permissions":[],"externalPermissionScopes":[],"protoArtifactId":"com.wixpress.premium.customcharges:custom-charges-spi","serviceArtifactId":"com.wixpress.premium.customcharges.spi.custom-charges","labels":[{"identifier":"BETA"},{"identifier":"exposure","values":["PUBLIC"]}],"rpcMethodDetails":{"requestMessage":"wix.premium.customcharges.spi.v1.InvoiceCreatedRequest","responseMessage":"wix.premium.customcharges.spi.v1.InvoiceCreatedResponse"},"legacyExamples":[{"name":"InvoiceCreatedEvent","type":"METHOD","content":{"title":"Get notified when Wix creates an invoice with your custom charges.","description":"The data payload includes the following object as an encoded JWT. Here, we show the request and response objects decoded.","request":"curl -X POST \\\n'https://provider.example.com/v1/invoice-created' \\\n-H 'Authorization: ' \\\n-d '{\n \"data\": {\n \"request\": {\n \"subscriptionId\": \"efa6b37d-74c6-44bb-b639-28c4af3957dd\",\n \"currency\": \"USD\",\n \"invoiceId\": 43434213,\n \"lineItems\": [\n {\n \"chargeId\": \"Some Charge Id 1\",\n \"amount\": \"200.00\",\n \"id\": \"f322c4bf-7edb-42f8-b0c2-162b51d4ad75\"\n },\n {\n \"chargeId\": \"Some Charge Id 2\",\n \"amount\": \"300.00\",\n \"id\": \"4faa44b4-654c-411d-803d-be816e03726e\"\n }\n ]\n },\n \"metadata\": {\n \"requestId\": \"1680014776.67327419774788218037\",\n \"identity\": {\n \"identityType\": \"APP\",\n \"appId\": \"365288ae-38f4-4932-92d5-d45c596c7260\"\n },\n \"instanceId\": \"3aa496c3-aa49-4369-84e6-3fa1876f191d\"\n }\n },\n \"aud\": \"6675724b-bf3e-482a-9a00-65616953b570\",\n \"iss\": \"wix.com\",\n \"iat\": 1680014777,\n \"exp\": 1683614777\n}'"}}],"sourceRepo":"git@github.com:wix-private/premium.git","contentLink":{"displayName":"Invoice Created Event","slugifiedName":"invoice-created-event"}},{"summary":"Charge Limit Updated Event","description":"Triggered in case the charge limit for an instance of your app is updated.\n\n\nYou can't update the charge limit after you've set an initial\nvalue. Site owners can increase the limit in their site's dashboard,\ncurrently they aren't allowed to decrease it.","operationId":"wix.premium.customcharges.spi.v1.CustomChargesProvider.ChargeLimitUpdatedEvent","parameters":[],"responses":{"200":{"$ref":"#/components/schemas/wix.premium.customcharges.spi.v1.ChargeLimitUpdatedResponse","description":""}},"deprecated":false,"servers":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"ChargeLimitUpdatedRequest","description":"","properties":{"subscriptionId":{"description":"ID of the subscription for which the charge limit has been updated.\nTo track usage and billing for apps, we recommend to use `instanceId` instead\nof the `subscriptionId`.","format":"GUID","title":"subscriptionId","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"currency":{"description":"Supported values: `AUD`, `BRL`, `CAD`, `EUR`, `GBP`, `ILS`, `INR`, `JPY`, `MXN`, `PLN`, `RUB`, `TRY`, `USD`.\n\n3-letter currency code in\n[ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes)\nformat of the charges. Wix may add supported currencies in the future.","format":"CURRENCY","title":"currency","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"chargeLimit":{"description":"Updated charge limit.","format":"DECIMAL_VALUE","title":"chargeLimit","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}}},"deprecated":false}}}},"x-wix-docs":{"triggeredEvents":[],"serviceName":"wix.premium.customcharges.spi.v1.CustomChargesProvider","errors":[],"exposure":"PUBLIC","maturity":"BETA","permissions":[],"externalPermissionScopes":[],"protoArtifactId":"com.wixpress.premium.customcharges:custom-charges-spi","serviceArtifactId":"com.wixpress.premium.customcharges.spi.custom-charges","labels":[{"identifier":"BETA"},{"identifier":"exposure","values":["PUBLIC"]}],"rpcMethodDetails":{"requestMessage":"wix.premium.customcharges.spi.v1.ChargeLimitUpdatedRequest","responseMessage":"wix.premium.customcharges.spi.v1.ChargeLimitUpdatedResponse"},"legacyExamples":[{"name":"ChargeLimitUpdatedEvent","type":"METHOD","content":{"title":"Get notified when a customer updates the charge limit.","description":"The data payload includes the following object as an encoded JWT. Here, we show the request and response objects decoded.","request":"curl -X POST \\\n'https://provider.example.com/v1/limit-updated' \\\n-H 'Authorization: ' \\\n-d '{\n \"data\": {\n \"request\": {\n \"subscriptionId\": \"efa6b37d-74c6-44bb-b639-28c4af3957dd\",\n \"currency\": \"USD\",\n \"chargeLimit\": \"1000.00\"\n },\n \"metadata\": {\n \"requestId\": \"1680014776.67327419774788218037\",\n \"identity\": {\n \"identityType\": \"APP\",\n \"appId\": \"365288ae-38f4-4932-92d5-d45c596c7260\"\n },\n \"instanceId\": \"3aa496c3-aa49-4369-84e6-3fa1876f191d\"\n }\n },\n \"aud\": \"6675724b-bf3e-482a-9a00-65616953b570\",\n \"iss\": \"wix.com\",\n \"iat\": 1680014777,\n \"exp\": 1683614777\n}'","response":"{\n}"}}],"sourceRepo":"git@github.com:wix-private/premium.git"},"httpMethod":"post","path":"/v1/limit-updated","rpcOnly":false,"triggeredEvents":[],"serviceName":"wix.premium.customcharges.spi.v1.CustomChargesProvider","errors":[],"exposure":"PUBLIC","maturity":"BETA","permissions":[],"externalPermissionScopes":[],"protoArtifactId":"com.wixpress.premium.customcharges:custom-charges-spi","serviceArtifactId":"com.wixpress.premium.customcharges.spi.custom-charges","labels":[{"identifier":"BETA"},{"identifier":"exposure","values":["PUBLIC"]}],"rpcMethodDetails":{"requestMessage":"wix.premium.customcharges.spi.v1.ChargeLimitUpdatedRequest","responseMessage":"wix.premium.customcharges.spi.v1.ChargeLimitUpdatedResponse"},"legacyExamples":[{"name":"ChargeLimitUpdatedEvent","type":"METHOD","content":{"title":"Get notified when a customer updates the charge limit.","description":"The data payload includes the following object as an encoded JWT. Here, we show the request and response objects decoded.","request":"curl -X POST \\\n'https://provider.example.com/v1/limit-updated' \\\n-H 'Authorization: ' \\\n-d '{\n \"data\": {\n \"request\": {\n \"subscriptionId\": \"efa6b37d-74c6-44bb-b639-28c4af3957dd\",\n \"currency\": \"USD\",\n \"chargeLimit\": \"1000.00\"\n },\n \"metadata\": {\n \"requestId\": \"1680014776.67327419774788218037\",\n \"identity\": {\n \"identityType\": \"APP\",\n \"appId\": \"365288ae-38f4-4932-92d5-d45c596c7260\"\n },\n \"instanceId\": \"3aa496c3-aa49-4369-84e6-3fa1876f191d\"\n }\n },\n \"aud\": \"6675724b-bf3e-482a-9a00-65616953b570\",\n \"iss\": \"wix.com\",\n \"iat\": 1680014777,\n \"exp\": 1683614777\n}'","response":"{\n}"}}],"sourceRepo":"git@github.com:wix-private/premium.git","contentLink":{"displayName":"Charge Limit Updated Event","slugifiedName":"charge-limit-updated-event"}}],"webhooks":[],"articles":[{"displayName":"Introduction","slugifyName":"introduction","content":"# About the Custom Charges Service Plugin\n\nThe Custom Charges service plugin (formerly SPI) allows you to manage what customers must pay to use\nyour app. This includes regularly recurring base prices, installation and usage\nfees, and any other custom charges.\n\nWith the Custom Charges service plugin, you can:\n\n+ Add your app's charges to the invoice that Wix sends to site owners.\n+ Receive notifications about charges that Wix doesn't accept, created\n invoices, or when customers increase their charge limit.\n+ Keep your customers informed about how much your app would charge them if Wix\n were to send an invoice at this moment.\n\nSee the [App Instance API](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::5a829a3f-423e-484e-80c5-b70320bf9383slug::introduction*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/introduction)\nfor more details about the notifications you receive when a customer installs\nan instance of your app on their site.\n\n## How to become a provider\n\nWhen configuring your app in the [Wix Developers Center](fallback::https://dev.wix.com):\n\n+ Set up [Usage-Based Pricing](fallback::https://dev.wix.com/docs/build-apps/build-your-app/pricing-plans/usage-based-pricing)\n for your app. Note that Usage-Based Pricing is in Alpha and may change in the\n future.\n+ Add a __Premium Custom Charges__ integration component.\n+ Use the JSON editor to update the `baseUri`. Make sure to include only\n the base part of your integration's URI. For example, if Wix should call your\n integration at `https://provider.example.com/v1/charge-limit` for the\n [Get Charge Limit](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::6af34c5d-ea5a-47dd-a73f-bb201b356a3dslug::get-charge-limit*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/custom-charges-provider-v1/get-charge-limit)\n endpoint set `{\"baseUri\": \"https://provider.example.com\"}`.\n\n## Before you begin\n\nIt’s important to note the following points before starting to code:\n\n+ Before you can implement the Custom Charges service plugin, it's essential to set up\n [Usage-Based Pricing](fallback::https://dev.wix.com/docs/build-apps/build-your-app/pricing-plans/usage-based-pricing)\n for your app in the [Wix Developers Center](fallback::https://dev.wix.com/). Note that\n you have to [submit a request](fallback::https://devforum.wix.com/account/connect-sso?redirectUrl=https:~2F~2Fdevforum.wix.com~2Fen~2Fcontact)\n to enable Usage-Based Pricing. Keep in mind that Usage-Based Pricing is\n currently in Alpha, this means it's still in development and may change in\n the future.\n+ You can't bill your customers before they\n [upgrade](fallback::https://support.wix.com/en/article/upgrading-an-app-from-the-wix-app-market)\n to a paid version of your app.\n+ You're able to include up to 5 custom charges per invoice.\n+ You must set an initial charge limit and can't bill customers more than this\n limit per billing cycle. You can't change the limit later, but customers are\n able to increase it themselves.\n+ You receive notifications in case Wix doesn't accept the charges you return\n via the service plugin. Currently, there is no notification if the customer agrees to\n your proposed charge limit or pays an invoice.\n+ Currently, Wix supports the following currencies: `AUD`, `BRL`, `CAD`, `EUR`,\n `GBP`, `ILS`, `INR`, `JPY`, `MXN`, `PLN`, `RUB`, `TRY`, `USD`. Wix may add\n more currencies in the future.\n+ We recommend to use the `instanceId` instead of the `subscriptionId` to track\n usage and billing for apps, because this field is also used in the\n [App Management API](fallback::https://dev.wix.com/docs/rest/api-reference/app-management/about-app-management).\n+ If we discover that your app has charged customers for usage outside of an\n invoice's specified period, we may take action such as blocking your app from\n charging the customer, removing your app from the Wix App Market, revoking\n your access to the Wix developer program, or pursuing legal action to recover\n damages caused by overcharging. We understand that mistakes can happen and\n encourage you to contact\n [the Wix App Market team](fallback::https://devforum.wix.com/kb/en/contact) immediately if you\n become aware of any overcharging issues so that we can work together to\n resolve the situation.\n\n## Use cases\n\n+ [Support app upgrades](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::6af34c5d-ea5a-47dd-a73f-bb201b356a3dslug::sample-flows#support-app-upgrades*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/sample-flows#support-app-upgrades)\n+ [Bill a customer](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::6af34c5d-ea5a-47dd-a73f-bb201b356a3dslug::sample-flows#bill-a-customer*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/sample-flows#bill-a-customer)\n+ [Get Notified when an app instance is canceled](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::6af34c5d-ea5a-47dd-a73f-bb201b356a3dslug::sample-flows#get-notified-when-an-app-instance-is-canceled*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/sample-flows#get-notified-when-an-app-instance-is-canceled)\n\n## Terminology\n\n+ __App instance__: Particular installation of an app that let's you identify\n your customer. Learn more about how to retrieve the instance ID from a\n [service plugin request envelope](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::e4363000-00cd-46c7-87bc-6709e250f783#getting-started_service-provider-interface_request-envelope*fallback::https://dev.wix.com/api/rest/getting-started/service-provider-interface#getting-started_service-provider-interface_request-envelope).\n+ __Customer__: Site owner who installs your app on their Wix site.\n+ __Invoice__: Document that Wix sends to customers specifying the price they\n have to pay for using the Wix platform. Includes charges for 3rd-party apps\n associated with the site.\n+ __Charge__: Price for using your app that you can add to an invoice. You can\n add up to 5 charges per invoice.\n+ __Charge limit__: Maximum amount that you're allowed to charge customers for\n using your app per billing cycle. It helps ensure that customers are aware of\n their potential costs upfront.\n+ __Subscription ID__: Unique identifier for the agreement that specifies the\n product or service to which the customer has access to and how they are billed.\n Currently, Wix doesn't provide an API to retrieve information about\n subscriptions. In case the product is an app, we recommend to use the app\n instance ID instead of the subscription ID to track usage and billing, because\n this field is also used in the\n [App Management API](fallback::https://dev.wix.com/docs/rest/api-reference/app-management/about-app-management).\n","sourceRepo":"git@github.com:wix-private/premium.git","path":"docs/Intro.md"},{"displayName":"Sample Flows","slugifyName":"sample-flows","content":"# Custom Charges Service Plugin: Sample Use Cases & Flows\n\nThis article shares some possible use cases your app could support, as well as\na sample flow that could support each use case. This can be a helpful jumping\noff point as you plan your app's implementation.\n\n## Support app upgrades\n\nEvery time a customer upgrades an instance of your app, Wix\nretrieves an initial charge limit from your app. Wix displays this limit to the\ncustomer in the checkout page of the upgrade process. This helps customers\nunderstand how much they may have to pay maximally for using your app per\nbilling cycle.\n\nTo support app upgrades:\n\n1. Wix calls [Get Charge Limit](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::6af34c5d-ea5a-47dd-a73f-bb201b356a3dslug::get-charge-limit*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/custom-charges-provider-v1/get-charge-limit).\n2. Return the initial charge limit that your app is allowed to charge the customer per billing cycle.\n3. Wix displays the limit to the customer for approval. Note that your app can't change this limit later, but customers are able to increase it themselves.\n\n## Bill a customer\n\nYour app can add custom charges to an invoice that Wix sends to a customer\nat the end of the billing cycle.\n\nTo bill a customer:\n\n1. Wix calls [List charges](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::6af34c5d-ea5a-47dd-a73f-bb201b356a3dslug::list-charges*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/custom-charges-provider-v1/list-charges). Note that Wix sends `{\"intent\": \"CREATE_INVOICE\"}` to actually create an invoice with the charges you return. For other purposes, Wix sends `{\"intent\": \"DISPLAY_ONLY\"}`.\n2. Return up to 5 charges that Wix adds to the invoice.\n3. In case Wix accepts your charges, Wix calls [Invoice Created Event](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::6af34c5d-ea5a-47dd-a73f-bb201b356a3dslug::invoice-created-event*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/custom-charges-provider-v1/invoice-created-event) and sends the invoice to the customer.\n\n## Get notified when an app instance is canceled\n\nCurrently, you can't receive notifications when a payment for an\ninvoice has failed. If that happens, Wix sends an email to the customer and\nretries to collect the payment several times. In case all retries fail, Wix\ncancels the app instance. Your app could get notified in this situation, and\nyou could reach out to the customer.\n\nTo receive notifications when an app instance is canceled:\n\n1. Sign up for the [Paid Plan Auto Renewal Cancelled Webhook](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::5a829a3f-423e-484e-80c5-b70320bf9383slug::paid-plan-auto-renewal-cancelled*fallback::https://dev.wix.com/api/rest/app-management/apps/app-instance/paid-plan-auto-renewal-cancelled-webhook) of the App Instance API.\n2. Listen to the webhook. Wix sends `{\"cancelReason\": \"FAILED_PAYMENT\"}` in case an app instance is canceled due to a failed payment.\n3. Reach out to the relevant customer.\n","sourceRepo":"git@github.com:wix-private/premium.git","path":"docs/Flows.md"}],"components":{"schemas":{"wix.premium.customcharges.spi.v1.GetChargeLimitRequest":{"type":"object","properties":{"subscriptionId":{"description":"ID of the subscription for which Wix retrieves the charge limit. Equals\n`null` in case Wix hasn't created the subscription when retrieving an\ninitial charge limit. To track usage and billing for apps, we recommend to\nuse `instanceId` instead of the `subscriptionId`.","format":"GUID","title":"subscriptionId","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"currency":{"description":"Supported values: `AUD`, `BRL`, `CAD`, `EUR`, `GBP`, `ILS`, `INR`, `JPY`, `MXN`, `PLN`, `RUB`, `TRY`, `USD`.\n\n3-letter currency code in\n[ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes)\nformat of the charge limit. Wix may add supported currencies in the future.","format":"CURRENCY","title":"currency","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}}},"title":"GetChargeLimitRequest","description":""},"google.protobuf.StringValue":{"type":"object","properties":{"value":{"description":"","title":"value","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}}},"title":"StringValue","description":""},"wix.premium.customcharges.spi.v1.GetChargeLimitResponse":{"type":"object","properties":{"chargeLimit":{"description":"Retrieved charge limit for the app instance. You can't update the\ncharge limit after you've set an initial value. Site owners can increase the\nlimit in their site's dashboard, currently they aren't allowed to decrease it.","format":"DECIMAL_VALUE","title":"chargeLimit","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA","decimalValue":{"gt":"0.00"}}}},"title":"GetChargeLimitResponse","description":""},"wix.premium.customcharges.spi.v1.ListChargesRequest":{"type":"object","properties":{"subscriptionId":{"description":"ID of the subscription for which Wix retrieves your custom charges.\nTo track usage and billing for apps, we recommend to use `instanceId` instead\nof the `subscriptionId`.","format":"GUID","title":"subscriptionId","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"currency":{"description":"Supported values: `AUD`, `BRL`, `CAD`, `EUR`, `GBP`, `ILS`, `INR`, `JPY`, `MXN`, `PLN`, `RUB`, `TRY`, `USD`.\n\n3-letter currency code in\n[ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes)\nformat of your charges to return. Wix may add supported currencies in the future.","format":"CURRENCY","title":"currency","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"periodStart":{"description":"Begin of the period Wix retrieves the app instance's charges for in\n`YYYY-MM-DDThh:mm:ss.sssZ` format.","title":"periodStart","type":"string","format":"date-time","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"periodEnd":{"description":"End of the period Wix retrieves the app instance's charges for in\n`YYYY-MM-DDThh:mm:ss.sssZ` format.","title":"periodEnd","type":"string","format":"date-time","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"intent":{"description":"Information about what Wix intends to do with the retrieved charges.\n\n+ `\"DISPLAY_ONLY\"`: Inform the customer about how much your app would charge them at the moment. Wix doesn't create an invoice.\n+ `\"CREATE_INVOICE\"`: Create an invoice for the customer.","title":"intent","type":"string","$ref":"#/components/schemas/wix.premium.customcharges.spi.v1.ListChargesRequest.Intent","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}}},"title":"ListChargesRequest","description":""},"google.protobuf.Timestamp":{"type":"object","properties":{"seconds":{"description":"","title":"seconds","type":"integer","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"nanos":{"description":"","title":"nanos","type":"integer","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}}},"title":"Timestamp","description":""},"wix.premium.customcharges.spi.v1.ListChargesRequest.Intent":{"type":"string","description":"","title":"Intent","enum":["DISPLAY_ONLY","CREATE_INVOICE"]},"wix.premium.customcharges.spi.v1.ListChargesResponse":{"type":"object","properties":{"charges":{"description":"Retrieved charges.\n\nMax: 5 charges","maxItems":5,"title":"charges","type":"array","items":{"$ref":"#/components/schemas/wix.premium.customcharges.spi.v1.ChargeLineItem"},"x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}}},"title":"ListChargesResponse","description":""},"wix.premium.customcharges.spi.v1.ChargeLineItem":{"type":"object","properties":{"id":{"description":"ID of the charge. Make sure to save the charge ID on your servers for future\nreference. Identical to `lineItem.chargeId` in the\n[Invoice Created Event](https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/custom-charges-provider-v1/invoice-created-event).\n\nMax: 64 characters","maxLength":64,"title":"id","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"description":{"description":"Charge description.","title":"description","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"amount":{"description":"Charge amount in the currency that's specified in the request. Use a whole number\nor separate major and minor units with a dot. For example, `10` or `1.99`. If\nyou return an amount with more minor units than supported according to\n[ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes),\nWix truncates the additional minor units.\n\nMin: `0.50`","format":"DECIMAL_VALUE","title":"amount","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}}},"title":"ChargeLineItem","description":""},"wix.premium.customcharges.spi.v1.ChargesRejectedRequest":{"type":"object","properties":{"subscriptionId":{"description":"ID of the subscription for which Wix hasn't accepted your custom charges.\nTo track usage and billing for apps, we recommend to use `instanceId` instead\nof the `subscriptionId`.","format":"GUID","title":"subscriptionId","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"currency":{"description":"Supported values: `AUD`, `BRL`, `CAD`, `EUR`, `GBP`, `ILS`, `INR`, `JPY`, `MXN`, `PLN`, `RUB`, `TRY`, `USD`.\n\n3-letter currency code in\n[ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes)\nformat of the charges. Wix may add supported currencies in the future.","format":"CURRENCY","title":"currency","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"chargeIds":{"description":"IDs of the rejected charges.\n\nMax: 5 charges","maxItems":5,"title":"chargeIds","type":"array","items":{"type":"string"},"x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"chargeLimit":{"description":"Maximum amount that your app may charge the customer per billing cycle.\n\nMin: `0.50`","format":"DECIMAL_VALUE","title":"chargeLimit","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA","decimalValue":{"gt":"0.00"}}},"reasons":{"description":"Information about why Wix has rejected your app's charges.\n\n+ `\"UNKNOWN_REASON\"`: There is no information about why Wix has rejected the charges.\n+ `\"CHARGE_LIMIT_EXCEEDED\"`: The sum of the charges is higher than the limit that you may charge the customer per billing cycle.\n+ `\"TOO_MANY_CHARGES\"`: You can't provide more than 5 charges per invoice.\n+ `\"INVALID_FORMAT\"`: You must submit charges as whole numbers or use a dot to separate major and minor units. For example, `10` or `1.50`. Currently, Wix doesn't validate whether the submitted number of decimals for the minor unit is supported for the given currency.\n\nMax: 20 reasons","maxItems":20,"title":"reasons","type":"array","enum":true,"items":{"$ref":"#/components/schemas/wix.premium.customcharges.spi.v1.ChargesRejectedRequest.ChargesRejectedReason"},"x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}}},"title":"ChargesRejectedRequest","description":""},"wix.premium.customcharges.spi.v1.ChargesRejectedRequest.ChargesRejectedReason":{"type":"string","description":"","title":"ChargesRejectedReason","enum":["UNKNOWN","CHARGE_LIMIT_EXCEEDED","TOO_MANY_CHARGES","INVALID_FORMAT"]},"wix.premium.customcharges.spi.v1.ChargesRejectedResponse":{"type":"object","properties":{},"title":"ChargesRejectedResponse","description":""},"wix.premium.customcharges.spi.v1.InvoiceCreatedRequest":{"type":"object","properties":{"subscriptionId":{"description":"ID of the subscription for which Wix has created an invoice that includes\nyour custom charges. To track usage and billing for apps, we recommend to use\n`instanceId` instead of the `subscriptionId`.","format":"GUID","title":"subscriptionId","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"currency":{"description":"Supported values: `AUD`, `BRL`, `CAD`, `EUR`, `GBP`, `ILS`, `INR`, `JPY`, `MXN`, `PLN`, `RUB`, `TRY`, `USD`.\n\n3-letter currency code in\n[ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes)\nformat of the charges. Wix may add supported currencies in the future.","format":"CURRENCY","title":"currency","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"invoiceId":{"description":"ID of the created invoice.","title":"invoiceId","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"lineItems":{"description":"Line items included in the invoice.","maxItems":5,"title":"lineItems","type":"array","items":{"$ref":"#/components/schemas/wix.premium.customcharges.spi.v1.InvoiceLineItem"},"x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}}},"title":"InvoiceCreatedRequest","description":""},"wix.premium.customcharges.spi.v1.InvoiceLineItem":{"type":"object","properties":{"chargeId":{"description":"ID of the charge as returned in\n[List Charges](https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/custom-charges-provider-v1/list-charges).\n\nMax: 64 characters","maxLength":64,"title":"chargeId","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"amount":{"description":"Charge amount.","format":"DECIMAL_VALUE","title":"amount","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"id":{"description":"ID of the line item in the invoice that Wix sends to the customer.","format":"GUID","title":"id","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}}},"title":"InvoiceLineItem","description":""},"wix.premium.customcharges.spi.v1.InvoiceCreatedResponse":{"type":"object","properties":{},"title":"InvoiceCreatedResponse","description":""},"wix.premium.customcharges.spi.v1.ChargeLimitUpdatedRequest":{"type":"object","properties":{"subscriptionId":{"description":"ID of the subscription for which the charge limit has been updated.\nTo track usage and billing for apps, we recommend to use `instanceId` instead\nof the `subscriptionId`.","format":"GUID","title":"subscriptionId","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"currency":{"description":"Supported values: `AUD`, `BRL`, `CAD`, `EUR`, `GBP`, `ILS`, `INR`, `JPY`, `MXN`, `PLN`, `RUB`, `TRY`, `USD`.\n\n3-letter currency code in\n[ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes)\nformat of the charges. Wix may add supported currencies in the future.","format":"CURRENCY","title":"currency","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"chargeLimit":{"description":"Updated charge limit.","format":"DECIMAL_VALUE","title":"chargeLimit","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}}},"title":"ChargeLimitUpdatedRequest","description":""},"wix.premium.customcharges.spi.v1.ChargeLimitUpdatedResponse":{"type":"object","properties":{},"title":"ChargeLimitUpdatedResponse","description":""},"wix.premium.customcharges.spi.v1.CustomChargesConfig":{"type":"object","properties":{"baseUri":{"description":"Base part of your integration's deployment URI for the Custom Charges SPI.\nFor example `\"https://provider.example.com\"`, if Wix should call your\nintegration at `https://provider.example.com/v1/charge-limit` for the\n[Get Charge Limit]https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/custom-charges-provider-v1/get-charge-limit)\nendpoint.","$ref":"#/components/schemas/wix.common.spi.SpiBaseUri","summary":"baseUri","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}}},"title":"CustomChargesConfig","description":""},"wix.common.spi.SpiBaseUri":{"type":"object","properties":{"baseUri":{"description":"URI that will be used by the host to call the implementer. The path-suffix defined on the method will be appended to it","format":"WEB_URL","title":"baseUri","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"alternativeUris":{"description":"override method mappings per method","title":"alternativeUris","type":"array","items":{"$ref":"#/components/schemas/wix.common.spi.SpiBaseUri.AlternativeUri"},"x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}}},"title":"SpiBaseUri","description":""},"wix.common.spi.SpiBaseUri.AlternativeUri":{"type":"object","properties":{"methodName":{"description":"name of the method as it appears in the proto","minLength":3,"title":"methodName","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"absoluteUri":{"description":"absolute uri that will be used by the host to call that method. The path-suffix mapped from the method http option will NOT be appended to this URI. For TPAs. it must be https","format":"WEB_URL","title":"absoluteUri","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}}},"title":"AlternativeUri","description":""},"wix.common.spi.Context":{"type":"object","properties":{"requestId":{"description":"A unique identifier for each request. Can be used for logging / troubleshooting","title":"requestId","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"currency":{"description":"3 capital letters string representing a currency according to ISO-4217","format":"CURRENCY","title":"currency","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"identity":{"description":"The identification type and identity data","$ref":"#/components/schemas/wix.common.spi.Context.IdentificationData","summary":"identity","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"languages":{"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","title":"languages","type":"array","items":{"type":"string"},"x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"instanceId":{"description":"App instance ID of SPI in context","format":"GUID","title":"instanceId","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}}},"title":"Context","description":"this message is not directly used by any service,\nit exists to describe the expected parameters that SHOULD be provided to invoked Velo methods as part of open-platform.\ne.g. SPIs, event-handlers, etc..\nNOTE: this context object MUST be provided as the last argument in each Velo method signature.\n\nExample:\n```typescript\nexport function wixStores_onOrderCanceled(event: OrderCanceledEvent, context: Context) {\n...\n}\n```"},"wix.common.spi.Context.IdentificationData.IdentityType":{"type":"string","description":"","title":"IdentityType","enum":["UNKNOWN","ANONYMOUS_VISITOR","MEMBER","WIX_USER","APP"]},"wix.common.spi.Context.IdentificationData":{"type":"object","properties":{"identityType":{"description":"","readOnly":true,"title":"identityType","type":"string","$ref":"#/components/schemas/wix.common.spi.Context.IdentificationData.IdentityType","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}}},"title":"IdentificationData","description":"","oneOf":[{"description":"","summary":"id","$ref":"#/components/schemas/wix.common.spi.Context.IdentificationData.id"}]},"wix.common.spi.Context.IdentificationData.id":{"type":"object","title":"id","properties":{"anonymousVisitorId":{"description":"ID of a site visitor that has not logged in to the site.","format":"GUID","title":"anonymousVisitorId","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"memberId":{"description":"ID of a site visitor that has logged in to the site.","format":"GUID","title":"memberId","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"wixUserId":{"description":"ID of a Wix user (site owner, contributor, etc.).","format":"GUID","title":"wixUserId","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}},"appId":{"description":"ID of an app.","format":"GUID","title":"appId","type":"string","x-wix-docs":{"exposure":"PUBLIC","maturity":"GA"}}}}}},"title":"","description":"","fqdn":"wix.interfaces.premium.v1.custom_charges_provider"},"articles":[{"displayName":"Introduction","slugifyName":"introduction","content":"# About the Custom Charges Service Plugin\n\nThe Custom Charges service plugin (formerly SPI) allows you to manage what customers must pay to use\nyour app. This includes regularly recurring base prices, installation and usage\nfees, and any other custom charges.\n\nWith the Custom Charges service plugin, you can:\n\n+ Add your app's charges to the invoice that Wix sends to site owners.\n+ Receive notifications about charges that Wix doesn't accept, created\n invoices, or when customers increase their charge limit.\n+ Keep your customers informed about how much your app would charge them if Wix\n were to send an invoice at this moment.\n\nSee the [App Instance API](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::5a829a3f-423e-484e-80c5-b70320bf9383slug::introduction*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/introduction)\nfor more details about the notifications you receive when a customer installs\nan instance of your app on their site.\n\n## How to become a provider\n\nWhen configuring your app in the [Wix Developers Center](fallback::https://dev.wix.com):\n\n+ Set up [Usage-Based Pricing](fallback::https://dev.wix.com/docs/build-apps/build-your-app/pricing-plans/usage-based-pricing)\n for your app. Note that Usage-Based Pricing is in Alpha and may change in the\n future.\n+ Add a __Premium Custom Charges__ integration component.\n+ Use the JSON editor to update the `baseUri`. Make sure to include only\n the base part of your integration's URI. For example, if Wix should call your\n integration at `https://provider.example.com/v1/charge-limit` for the\n [Get Charge Limit](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::6af34c5d-ea5a-47dd-a73f-bb201b356a3dslug::get-charge-limit*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/custom-charges-provider-v1/get-charge-limit)\n endpoint set `{\"baseUri\": \"https://provider.example.com\"}`.\n\n## Before you begin\n\nIt’s important to note the following points before starting to code:\n\n+ Before you can implement the Custom Charges service plugin, it's essential to set up\n [Usage-Based Pricing](fallback::https://dev.wix.com/docs/build-apps/build-your-app/pricing-plans/usage-based-pricing)\n for your app in the [Wix Developers Center](fallback::https://dev.wix.com/). Note that\n you have to [submit a request](fallback::https://devforum.wix.com/account/connect-sso?redirectUrl=https:~2F~2Fdevforum.wix.com~2Fen~2Fcontact)\n to enable Usage-Based Pricing. Keep in mind that Usage-Based Pricing is\n currently in Alpha, this means it's still in development and may change in\n the future.\n+ You can't bill your customers before they\n [upgrade](fallback::https://support.wix.com/en/article/upgrading-an-app-from-the-wix-app-market)\n to a paid version of your app.\n+ You're able to include up to 5 custom charges per invoice.\n+ You must set an initial charge limit and can't bill customers more than this\n limit per billing cycle. You can't change the limit later, but customers are\n able to increase it themselves.\n+ You receive notifications in case Wix doesn't accept the charges you return\n via the service plugin. Currently, there is no notification if the customer agrees to\n your proposed charge limit or pays an invoice.\n+ Currently, Wix supports the following currencies: `AUD`, `BRL`, `CAD`, `EUR`,\n `GBP`, `ILS`, `INR`, `JPY`, `MXN`, `PLN`, `RUB`, `TRY`, `USD`. Wix may add\n more currencies in the future.\n+ We recommend to use the `instanceId` instead of the `subscriptionId` to track\n usage and billing for apps, because this field is also used in the\n [App Management API](fallback::https://dev.wix.com/docs/rest/api-reference/app-management/about-app-management).\n+ If we discover that your app has charged customers for usage outside of an\n invoice's specified period, we may take action such as blocking your app from\n charging the customer, removing your app from the Wix App Market, revoking\n your access to the Wix developer program, or pursuing legal action to recover\n damages caused by overcharging. We understand that mistakes can happen and\n encourage you to contact\n [the Wix App Market team](fallback::https://devforum.wix.com/kb/en/contact) immediately if you\n become aware of any overcharging issues so that we can work together to\n resolve the situation.\n\n## Use cases\n\n+ [Support app upgrades](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::6af34c5d-ea5a-47dd-a73f-bb201b356a3dslug::sample-flows#support-app-upgrades*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/sample-flows#support-app-upgrades)\n+ [Bill a customer](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::6af34c5d-ea5a-47dd-a73f-bb201b356a3dslug::sample-flows#bill-a-customer*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/sample-flows#bill-a-customer)\n+ [Get Notified when an app instance is canceled](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::6af34c5d-ea5a-47dd-a73f-bb201b356a3dslug::sample-flows#get-notified-when-an-app-instance-is-canceled*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/sample-flows#get-notified-when-an-app-instance-is-canceled)\n\n## Terminology\n\n+ __App instance__: Particular installation of an app that let's you identify\n your customer. Learn more about how to retrieve the instance ID from a\n [service plugin request envelope](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::e4363000-00cd-46c7-87bc-6709e250f783#getting-started_service-provider-interface_request-envelope*fallback::https://dev.wix.com/api/rest/getting-started/service-provider-interface#getting-started_service-provider-interface_request-envelope).\n+ __Customer__: Site owner who installs your app on their Wix site.\n+ __Invoice__: Document that Wix sends to customers specifying the price they\n have to pay for using the Wix platform. Includes charges for 3rd-party apps\n associated with the site.\n+ __Charge__: Price for using your app that you can add to an invoice. You can\n add up to 5 charges per invoice.\n+ __Charge limit__: Maximum amount that you're allowed to charge customers for\n using your app per billing cycle. It helps ensure that customers are aware of\n their potential costs upfront.\n+ __Subscription ID__: Unique identifier for the agreement that specifies the\n product or service to which the customer has access to and how they are billed.\n Currently, Wix doesn't provide an API to retrieve information about\n subscriptions. In case the product is an app, we recommend to use the app\n instance ID instead of the subscription ID to track usage and billing, because\n this field is also used in the\n [App Management API](fallback::https://dev.wix.com/docs/rest/api-reference/app-management/about-app-management).\n"},{"displayName":"Sample Flows","slugifyName":"sample-flows","content":"# Custom Charges Service Plugin: Sample Use Cases & Flows\n\nThis article shares some possible use cases your app could support, as well as\na sample flow that could support each use case. This can be a helpful jumping\noff point as you plan your app's implementation.\n\n## Support app upgrades\n\nEvery time a customer upgrades an instance of your app, Wix\nretrieves an initial charge limit from your app. Wix displays this limit to the\ncustomer in the checkout page of the upgrade process. This helps customers\nunderstand how much they may have to pay maximally for using your app per\nbilling cycle.\n\nTo support app upgrades:\n\n1. Wix calls [Get Charge Limit](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::6af34c5d-ea5a-47dd-a73f-bb201b356a3dslug::get-charge-limit*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/custom-charges-provider-v1/get-charge-limit).\n2. Return the initial charge limit that your app is allowed to charge the customer per billing cycle.\n3. Wix displays the limit to the customer for approval. Note that your app can't change this limit later, but customers are able to increase it themselves.\n\n## Bill a customer\n\nYour app can add custom charges to an invoice that Wix sends to a customer\nat the end of the billing cycle.\n\nTo bill a customer:\n\n1. Wix calls [List charges](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::6af34c5d-ea5a-47dd-a73f-bb201b356a3dslug::list-charges*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/custom-charges-provider-v1/list-charges). Note that Wix sends `{\"intent\": \"CREATE_INVOICE\"}` to actually create an invoice with the charges you return. For other purposes, Wix sends `{\"intent\": \"DISPLAY_ONLY\"}`.\n2. Return up to 5 charges that Wix adds to the invoice.\n3. In case Wix accepts your charges, Wix calls [Invoice Created Event](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::6af34c5d-ea5a-47dd-a73f-bb201b356a3dslug::invoice-created-event*fallback::https://dev.wix.com/docs/rest/api-reference/app-management/apps/custom-charges-spi/custom-charges-provider-v1/invoice-created-event) and sends the invoice to the customer.\n\n## Get notified when an app instance is canceled\n\nCurrently, you can't receive notifications when a payment for an\ninvoice has failed. If that happens, Wix sends an email to the customer and\nretries to collect the payment several times. In case all retries fail, Wix\ncancels the app instance. Your app could get notified in this situation, and\nyou could reach out to the customer.\n\nTo receive notifications when an app instance is canceled:\n\n1. Sign up for the [Paid Plan Auto Renewal Cancelled Webhook](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::5a829a3f-423e-484e-80c5-b70320bf9383slug::paid-plan-auto-renewal-cancelled*fallback::https://dev.wix.com/api/rest/app-management/apps/app-instance/paid-plan-auto-renewal-cancelled-webhook) of the App Instance API.\n2. Listen to the webhook. Wix sends `{\"cancelReason\": \"FAILED_PAYMENT\"}` in case an app instance is canceled due to a failed payment.\n3. Reach out to the relevant customer.\n"}]},"reviewStatus":"APPROVED","isLocked":true,"metadata":{"packageVersion":""}}