{ "openapi": "3.0.0", "info": { "title": "Subscriptions API (v3)", "description": "[Subscriptions](https:\/\/help.vtex.com\/en\/tutorial\/how-subscriptions-work--frequentlyAskedQuestions_4453) is the VTEX solution for customers to make recurrent purchases at your store on a regular schedule. When customers subscribe, they define what products they want to acquire regularly and at what frequency they want these automatic orders to be created. For more information, see [Subscriptions onboarding guide](https:\/\/developers.vtex.com\/docs\/guides\/subscriptions).\r\n\r\n## Common parameters\r\n\r\n| **Parameter name** | **Description** | **Type** |\r\n| --- | --- | :--- |\r\n| `{{accountName}}` | Name of the VTEX account. Used as part of the URL. | Server variable. |\r\n| `{{environment}}` | Environment to use. Used as part of the URL. The default value is `vtexcommercestable`. | Server variable. |\r\n| `X-VTEX-API-AppKey` | Unique identifier of the [API key](https:\/\/developers.vtex.com\/docs\/guides\/api-authentication-using-api-keys). | Authentication header. Must be used together with `X-VTEX-API-AppToken`. Not necessary when using `VtexIdclientAutCookie`. |\r\n| `X-VTEX-API-AppToken` | Secret token of the [API key](https:\/\/developers.vtex.com\/docs\/guides\/api-authentication-using-api-keys). | Authentication header. Must be used together with X-VTEX-API-AppKey. Not necessary when using `VtexIdclientAutCookie`. |\r\n| `VtexIdclientAutCookie` | [User token](https:\/\/developers.vtex.com\/docs\/guides\/api-authentication-using-user-tokens), valid for 24 hours. | Authentication header. Not necessary when using `X-VTEX-API-AppKey` and `X-VTEX-API-AppToken`. |", "contact": {}, "version": "1.0" }, "servers": [ { "url": "https://{accountName}.{environment}.com.br", "description": "VTEX server URL.", "variables": { "accountName": { "description": "Name of the VTEX account. Used as part of the URL.", "default": "apiexamples" }, "environment": { "description": "Environment to use. Used as part of the URL.", "enum": [ "vtexcommercestable" ], "default": "vtexcommercestable" } } } ], "paths": { "/api/rns/pub/cycles/{cycleId}": { "get": { "tags": [ "Cycles" ], "summary": "Get cycle details", "description": "Retrieves a specific cycle by its ID.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Subscriptions | ApplicationAccess | **Subscription view only** |\r\n| Subscriptions | ApplicationAccess | **Subscription view and edit** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations. ", "parameters": [ { "name": "cycleId", "in": "path", "description": "ID from the desired cycle.", "required": true, "schema": { "type": "string", "example": "2b9de8a5-b29b-4e18-8400-400dc0a2330d" } }, { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCycleResponse" }, "example": { "id": "2b9de8a5-b29b-4e18-8400-400dc0a2330d-20240730", "subscriptionId": "2b9de8a5-b29b-4e18-8400-400dc0a2330d", "workflowId": "73a385ff-b3dc-48c0-ab25-0f1cecc4be8a", "status": "SUCCESS", "customerEmail": "customer@email.com", "customerId": "94b0a774-09c7-43ee-91e2-e8fa6guad0ju", "date": "2024-07-30T09:04:59.7325176Z", "lastUpdate": "2024-07-31T09:06:05.6879323Z", "cycleCount": 3, "isInRetry": false, "message": null, "friendlyMessage": null, "plan": { "id": "store.subscription.tshirt-collection", "frequency": { "periodicity": "WEEKLY", "interval": 3 }, "validity": { "begin": "2024-04-11T11:04:24.0454821Z", "end": null }, "purchaseDay": "Sunday" }, "orderInfo": { "orderId": "V-8753228-01", "orderGroup": "V-8753228", "paymentUrl": null, "value": 21600 }, "context": { "items": [ { "subscriptionItem": "69C872657263439D899265717E733A84", "skuId": "1154", "quantity": 1, "status": "ACTIVE", "isSkipped": false, "cycleCount": 1 } ], "paymentSystem": "47", "paymentSystemName": "Cash", "paymentSystemGroup": "cash", "paymentAccountId": null, "addressId": "Address", "addressType": "residential", "catalogAttachment": "vtex.subscription.tshirt-collection" }, "simulationItems": [ { "id": "1145", "quantity": 1, "unitPrice": 21600, "status": "OK", "price": null, "sellingPrice": 21600, "manualPrice": null } ] } } } } } } }, "/api/rns/pub/cycles": { "get": { "tags": [ "Cycles" ], "summary": "List cycles", "description": "Lists subscription cycles, based on filters defined in the query parameters.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Subscriptions | ApplicationAccess | **Subscription view only** |\r\n| Subscriptions | ApplicationAccess | **Subscription view and edit** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "beginDate", "in": "query", "description": "Lower limit for the date of creation of the cycle", "schema": { "type": "string", "nullable": true } }, { "name": "endDate", "description": "Upper limit for the date of creation of the cycle", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "subscriptionId", "description": "Id from the subscription that generated the cycle", "in": "query", "schema": { "type": "string", "nullable": true } }, { "name": "customerEmail", "in": "query", "description": "Customer that owns the subscription. Defaults to the current logged user", "schema": { "type": "string", "nullable": true } }, { "name": "status", "in": "query", "description": "Current cycle status", "schema": { "type": "string", "nullable": true } }, { "name": "page", "in": "query", "description": "Page used for pagination", "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "size", "in": "query", "description": "Page size used for pagination", "schema": { "type": "integer", "format": "int32", "default": 15 } }, { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "description": "List of subscriptions of the VTEX account, limited to 15 results.", "items": { "$ref": "#/components/schemas/SubscriptionCycleResponse" } }, "example": [ { "id": "2b9de8a5-b29b-4e18-8400-400dc0a2330d-20240730", "subscriptionId": "2b9de8a5-b29b-4e18-8400-400dc0a2330d", "workflowId": "73a385ff-b3dc-48c0-ab25-0f1cecc4be8a", "status": "SUCCESS", "customerEmail": "customer@email.com", "customerId": "94b0a774-09c7-43ee-91e2-e8fa6guad0ju", "date": "2024-07-30T09:04:59.7325176Z", "lastUpdate": "2024-07-31T09:06:05.6879323Z", "cycleCount": 3, "isInRetry": false, "message": null, "friendlyMessage": null, "plan": { "id": "store.subscription.tshirt-collection", "frequency": { "periodicity": "WEEKLY", "interval": 3 }, "validity": { "begin": "2024-04-11T11:04:24.0454821Z", "end": null }, "purchaseDay": "Sunday" }, "orderInfo": { "orderId": "V-8753228-01", "orderGroup": "V-8753228", "paymentUrl": null, "value": 21600 }, "context": { "items": [ { "subscriptionItem": "69C872657263439D899265717E733A84", "skuId": "1154", "quantity": 1, "status": "ACTIVE", "isSkipped": false, "cycleCount": 1 } ], "paymentSystem": "47", "paymentSystemName": "Cash", "paymentSystemGroup": "cash", "paymentAccountId": null, "addressId": "Address", "addressType": "residential", "catalogAttachment": "vtex.subscription.tshirt-collection" }, "simulationItems": [ { "id": "1145", "quantity": 1, "unitPrice": 21600, "status": "OK", "price": null, "sellingPrice": 21600, "manualPrice": null } ] } ] } } } } } }, "/api/rns/pub/cycles/{cycleId}/retry": { "post": { "tags": [ "Cycles" ], "summary": "Retry cycle", "description": "Every subscription order has an execution count called cycle, which determines the position of an order counting from when the shopper subscribed. This endpoint reruns a cycle that is currently in error state.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Subscriptions | ApplicationAccess | **Subscription view only** |\r\n| Subscriptions | ApplicationAccess | **Subscription view and edit** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "cycleId", "in": "path", "description": "ID from the subscription cycle that will be retried.", "required": true, "schema": { "type": "string", "nullable": true } }, { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/rns/pvt/plans": { "get": { "tags": [ "Plans" ], "summary": "List plans", "description": "Lists subscription plans, based on filters defined in the query parameters.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Subscriptions | ApplicationAccess | **Subscription admin** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "periodicity", "in": "query", "description": "Filter [subscription plans](https://help.vtex.com/en/tutorial/subscription-plans-beta--5kczKRqHEsrs1tYtRcY8wR) by available periodicity.", "schema": { "type": "string", "nullable": true } }, { "name": "interval", "in": "query", "description": "Filter [subscription plans](https://help.vtex.com/en/tutorial/subscription-plans-beta--5kczKRqHEsrs1tYtRcY8wR) by available interval.", "schema": { "type": "string", "nullable": true } }, { "name": "page", "in": "query", "description": "Page used for pagination.", "schema": { "type": "integer", "example": 1 } }, { "name": "size", "in": "query", "description": "Desired number of [subscription plans](https://help.vtex.com/en/tutorial/subscription-plans-beta--5kczKRqHEsrs1tYtRcY8wR) in the response.", "schema": { "type": "integer", "example": 15 } }, { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StorePlan" } }, "example": [ { "id": "catfood.subscription", "frequencies": [ { "periodicity": "DAILY", "interval": 1 } ], "isActive": true, "importInProgress": false, "attachmentId": 40, "isValid": true, "validationMessages": [], "validity": null, "purchaseDays": [ "7" ] }, { "id": "subscription.tshirt", "frequencies": [ { "periodicity": "MONTHLY", "interval": 1 } ], "isActive": true, "importInProgress": false, "attachmentId": 39, "isValid": true, "validationMessages": [], "validity": null, "purchaseDays": [ "3" ] } ] } } } } } }, "/api/rns/pvt/plans/{id}": { "get": { "tags": [ "Plans" ], "summary": "Get plan details", "description": "Retrieves a specific subscription plan by its ID.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Subscriptions | ApplicationAccess | **Subscription admin** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "id", "in": "path", "description": "ID from the [subscription plan](https://help.vtex.com/en/tutorial/subscription-plans-beta--5kczKRqHEsrs1tYtRcY8wR).", "required": true, "schema": { "type": "string", "example": "catfood.subscription" } }, { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePlan" }, "example": { "id": "catfood.subscription", "frequencies": [ { "periodicity": "DAILY", "interval": 1 } ], "isActive": true, "importInProgress": false, "attachmentId": 40, "isValid": true, "validationMessages": [], "validity": null, "purchaseDays": [ "1", "2", "3", "4", "5", "6", "0" ] } } } } } } }, "/api/rns/pvt/reports": { "get": { "tags": [ "Reports" ], "summary": "List report templates", "description": "Lists all subscription report templates available.\r\n\r\n>ℹ️ After choosing the desired template, use the [Generate report](https://developers.vtex.com/docs/api-reference/subscriptions-api-v3#post-/api/rns/pvt/reports/-reportName-/documents) endpoint to create the report for your store.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Subscriptions | ApplicationAccess | **Subscription view only** |\r\n| Subscriptions | ApplicationAccess | **Subscription admin** |\r\n| Subscriptions | ApplicationAccess | **Subscription view and edit** |\r\n| Subscriptions | ApplicationAccess | **Subscription metrics and reports** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "Report template details.", "properties": { "account": { "type": "string", "description": "VTEX store account name." }, "name": { "type": "string", "description": "Template type, more information in the `description` field.", "enum": [ "subscriptionsWithStatus", "subscriptionsScheduledBetweenDate", "subscriptionsUpdatedBetweenDate", "subscriptionsCreatedBetweenDate", "executionsBetweenDate" ] }, "description": { "type": "string", "description": "Template description, which varies according to the template type:\r\n- `subscriptionsWithStatus`: Get subscriptions based on status.\r\n- `subscriptionsScheduledBetweenDate`: Get active subscriptions scheduled between dates.\r\n- `subscriptionsUpdatedBetweenDate`: Get subscriptions updated between dates.\r\n- `subscriptionsCreatedBetweenDates`: Get subscriptions created between date.\r\n- `executionsBetweenDate`: Get executions between dates." }, "reason": { "type": "string", "description": "Reason why the template was created.", "nullable": true }, "behalfOf": { "type": "string", "description": "On behalf of which user the template was created.", "nullable": true }, "params": { "type": "array", "description": "Information about the template params.", "items": { "type": "object", "description": "Param details.", "properties": { "type": { "type": "string", "description": "Template param type, which can be `string` for the `subscriptionsWithStatus` template type, or `date` for the other cases.", "enum": [ "string", "date" ] }, "format": { "type": "string", "description": "Template param format, such as `yyyy-MM-dd` for `beginDate` or `endDate`. Not applicable to the `subscriptionsWithStatus` type." }, "name": { "type": "string", "description": "Template param name, which can relate to the template status (`status`) or dates (`beginDate`, `endDate`).", "enum": [ "status", "beginDate", "endDate" ] } } } } } } }, "example": [ { "account": "fashionstore", "name": "subscriptionsWithStatus", "description": "Get subscriptions based on status", "reason": null, "behalfOf": null, "params": [ { "type": "string", "name": "status" } ] }, { "account": "fashionstore", "name": "subscriptionsScheduledBetweenDate", "description": "Get active subscriptions scheduled between date", "reason": null, "behalfOf": null, "params": [ { "type": "date", "format": "yyyy-MM-dd", "name": "beginDate" }, { "type": "date", "format": "yyyy-MM-dd", "name": "endDate" } ] }, { "account": "fashionstore", "name": "subscriptionsUpdatedBetweenDate", "description": "Get subscriptions updated between date", "reason": null, "behalfOf": null, "params": [ { "type": "date", "format": "yyyy-MM-dd", "name": "beginDate" }, { "type": "date", "format": "yyyy-MM-dd", "name": "endDate" } ] }, { "account": "fashionstore", "name": "subscriptionsCreatedBetweenDate", "description": "Get subscriptions created between date", "reason": null, "behalfOf": null, "params": [ { "type": "date", "format": "yyyy-MM-dd", "name": "beginDate" }, { "type": "date", "format": "yyyy-MM-dd", "name": "endDate" } ] }, { "account": "fashionstore", "name": "executionsBetweenDate", "description": "Get executions between date", "reason": null, "behalfOf": null, "params": [ { "type": "date", "format": "yyyy-MM-dd", "name": "beginDate" }, { "type": "date", "format": "yyyy-MM-dd", "name": "endDate" } ] } ] } } } } } }, "/api/rns/pvt/reports/{reportName}/documents/{documentId}": { "get": { "tags": [ "Reports" ], "summary": "Get report document details", "description": "Retrieves information about a subscription report document, searching by document ID. In the status code `200 OK` response, you get a link to download the report.\r\n\r\n>❗ Before using this endpoint, you must create a report with the [Generate report](https://developers.vtex.com/docs/api-reference/subscriptions-api-v3#post-/api/rns/pvt/reports/-reportName-/documents) endpoint and get the document ID.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Subscriptions | ApplicationAccess | **Subscription metrics and reports** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "reportName", "in": "path", "required": true, "description": "Name of the report type, which must be previously created for your store using the [Generate report](https://developers.vtex.com/docs/api-reference/subscriptions-api-v3#post-/api/rns/pvt/reports/-reportName-/documents) endpoint. The possible values are:\r\n- `subscriptionsWithStatus`\r\n- `subscriptionsScheduledBetweenDate`\r\n- `subscriptionsUpdatedBetweenDate`\r\n- `subscriptionsCreatedBetweenDate`\r\n- `executionsBetweenDate`", "schema": { "type": "string", "example": "subscriptionsWithStatus" } }, { "name": "documentId", "in": "path", "required": true, "description": "Report document ID. You get this value after you create a report template for your store using the [Generate report](https://developers.vtex.com/docs/api-reference/subscriptions-api-v3#post-/api/rns/pvt/reports/-reportName-/documents) endpoint.", "schema": { "type": "string", "example": "2804f3ab-5a51-11ef-b37f-f89ffae09a60" } }, { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportResponse" }, "example": { "id": "7849df9f-00d4-11ef-8452-1254acca1d85", "finished": true, "recordsProcessed": 63, "recordsSum": 63, "startDate": "2024-03-22T18:16:50.7487312Z", "lastUpdateTime": "2024-04-22T18:16:50.7487312Z", "completedDate": "2024-04-22T18:16:50.7487312Z", "errorCount": null, "percentageProcessed": 100, "enqueueDate": "2024-04-22T18:16:50.7487312Z", "email": "receiver@email.com", "canceled": false, "outputType": "CSV", "zipped": false, "linkToDownload": "https://s3.amazonaws.com/OMSReport/v3/_finished/accountname/7849df9f-00d4-11ef-8452-1254acca1d85//files/47363271-b655-11ed-83ab-12dbed7de2a7.csv?AWSAccessKeyId=ASIAQYXXCHIYPSJDRNHB&Expires=1724945014&x-amz-security-token=IQoJb3JpZ2luX2VjEMj%2Feq6V1w8z3NGlnfhvSp70Q80qvQUIwP%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARAAGgwwNTMxMzE0OTE4ODgiDCM0JATV%2FwXQvXyovCqRBW%2F14aC5J3plQR%2BzKbpddyDnoAstfgJo1MfR0yel3uRzixrSRFE033V4%2B8cN7ez5Lr0ymGifnB14ONZ35RtM4PgQvuV0fs8If6cw8%3D%3D&Signature=7yZbA%2BGaYdPUkdxFXqy9W8GGHuo%3D", "lastErrorMessage": null, "statusMessage": "Report 7849df9f-00d4-11ef-8452-1254acca1d85 was completed at 15:23 and sent to receiver@email.com." } } } } } } }, "/api/rns/pvt/reports/{reportName}/documents": { "post": { "tags": [ "Reports" ], "summary": "Generate report", "description": "Creates a subscriptions report in the format of a `csv` file and sends it via email to a given user.\r\n\r\n>ℹ️ In the response body of the current endpoint, you get the document ID required for the [Get report document details](https://developers.vtex.com/docs/api-reference/subscriptions-api-v3#get-/api/rns/pvt/reports/-reportName-/documents/-documentId-) endpoint.\r\n\r\nYou can generate the following types of report:\r\n\r\n- `subscriptionsWithStatus`: Get subscriptions based on subscription cycle execution status.\r\n - **Required query param:** `status`.\r\n\r\n- `subscriptionsScheduledBetweenDate`: Get active subscriptions scheduled between dates.\r\n - **Required query params:** `beginDate` and `endDate`.\r\n\r\n- `subscriptionsUpdatedBetweenDate`: Get subscriptions updated between dates.\r\n - **Required query params:** `beginDate` and `endDate`.\r\n\r\n- `subscriptionsCreatedBetweenDate`: Get subscriptions created between dates.\r\n - **Required query params:** `beginDate` and `endDate`.\r\n\r\n- `executionsBetweenDate`: Get executions between dates.\r\n - **Required query params:** `beginDate` and `endDate`.\r\n\r\n>ℹ️ You can also use the [List report templates](https://developers.vtex.com/docs/api-reference/subscriptions-api-v3#get-/api/rns/pvt/reports) endpoint to discover the types of reports you can generate.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Subscriptions | ApplicationAccess | **Subscription metrics and reports** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "reportName", "in": "path", "required": true, "description": "Name of the type of report you wish to generate. The following values are accepted:\r\n- `subscriptionsWithStatus`\r\n- `subscriptionsScheduledBetweenDate`\r\n- `subscriptionsUpdatedBetweenDate`\r\n- `subscriptionsCreatedBetweenDate`\r\n- `executionsBetweenDate`", "schema": { "type": "string", "example": "subscriptionsWithStatus" } }, { "name": "email", "in": "query", "required": false, "description": "The report will be sent to the email in this field. When no email is provided, the report is sent to the email of the user making the request.", "schema": { "type": "string", "example": "receiver@email.com" } }, { "name": "status", "in": "query", "required": false, "description": "Subscription cycle execution status. This field is required only for the `subscriptionsWithStatus` report type, and the possible values are:\r\n- `TRIGGERED`: Execution has been triggered.\r\n- `IN_PROCESS`: Execution is being processed by the system.\r\n- `FAILURE`: An internal error occurred during the subscription execution.\r\n- `SUCCESS`: Successful cycle processing.\r\n- `EXPIRED`: The subscription was not renewed, and the period for which it was valid has ended.\r\n- `ORDER_ERROR`: Cycle was not executed due to an error in order placement.\r\n- `PAYMENT_ERROR`: Cycle was not executed due to an error in the payment.\r\n- `SKIPED`: A subscription cycle execution was skipped, and the subscription will be executed in the next cycle.\r\n- `SUCCESS_WITH_NO_ORDER`: Cycle was executed successfully, and the linked order has no items.\r\n- `SUCCESS_WITH_PARTIAL_ORDER`: Cycle was executed successfully, and has a linked partial order.\r\n- `RE_TRIGGERED`: Execution retry was triggered manually.\r\n- `SCHEDULE_UPDATED`: The next subscription cycle execution date has been updated.", "schema": { "type": "string", "example": "SUCCESS" } }, { "name": "beginDate", "in": "query", "required": false, "description": "Beginning date in the format `YYYY-MM-DD`. This field is required for all report types, except for the `subscriptionsWithStatus` type.", "schema": { "type": "string", "example": "2024-07-01" } }, { "name": "endDate", "in": "query", "required": false, "description": "Ending date in the format `YYYY-MM-DD`. This field is required for all report types, except for the `subscriptionsWithStatus` type.", "schema": { "type": "string", "example": "2024-08-01" } }, { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportResponse" }, "example": { "id": "7849df9f-00d4-11ef-8452-1254acca1d85", "finished": false, "recordsProcessed": 0, "recordsSum": null, "startDate": null, "lastUpdateTime": null, "completedDate": null, "errorCount": null, "percentageProcessed": 0, "enqueueDate": "2024-04-22T18:16:50.7487312Z", "email": "receiver@email.com", "canceled": false, "outputType": "CSV", "zipped": false, "linkToDownload": null, "lastErrorMessage": null, "statusMessage": "Report 7849df9f-00d4-11ef-8452-1254acca1d85 is being processed (0.00% completed). The file will be sent to receiver@email.com." } } } } } } }, "/api/rns/pub/subscriptions/{id}": { "get": { "tags": [ "Subscriptions" ], "summary": "Get subscription details by ID", "description": "Retrieves information about a subscription, searching by subscription ID.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Subscriptions | ApplicationAccess | **Subscription view only** |\r\n| Subscriptions | ApplicationAccess | **Subscription view and edit** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "[Subscription](https://help.vtex.com/en/tutorial/how-subscriptions-work--frequentlyAskedQuestions_4453) ID.", "schema": { "type": "string", "example": "F35A8B497EA9E5A6D8F3778CBBA4C9E3" } }, { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionGroupResponse" }, "example": { "id": "F35A8B497EA9E5A6D8F3778CBBA4C9E3", "customerId": "5aff33ec-5302-4580-a4ed-be9aa32ba3db", "customerEmail": "customer@email.com", "title": null, "status": "ACTIVE", "isSkipped": false, "nextPurchaseDate": "2024-08-21T12:00:00Z", "lastPurchaseDate": "2024-08-19T00:00:00Z", "plan": { "id": "store.subscription.ana-plan", "frequency": { "periodicity": "DAILY", "interval": 2 }, "validity": { "begin": "2024-08-01T00:00:00Z", "end": null }, "purchaseDay": "Not_Applicable" }, "shippingAddress": { "addressId": "5028945524109", "addressType": "residential" }, "purchaseSettings": { "paymentMethod": { "paymentAccountId": "B2BBDD0F2E4B47FC9E48D2DA99C318EF", "paymentSystem": "2", "installments": 1, "paymentSystemName": "creditCard", "paymentSystemGroup": "creditCard" }, "currencyCode": "BRL", "selectedSla": "Normal", "salesChannel": "1", "seller": "1" }, "cycleCount": 9, "createdAt": "2024-08-01T12:31:55.7308301Z", "lastUpdate": "2024-08-19T12:16:51.0237801Z", "items": [ { "id": "0213AB4188FE4007A865AD33D972FA37", "skuId": "9", "quantity": 1, "isSkipped": false, "status": "ACTIVE", "originalOrderId": "1451256157912-01", "cycleCount": 9, "priceAtSubscriptionDate": 736.0, "manualPrice": 736.0, "attachments": [ { "name": "printMessage", "content": { "printMessage": "Hello" } } ] } ], "lastCycleId": "F35A8B497EA9E5A6D8F3778CBBA4C9E3-20240819", "customData": null } } } } } }, "patch": { "tags": [ "Subscriptions" ], "summary": "Update subscription by ID", "description": "Updates a subscription, searching by subscription ID.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Subscriptions | ApplicationAccess | **Subscription view and edit** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "[Subscription](https://help.vtex.com/en/tutorial/how-subscriptions-work--frequentlyAskedQuestions_4453) ID.", "schema": { "type": "string", "example": "1E7886FC8E45FF38C527897D749584F4" } }, { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "customerEmail" ], "properties": { "customerEmail": { "type": "string", "description": "Customer email.", "example": "customer@email.com" }, "title": { "type": "string", "description": "Subscription title.", "example": "catFood", "nullable": true }, "status": { "type": "string", "nullable": true, "description": "Status to which you wish to update the subscription.", "enum": [ "ACTIVE", "PAUSED", "CANCELED", "EXPIRED", "MISSING" ], "example": "ACTIVE" }, "nextPurchaseDate": { "type": "string", "description": "Date and time you wish to update the next purchase. The format is [ISO 8601 time zone offset](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`.", "example": "2024-09-21T00:00:00Z" }, "isSkipped": { "type": "boolean", "description": "Defines if the customer asked to skip the next subscription order (`true`), or not (`false`).", "example": false }, "plan": { "$ref": "#/components/schemas/PlanRequest" }, "shippingAddress": { "$ref": "#/components/schemas/ShippingAddressRequest" }, "purchaseSettings": { "$ref": "#/components/schemas/PurchaseSettingsRequest" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionGroupResponse" }, "example": { "id": "8B91E3077495AB982117AD0BA4A5829D", "customerId": "c00a9529-806b-4ef3-a5f7-ed7846a66d3d", "customerEmail": "customer@email.com", "title": null, "status": "PAUSED", "isSkipped": false, "nextPurchaseDate": "2024-09-21T15:53:27.0665798Z", "lastPurchaseDate": "2024-08-21T15:53:27.0665798Z", "plan": { "id": "store.subscription.basic", "frequency": { "periodicity": "DAILY", "interval": 1 }, "validity": { "begin": "2024-09-21T15:53:27.0665798Z", "end": null }, "purchaseDay": "Not_Applicable" }, "shippingAddress": { "addressId": "5028945524109", "addressType": "residential" }, "purchaseSettings": { "paymentMethod": { "paymentAccountId": "B2BBDD0F2E4B47FC9E48D2DA99C318EF", "paymentSystem": "6", "installments": 1, "paymentSystemName": "Bank Slips", "paymentSystemGroup": "bankInvoice" }, "currencyCode": "BRL", "selectedSla": "Normal", "salesChannel": "1", "seller": "1" }, "cycleCount": 0, "createdAt": "2024-08-21T15:53:27.0665798Z", "lastUpdate": "0001-01-01T00:00:00", "items": [ { "id": "0F821B992DD848028E3A82C40DBCD834", "skuId": "9", "quantity": 1, "isSkipped": false, "status": "ACTIVE", "cycleCount": 0, "manualPrice": 736.0, "attachments": null } ], "lastCycleId": null, "customData": {} } } } } } } }, "/api/rns/pub/subscriptions": { "get": { "tags": [ "Subscriptions" ], "summary": "List subscriptions", "description": "Lists subscriptions from your store. By default, this request uses the query parameter `page` = `1`, and `size` = `15`. If you wish, you can use different values for query parameters. \r\n\r\n>⚠️ Each response is limited to 15 results. You can get different values by combining pagination query parameters.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Subscriptions | ApplicationAccess | **Subscription view only** |\r\n| Subscriptions | ApplicationAccess | **Subscription view and edit** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "customerEmail", "in": "query", "required": false, "description": "Email of a customer that subscrived to your store.", "schema": { "type": "string", "example": "customer@email.com" } }, { "name": "status", "in": "query", "required": false, "description": "Subscription status. The acceptable values are:\r\n- ACTIVE\r\n- PAUSED\r\n- CANCELED\r\n- EXPIRED\r\n- MISSING", "schema": { "type": "string", "example": "ACTIVE" } }, { "name": "addressId", "in": "query", "required": false, "description": "Subscription shipping address ID.", "schema": { "type": "string", "example": "5028945524109" } }, { "name": "paymentId", "in": "query", "required": false, "description": "[Payment method](https://help.vtex.com/en/tutorial/difference-between-payment-methods-and-payment-conditions--3azJenhGFyUy2gsocms42Q) ID. It corresponds to the `paymentAccountId` field.", "schema": { "type": "string", "example": "807E03E56A844BE2B1727B752E19C828" } }, { "name": "planId", "in": "query", "required": false, "description": "[Subscription plan](https://help.vtex.com/en/tutorial/subscription-plans-beta--5kczKRqHEsrs1tYtRcY8wR) ID.", "schema": { "type": "string", "example": "store.subscription.basic" } }, { "name": "nextPurchaseDate", "in": "query", "required": false, "description": "Subscription next purchase date in the format `YYYY-MM-DD`.", "schema": { "type": "string", "example": "2024-10-30" } }, { "name": "originalOrderId", "in": "query", "required": false, "description": "Order ID of when the customer subscribed.", "schema": { "type": "string", "example": "1421091661214-01" } }, { "name": "page", "in": "query", "required": false, "description": "Number of the starting page of the response. When no value is sent, it starts in page `1`.", "schema": { "type": "integer", "example": 3 } }, { "name": "size", "in": "query", "required": false, "description": "Determines the number of subscriptions in the response. The maximum is equal to the default value, which is `15`.", "schema": { "type": "integer", "example": 10 } }, { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionGroupResponse" } }, "example": [ { "id": "F35A8B497EA9E5A6D8F3778CBBA4C9E3", "customerId": "5aff33ec-5302-4580-a4ed-be9aa32ba3db", "customerEmail": "customer@email.com", "title": null, "status": "ACTIVE", "isSkipped": false, "nextPurchaseDate": "2024-08-21T12:00:00Z", "lastPurchaseDate": "2024-08-19T00:00:00Z", "plan": { "id": "store.subscription.ana-plan", "frequency": { "periodicity": "DAILY", "interval": 2 }, "validity": { "begin": "2024-08-01T00:00:00Z", "end": null }, "purchaseDay": "Not_Applicable" }, "shippingAddress": { "addressId": "5028945524109", "addressType": "residential" }, "purchaseSettings": { "paymentMethod": { "paymentAccountId": "B2BBDD0F2E4B47FC9E48D2DA99C318EF", "paymentSystem": "2", "installments": 1, "paymentSystemName": "creditCard", "paymentSystemGroup": "creditCard" }, "currencyCode": "BRL", "selectedSla": "Normal", "salesChannel": "1", "seller": "1" }, "cycleCount": 9, "createdAt": "2024-08-01T12:31:55.7308301Z", "lastUpdate": "2024-08-19T12:16:51.0237801Z", "items": [ { "id": "0213AB4188FE4007A865AD33D972FA37", "skuId": "9", "quantity": 1, "isSkipped": false, "status": "ACTIVE", "originalOrderId": "1451256157912-01", "cycleCount": 9, "priceAtSubscriptionDate": 736.0, "manualPrice": 736.0, "attachments": [ { "name": "printMessage", "content": { "printMessage": "Hello" } } ] } ], "lastCycleId": "F35A8B497EA9E5A6D8F3778CBBA4C9E3-20240819", "customData": null } ] } } } } }, "post": { "tags": [ "Subscriptions" ], "summary": "Create subscription", "description": "Creates a new subscription.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Subscriptions | ApplicationAccess | **Subscription view and edit** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionGroupRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionGroupResponse" }, "example": { "id": "8B91E3077495AB982117AD0BA4A5829D", "customerId": "c00a9529-806b-4ef3-a5f7-ed7846a66d3d", "customerEmail": "customer@email.com", "title": null, "status": "PAUSED", "isSkipped": false, "nextPurchaseDate": "2024-09-21T15:53:27.0665798Z", "lastPurchaseDate": "2024-08-21T15:53:27.0665798Z", "plan": { "id": "store.subscription.basic", "frequency": { "periodicity": "DAILY", "interval": 1 }, "validity": { "begin": "2024-09-21T15:53:27.0665798Z", "end": null }, "purchaseDay": "Not_Applicable" }, "shippingAddress": { "addressId": "5028945524109", "addressType": "residential" }, "purchaseSettings": { "paymentMethod": { "paymentAccountId": "B2BBDD0F2E4B47FC9E48D2DA99C318EF", "paymentSystem": "6", "installments": 1, "paymentSystemName": "Bank Slips", "paymentSystemGroup": "bankInvoice" }, "currencyCode": "BRL", "selectedSla": "Normal", "salesChannel": "1", "seller": "1" }, "cycleCount": 0, "createdAt": "2024-08-21T15:53:27.0665798Z", "lastUpdate": "0001-01-01T00:00:00", "items": [ { "id": "0F821B992DD848028E3A82C40DBCD834", "skuId": "9", "quantity": 1, "isSkipped": false, "status": "ACTIVE", "cycleCount": 0, "manualPrice": 736.0, "attachments": null } ], "lastCycleId": null, "customData": {} } } } } } } }, "/api/rns/pub/subscriptions/{id}/items/{itemId}": { "delete": { "tags": [ "Subscriptions" ], "summary": "Remove item from subscription", "description": "Removes an item from a given subscription.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Subscriptions | ApplicationAccess | **Subscription view and edit** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "id", "in": "path", "description": "[Subscription](https://help.vtex.com/en/tutorial/how-subscriptions-work--frequentlyAskedQuestions_4453) ID.", "required": true, "schema": { "type": "string", "example": "8700734451ED4FD4955697873BEC51C3" } }, { "name": "itemId", "in": "path", "description": "Subscription item ID of the SKU being removed from the subscription.", "required": true, "schema": { "type": "string", "example": "0A6C01CA4582458A9CF8F61A9F6E1A68" } }, { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "responses": { "204": { "description": "No Content" } } }, "patch": { "tags": [ "Subscriptions" ], "summary": "Edit item from subscription", "description": "Edits an item from a given subscription.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Subscriptions | ApplicationAccess | **Subscription view only** |\r\n| Subscriptions | ApplicationAccess | **Subscription view and edit** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "[Subscription](https://help.vtex.com/en/tutorial/how-subscriptions-work--frequentlyAskedQuestions_4453) ID.", "schema": { "type": "string", "example": "8700734451ED4FD4955697873BEC51C3" } }, { "name": "itemId", "in": "path", "required": true, "description": "ID of the subscription item being edited.", "schema": { "type": "string", "example": "0A6C01CA4582458A9CF8F61A9F6E1A68" } }, { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Subscription status.", "enum": [ "ACTIVE", "PAUSED", "CANCELED", "EXPIRED", "MISSING" ], "example": "ACTIVE", "nullable": true }, "isSkipped": { "type": "boolean", "description": "Defines if the customer asked to skip the next subscription order (`true`), or not (`false`).", "example": false, "nullable": true }, "quantity": { "type": "integer", "description": "Quantity of units being purchased via subscription.", "example": 5 }, "manualPrice": { "type": "number", "description": "You can edit or configure a [manual price](https://help.vtex.com/en/tutorial/change-the-price-of-an-item-in-the-shopping-cart--7Cd37aCAmtL1qmoZJJvjNf) for the item, if you wish.", "example": 400.3 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionGroupResponse" }, "example": { "id": "F35A8B497EA9E5A6D8F3778CBBA4C9E3", "customerId": "5aff33ec-5302-4580-a4ed-be9aa32ba3db", "customerEmail": "customer@email.com", "title": null, "status": "ACTIVE", "isSkipped": false, "nextPurchaseDate": "2024-08-21T12:00:00Z", "lastPurchaseDate": "2024-08-19T00:00:00Z", "plan": { "id": "store.subscription.ana-plan", "frequency": { "periodicity": "DAILY", "interval": 2 }, "validity": { "begin": "2024-08-01T00:00:00Z", "end": null }, "purchaseDay": "Not_Applicable" }, "shippingAddress": { "addressId": "5028945524109", "addressType": "residential" }, "purchaseSettings": { "paymentMethod": { "paymentAccountId": "B2BBDD0F2E4B47FC9E48D2DA99C318EF", "paymentSystem": "2", "installments": 1, "paymentSystemName": "creditCard", "paymentSystemGroup": "creditCard" }, "currencyCode": "BRL", "selectedSla": "Normal", "salesChannel": "1", "seller": "1" }, "cycleCount": 9, "createdAt": "2024-08-01T12:31:55.7308301Z", "lastUpdate": "2024-08-19T12:16:51.0237801Z", "items": [ { "id": "0213AB4188FE4007A865AD33D972FA37", "skuId": "9", "quantity": 1, "isSkipped": false, "status": "ACTIVE", "originalOrderId": "1451256157912-01", "cycleCount": 9, "priceAtSubscriptionDate": 736.0, "manualPrice": 736.0, "attachments": [ { "name": "printMessage", "content": { "printMessage": "Hello" } } ] } ], "lastCycleId": "F35A8B497EA9E5A6D8F3778CBBA4C9E3-20240819", "customData": null } } } } } } }, "/api/rns/pub/subscriptions/{id}/items": { "post": { "tags": [ "Subscriptions" ], "summary": "Add item to subscription", "description": "Adds a new item to a given subscription.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Subscriptions | ApplicationAccess | **Subscription view only** |\r\n| Subscriptions | ApplicationAccess | **Subscription view and edit** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "id", "in": "path", "description": "[Subscription](https://help.vtex.com/en/tutorial/how-subscriptions-work--frequentlyAskedQuestions_4453) ID.", "required": true, "schema": { "type": "string", "example": "8700734451ED4FD4955697873BEC51C3" } }, { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "skuId", "quantity" ], "properties": { "skuId": { "type": "string", "description": "ID of the SKU being added to the subscription.", "example": "12" }, "quantity": { "type": "integer", "description": "Quantity of units being purchased in each subscription order.", "example": 5 }, "manualPrice": { "type": "number", "description": "You can configure a [manual price](https://help.vtex.com/en/tutorial/change-the-price-of-an-item-in-the-shopping-cart--7Cd37aCAmtL1qmoZJJvjNf) for the subscription item, if you wish.", "example": 400.3, "nullable": true } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionGroupResponse" }, "example": { "id": "F35A8B497EA9E5A6D8F3778CBBA4C9E3", "customerId": "5aff33ec-5302-4580-a4ed-be9aa32ba3db", "customerEmail": "customer@email.com", "title": null, "status": "ACTIVE", "isSkipped": false, "nextPurchaseDate": "2024-08-21T12:00:00Z", "lastPurchaseDate": "2024-08-19T00:00:00Z", "plan": { "id": "vtex.subscription.ana-plan", "frequency": { "periodicity": "DAILY", "interval": 2 }, "validity": { "begin": "2024-08-01T00:00:00Z", "end": null }, "purchaseDay": "Not_Applicable" }, "shippingAddress": { "addressId": "5028945524109", "addressType": "residential" }, "purchaseSettings": { "paymentMethod": { "paymentAccountId": "B2BBDD0F2E4B47FC9E48D2DA99C318EF", "paymentSystem": "2", "installments": 1, "paymentSystemName": "creditCard", "paymentSystemGroup": "creditCard" }, "currencyCode": "BRL", "selectedSla": "Normal", "salesChannel": "1", "seller": "1" }, "cycleCount": 9, "createdAt": "2024-08-01T12:31:55.7308301Z", "lastUpdate": "2024-08-19T12:16:51.0237801Z", "items": [ { "id": "0213AB4188FE4007A865AD33D972FA37", "skuId": "9", "quantity": 1, "isSkipped": false, "status": "ACTIVE", "originalOrderId": "1451256157912-01", "cycleCount": 9, "priceAtSubscriptionDate": 736.0, "manualPrice": 736.0, "attachments": [ { "name": "printMessage", "content": { "printMessage": "Hello" } } ] } ], "lastCycleId": "F35A8B497EA9E5A6D8F3778CBBA4C9E3-20240819", "customData": null } } } } } } }, "/api/rns/pub/subscriptions/{id}/simulate": { "post": { "tags": [ "Subscriptions" ], "summary": "Calculate the current prices for a subscription", "description": "Simulates an order made by the specific subscription on checkout and retrieves the current price for items and shipping.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Subscriptions | ApplicationAccess | **Subscription view only** |\r\n| Subscriptions | ApplicationAccess | **Subscription view and edit** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "[Subscription](https://help.vtex.com/en/tutorial/how-subscriptions-work--frequentlyAskedQuestions_4453) ID.", "schema": { "type": "string", "example": "8700734451ED4FD4955697873BEC51C3" } }, { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateResponseVO" }, "example": { "simulation": { "items": [ { "id": "9", "seller": "1", "quantity": 1, "price": 12960, "sellingPrice": 12960, "manualPrice": null, "unitMultiplier": 1.0, "measurementUnit": "un", "attachments": null, "name": null, "isGift": false, "priceTags": [] } ], "logisticsInfo": [ { "itemIndex": 0, "quantity": 1, "selectedSla": "Normal", "selectedDeliveryChannel": "delivery", "lockTTL": "1bd", "shippingEstimate": null, "addressId": "5028945524109", "pickupId": null, "price": 0, "deliveryWindow": null, "slas": [ { "id": "Normal", "pickupPointId": null, "deliveryChannel": "delivery", "price": 500, "shippingEstimate": "3bd", "lockTTL": "1bd", "deliveryWindows": [], "availableDeliveryWindows": [] } ] } ], "paymentData": { "payments": [ { "id": null, "paymentSystem": "6", "group": null, "bin": null, "accountId": null, "parentAccountId": null, "referenceValue": 13460, "value": 13460, "installments": 1, "url": null, "cardNumber": null, "fields": null, "paymentSystemName": null } ], "transactions": [] }, "country": null, "postalCode": null, "messages": [], "selectableGifts": [], "totals": [ { "id": "Items", "name": "Items total", "value": 12960 }, { "id": "Shipping", "name": "Shipping total", "value": 500 } ], "totalsBySimulationItems": [ { "id": "9", "quantity": 1, "unitPrice": 12960, "status": "OK", "price": null, "sellingPrice": 12960, "manualPrice": null } ] }, "shippingEstimate": { "name": "Normal", "estimate": "3bd", "estimatedDeliveryDate": "2024-08-26T00:00:00Z", "nextPurchaseDate": "2024-09-26T00:00:00Z", "matched": true }, "totalsBySimulationItems": [ { "id": "9", "quantity": 1, "unitPrice": 12960, "status": "OK", "price": 12960, "sellingPrice": 12960, "manualPrice": null } ], "totals": [ { "id": "Items", "value": 12960.0 }, { "id": "Shipping", "value": 500.0 } ] } } } } } } }, "/api/rns/pub/subscriptions/simulate": { "post": { "tags": [ "Subscriptions" ], "summary": "Calculate the current prices for the provided subscription template", "description": "Simulates an order made by subscriptions on checkout and retrieves the current price for items and shipping.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Subscriptions | ApplicationAccess | **Subscription view only** |\r\n| Subscriptions | ApplicationAccess | **Subscription view and edit** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionGroupRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateResponseVO" }, "example": { "simulation": { "items": [ { "id": "9", "seller": "1", "quantity": 1, "price": 12960, "sellingPrice": 12960, "manualPrice": null, "unitMultiplier": 1.0, "measurementUnit": "un", "attachments": null, "name": null, "isGift": false, "priceTags": [] } ], "logisticsInfo": [ { "itemIndex": 0, "quantity": 1, "selectedSla": "Normal", "selectedDeliveryChannel": "delivery", "lockTTL": "1bd", "shippingEstimate": null, "addressId": "5028945524109", "pickupId": null, "price": 0, "deliveryWindow": null, "slas": [ { "id": "Normal", "pickupPointId": null, "deliveryChannel": "delivery", "price": 500, "shippingEstimate": "3bd", "lockTTL": "1bd", "deliveryWindows": [], "availableDeliveryWindows": [] } ] } ], "paymentData": { "payments": [ { "id": null, "paymentSystem": "6", "group": null, "bin": null, "accountId": null, "parentAccountId": null, "referenceValue": 13460, "value": 13460, "installments": 1, "url": null, "cardNumber": null, "fields": null, "paymentSystemName": null } ], "transactions": [] }, "country": null, "postalCode": null, "messages": [], "selectableGifts": [], "totals": [ { "id": "Items", "name": "Items total", "value": 12960 }, { "id": "Shipping", "name": "Shipping total", "value": 500 } ], "totalsBySimulationItems": [ { "id": "9", "quantity": 1, "unitPrice": 12960, "status": "OK", "price": null, "sellingPrice": 12960, "manualPrice": null } ] }, "shippingEstimate": { "name": "Normal", "estimate": "3bd", "estimatedDeliveryDate": "2024-08-26T00:00:00Z", "nextPurchaseDate": "2024-09-26T00:00:00Z", "matched": true }, "totalsBySimulationItems": [ { "id": "9", "quantity": 1, "unitPrice": 12960, "status": "OK", "price": 12960, "sellingPrice": 12960, "manualPrice": null } ], "totals": [ { "id": "Items", "value": 12960.0 }, { "id": "Shipping", "value": 500.0 } ] } } } } } } }, "/api/rns/pub/subscriptions/{subscriptionId}/conversation-message": { "get": { "tags": [ "Subscriptions" ], "summary": "Get conversation messages", "description": "Retrieves all conversation messages sent to a customer regarding a subscription.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Subscriptions | ApplicationAccess | **Subscription view only** |\r\n| Subscriptions | ApplicationAccess | **Subscription view and edit** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "name": "subscriptionId", "in": "path", "description": "[Subscription](https://help.vtex.com/en/tutorial/how-subscriptions-work--frequentlyAskedQuestions_4453) ID.", "required": true, "style": "simple", "schema": { "type": "string", "default": "123456789abc" } }, { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "Each message exchanged with the customer related to the subscription.", "properties": { "id": { "type": "string", "description": "Message ID." }, "from": { "type": "object", "description": "Information regarding the message sender.", "properties": { "conversationRelatedTo": { "type": "string", "description": "ID of the subscription related to the message." }, "conversationSubject": { "type": "string", "description": "Subject of the conversation." }, "emailAlias": { "type": "string", "description": "Email alias." }, "aliasMaskType": { "type": "string", "description": "Alias [mask type](https://help.vtex.com/en/tutorial/how-communication-with-the-client-is-made-during-the-order-flow--tutorials_195)." }, "email": { "type": "string", "description": "Sender email address." }, "name": { "type": "string", "description": "Sender name." }, "role": { "type": "string", "description": "Sender [role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc).", "nullable": true } } }, "to": { "type": "array", "description": "Information regarding the message receiver.", "items": { "type": "object", "description": "Message receiver details.", "properties": { "conversationRelatedTo": { "type": "string", "description": "ID of the subscription related to the message." }, "conversationSubject": { "type": "string", "description": "Subject of the conversation." }, "emailAlias": { "type": "string", "description": "Email alias." }, "aliasMaskType": { "type": "string", "description": "Alias [mask type](https://help.vtex.com/en/tutorial/how-communication-with-the-client-is-made-during-the-order-flow--tutorials_195)." }, "email": { "type": "string", "description": "Customer email address." }, "name": { "type": "string", "description": "Customer name." }, "role": { "type": "string", "description": "Role identification." } } } }, "subject": { "type": "string", "description": "Message subject." }, "firstWords": { "type": "string", "description": "First words of the message text." }, "body": { "type": "string", "description": "HTML content of the message's body." }, "hasAttachment": { "type": "boolean", "description": "Indicates if the message has [attachments](https://help.vtex.com/en/tutorial/what-is-an-attachment--aGICk0RVbqKg6GYmQcWUm) (`true`) or not (`false`)." }, "attachmentNames": { "type": "array", "description": "Attachment names.", "nullable": true, "items": { "type": "string", "description": "Attachment name.", "nullable": true } }, "date": { "type": "string", "description": "Message date and time in [ISO 8601 time zone offset format](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`." } } } }, "example": [ { "id": "2024-07-25t22-01-08_80e67e10318d4a73a66dbfdb3d471cfb", "from": { "conversationRelatedTo": "875a3b36d02e17058ed46e5b0c50353c", "conversationSubject": "rns", "emailAlias": "a506b3df1b584381b2838447a44d0579@ct.vtex.com.br", "aliasMaskType": "0", "email": "noreply@vtexcommerce.com.br", "name": "no reply", "role": null }, "to": [ { "conversationRelatedTo": "875a3b36d02e17058ed46e5b0c50353c", "conversationSubject": "rns", "emailAlias": "dda23454991e4cfea71ca7beb4ec0aad@ct.vtex.com.br", "aliasMaskType": "0", "email": "sophia.smith@email.com", "name": "Sophia Smith", "role": "Customer" } ], "subject": "Your subscription was confirmed", "firstWords": "Hello, your subscription was successfully created! We will email you a confirmation after each order payment is approved.", "body": "
| Entrega estimada 13/01/2022 |
| | ************2503 |
Atenciosamente,
Equipe CeA.