{ "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": " test
Próxima compra
25/12/2021
Entrega estimada
13/01/2022
************2503
!important; \" align=\"left\">

Atenciosamente,
Equipe CeA.

", "hasAttachment": false, "attachmentNames": [], "date": "2024-07-25T22:01:25Z" } ] } } } } } }, "/api/rns/settings": { "get": { "tags": [ "Settings" ], "summary": "Get subscriptions settings", "description": "Retrieves information about the subscriptions settings of 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 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.", "operationId": "GetSettings", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "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", "default": "application/json" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settings" }, "example": { "slaOption": "STORE_CHOICE", "defaultSla": "Express", "isUsingV3": true, "onMigrationProcess": false, "executionHourInUtc": 9, "workflowVersion": "1.1", "deliveryChannels": [ "delivery", "pickupInPoint" ], "randomIdGeneration": false, "isMultipleInstallmentsEnabledOnCreation": true, "isMultipleInstallmentsEnabledOnUpdate": true, "attachmentPreferences": { "enableAttachments": false, "splitSameSkuWithDifferentAttachments": false }, "orderCustomDataAppId": "customData.customFieldName", "postponeExpiration": false, "manualPriceAllowed": true, "useItemPriceFromOriginalOrder": true } } } } } }, "post": { "tags": [ "Settings" ], "summary": "Edit subscriptions settings", "description": "Edits the subscriptions settings of your store. This configurations apply to all subscriptions.\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.", "operationId": "EditSettings", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "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", "default": "application/json" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "slaOption", "defaultSla", "isUsingV3", "onMigrationProcess", "executionHourInUtc", "workflowVersion", "deliveryChannels", "randomIdGeneration", "isMultipleInstallmentsEnabledOnCreation", "isMultipleInstallmentsEnabledOnUpdate", "orderCustomDataAppId", "postponeExpiration", "manualPriceAllowed", "useItemPriceFromOriginalOrder" ], "properties": { "slaOption": { "description": "Service Level Agreement (SLA) option, which is the shipping method. The possible values are:\r\n- `NONE`: The platform automatically chooses the smallest cost for shipping method at the time of the subscription cycle generation. The `defaultSla` field must remain `null`.\r\n- `CHEAPEST`: Smallest cost for shipping method at the time of cycle generation. The `defaultSla` field must remain `null`.\r\n- `CUSTOMER_CHOICE`: The customer can select the desired shipping method at checkout for every new subscription order. The `defaultSla` field must remain `null`.\r\n- `STORE_CHOICE`: The store sets the preferred shipping method. This is configured in the `defaultSla` field.", "type": "string", "enum": [ "NONE", "CHEAPEST", "CUSTOMER_CHOICE", "STORE_CHOICE" ], "example": "STORE_CHOICE" }, "defaultSla": { "description": "This field contains the shipping method set by the store for new cycle generation. The only case when its value is not `null` is when the `slaOption` field is set as `STORE_CHOICE`.", "type": "string", "nullable": true, "example": "Express" }, "isUsingV3": { "description": "Indicates if the store uses the updated Subscriptions V3 (`true`) or a previous version (`false`).", "type": "boolean", "example": true }, "onMigrationProcess": { "description": "Indicates whether or not the account is in the migration process to Subscriptions V3.", "type": "boolean", "example": false }, "executionHourInUtc": { "description": "Indicates the time future subscription orders will be generated.", "type": "integer", "example": 9 }, "workflowVersion": { "description": "Workflow version.", "type": "string", "example": "1.1" }, "deliveryChannels": { "description": "Array containing delivery channels.", "type": "array", "items": { "description": "Type of delivery channel. The values that are possible are: `pickupInPoint` for [pickup point](https://help.vtex.com/en/tutorial/pickup-points--2fljn6wLjn8M4lJHA6HP3R) and `delivery` for regular delivery.", "type": "string", "example": "delivery", "enum": [ "delivery", "pickupInPoint" ] } }, "randomIdGeneration": { "description": "Defines if subscription order IDs will be randomly generated (`true`) or not (`false`).", "type": "boolean", "example": false }, "isMultipleInstallmentsEnabledOnCreation": { "description": "Defines if the store allows multiple installments when a subscription is created (`true`) or not (`false`).", "type": "boolean", "example": true }, "isMultipleInstallmentsEnabledOnUpdate": { "description": "Defines if the store allows multiple installments when the subscription is updated (`true`) or not (`false`).", "type": "boolean", "example": true }, "attachmentPreferences": { "type": "object", "description": "Store settings on how to process original orders with SKUs that contain [attachments](https://help.vtex.com/en/tutorial/what-is-an-attachment--aGICk0RVbqKg6GYmQcWUm).", "properties": { "enableAttachments": { "type": "boolean", "description": "Defines if the store [keeps attachments from original orders](https://developers.vtex.com/docs/guides/how-to-keep-attachments-from-original-orders-in-subscriptions) and subscription orders incorporate them (`true`) or if these attachments are disconsidered (`false`). By default, this field is set as `false`.", "example": false }, "splitSameSkuWithDifferentAttachments": { "type": "boolean", "description": "Defines if the [same SKUs that contain different attachments](https://developers.vtex.com/docs/guides/how-to-keep-attachments-from-original-orders-in-subscriptions) in the original order are split (`true`) or not (`false`). By default, this field is set as `false`. It can only be set as `true` if the `enableAttachments` field is also set as `true`.", "example": false } } }, "orderCustomDataAppId": { "description": "When there are custom fields configured, this field passes along the `customData` information in the original order to the next subscriptions orders.", "type": "string", "example": "customData.customFieldName", "nullable": true }, "postponeExpiration": { "description": "Defines if the expiration of subscriptions can be postponed (`true`) or not (`false`).", "type": "boolean", "example": false }, "manualPriceAllowed": { "description": "When set to `true`, this property enables [manual price](https://help.vtex.com/en/tutorial/change-the-price-of-an-item-in-the-shopping-cart--7Cd37aCAmtL1qmoZJJvjNf) configuration in subscription items. This is valid for all existing subscriptions, provided that there is a manual price configured and that the `isUsingV3` field is set as `true`.", "type": "boolean", "example": true }, "useItemPriceFromOriginalOrder": { "description": "When set to `true`, this property enables using the manual price for each item from the original subscription order. This is only valid for new subscriptions created from the moment this configuration is enabled. For this to work, it is mandatory that the `manualPriceAllowed` and `isUsingV3` properties are set to `true`.", "type": "boolean", "example": true } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settings" }, "example": { "slaOption": "STORE_CHOICE", "defaultSla": "Express", "isUsingV3": true, "onMigrationProcess": false, "executionHourInUtc": 9, "workflowVersion": "1.1", "deliveryChannels": [ "delivery", "pickupInPoint" ], "randomIdGeneration": false, "isMultipleInstallmentsEnabledOnCreation": true, "isMultipleInstallmentsEnabledOnUpdate": true, "orderCustomDataAppId": "customData.customFieldName", "postponeExpiration": false, "manualPriceAllowed": true, "useItemPriceFromOriginalOrder": true } } } } } } } }, "security": [ { "appKey": [], "appToken": [] }, { "VtexIdclientAutCookie": [] } ], "components": { "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppKey", "description": "Unique identifier of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)." }, "appToken": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppToken", "description": "Secret token of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)." }, "VtexIdclientAutCookie": { "type": "apiKey", "in": "header", "name": "VtexIdclientAutCookie", "description": "[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours." } }, "schemas": { "SimulationItemResult": { "type": "object", "description": "Simulation information about an item.", "properties": { "id": { "type": "string", "description": "SKU ID.", "nullable": true }, "quantity": { "type": "integer", "description": "Quantity of units for the given SKU." }, "unitPrice": { "type": "integer", "format": "int64", "description": "Unit price in cents.", "nullable": true }, "status": { "type": "string", "description": "Subscription cycle status in the simulation." }, "price": { "type": "integer", "description": "Price in cents.", "nullable": true }, "sellingPrice": { "type": "integer", "description": "Selling price in cents." }, "manualPrice": { "type": "number", "description": "[Manual price](https://help.vtex.com/en/tutorial/change-the-price-of-an-item-in-the-shopping-cart--7Cd37aCAmtL1qmoZJJvjNf).", "nullable": true } } }, "SubscriptionCycleResponse": { "type": "object", "description": "Object with information about the subscription cycle.", "properties": { "id": { "type": "string", "description": "Cycle ID. When the `cycleCount` value is `1`, the `id` value will be the same as the `subscriptionId` value." }, "subscriptionId": { "type": "string", "description": "[Subscription](https://help.vtex.com/en/tutorial/how-subscriptions-work--frequentlyAskedQuestions_4453) ID." }, "workflowId": { "type": "string", "description": "Code that identifies the subscription in the [order flow](https://help.vtex.com/en/tutorial/order-flow-and-status--tutorials_196)." }, "status": { "type": "string", "description": "Subscription cycle execution status. 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.", "enum": [ "TRIGGERED", "IN_PROCESS", "FAILURE", "SUCCESS", "EXPIRED", "ORDER_ERROR", "PAYMENT_ERROR", "SKIPED", "SUCCESS_WITH_NO_ORDER", "SUCCESS_WITH_PARTIAL_ORDER", "RE_TRIGGERED", "SCHEDULE_UPDATED" ] }, "customerEmail": { "type": "string", "description": "Customer email." }, "customerId": { "type": "string", "description": "Customer ID." }, "date": { "type": "string", "format": "date-time", "description": "Current date and time in [UTC time format](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`." }, "lastUpdate": { "type": "string", "format": "date-time", "description": "Subscription cycle last update date and time in [UTC time format](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`." }, "cycleCount": { "type": "integer", "description": "The cycle determines the position of an order counting from when the shopper subscribed. The original order that creates the subscription corresponds to cycle count `0`, the first subscription order corresponds to `1`, the second corresponds to `2`, and so on." }, "isInRetry": { "type": "boolean", "description": "Defines if the cycle execution is in retry (`true`), or not (`false`)." }, "message": { "type": "string", "description": "Cycle execution message.", "nullable": true }, "friendlyMessage": { "type": "string", "description": "Cycle execution friendly message.", "nullable": true }, "plan": { "$ref": "#/components/schemas/PlanResponse" }, "orderInfo": { "type": "object", "description": "Subscription order information.", "properties": { "orderId": { "type": "string", "description": "Order ID." }, "orderGroup": { "type": "string", "description": "Order group ID." }, "paymentURL": { "type": "string", "description": "Order payment URL.", "nullable": true }, "value": { "type": "integer", "format": "int64", "description": "Order value in cents." } } }, "context": { "type": "object", "description": "Subscription cycle context.", "properties": { "items": { "type": "array", "description": "Information about subscription cycle items.", "nullable": true, "items": { "type": "object", "description": "Subscription item information.", "properties": { "subscriptionItemId": { "type": "string", "nullable": true, "description": "Subscription item ID." }, "skuId": { "type": "string", "nullable": true, "description": "SKU ID." }, "quantity": { "type": "integer", "description": "Quantity of item units.", "nullable": true }, "status": { "type": "string", "description": "Subscription status.", "nullable": true, "enum": [ "ACTIVE", "PAUSED", "CANCELED", "EXPIRED", "MISSING" ] }, "isSkipped": { "type": "boolean", "description": "Defines if the customer asked to skip the item in the next subscription order (`true`), or not (`false`).", "nullable": true }, "cycleCount": { "type": "integer", "description": "The cycle determines the position of an order counting from when the shopper subscribed. The original order that creates the subscription corresponds to cycle count `0`, the first subscription order corresponds to `1`, the second corresponds to `2`, and so on.", "nullable": true } } } }, "paymentSystem": { "type": "string", "description": "Payment system ID.", "nullable": true }, "paymentSystemName": { "type": "string", "description": "Payment system name.", "nullable": true }, "paymentSystemGroup": { "type": "string", "description": "Payment system group.", "nullable": true }, "paymentAccountId": { "type": "string", "description": "Information about the customer profile and their documents, such as a credit card number. You can also retrieve that information using the [Get client profile by email](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/profiles) endpoint.", "nullable": true }, "addressId": { "type": "string", "description": "Shipping address ID.", "nullable": true }, "addressType": { "type": "string", "description": "Shipping address type.", "nullable": true }, "catalogAttachment": { "type": "string", "description": "Subscription [attachment](https://help.vtex.com/en/tutorial/what-is-an-attachment--aGICk0RVbqKg6GYmQcWUm) content, when applicable.", "nullable": true } } }, "simulationItems": { "type": "array", "description": "Subscription simulation items.", "items": { "$ref": "#/components/schemas/SimulationItemResult" }, "nullable": true } } }, "StorePlan": { "type": "object", "description": "Subscription [plan](https://help.vtex.com/en/tutorial/subscription-plans-beta--5kczKRqHEsrs1tYtRcY8wR) object.", "properties": { "id": { "type": "string", "description": "Subscription plan ID." }, "frequencies": { "type": "array", "description": "Array of the plan frequencies.", "items": { "type": "object", "description": "Information about the plan periodicity and interval.", "properties": { "periodicity": { "type": "string", "description": "Repurchase frequency requested by the customer, defines the subscriptions recurrence period.", "nullable": true, "enum": [ "DAILY", "WEEKLY", "MONTHLY", "YEARLY" ] }, "interval": { "type": "integer", "description": "Time interval configured between subscription orders, which depends on the periodicity. For a `DAILY` periodicity, the value will be days, for `MONTHLY` it will be months, and so on." } } } }, "isActive": { "type": "boolean", "description": "Defines if the plan is active (`true`) or not (`false`)." }, "importInProgress": { "type": "boolean", "description": "Defines if a SKU importing process is in progress (`true`) or not (`false`)." }, "attachmentId": { "type": "integer", "description": "Plan attachment ID." }, "isValid": { "type": "boolean", "description": "Defines if the plan is valid (`true`) or not (`false`)." }, "validationMessages": { "type": "array", "description": "List of validation messages.", "nullable": true, "items": { "type": "string", "description": "Validation message." } }, "validity": { "type": "object", "description": "Information about the period during which the subscription plan will be valid.", "nullable": true, "properties": { "begin": { "type": "string", "format": "date-time", "description": "Subscription plan beginning date and time in [UTC time format](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`." }, "end": { "type": "string", "format": "date-time", "description": "Subscription plan ending date and time in [UTC time format](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`.", "nullable": true } } }, "purchaseDays": { "type": "array", "description": "Time reference in which subscription orders will be created.", "items": { "type": "string", "description": "Time reference in which subscription orders will be created. It will depend on the cycle periodicity, for `WEEKLY` subscriptions, for example, the purchase day could be `Sunday`. For `MONTHLY`, would be `7`, as in the 7th day of the month. When the subscription periodicity is `DAILY`, this field corresponds to `Not_Applicable`." } } } }, "ReportResponse": { "type": "object", "description": "Subscription report information.", "properties": { "id": { "type": "string", "description": "Report document ID." }, "finished": { "type": "boolean", "description": "Defines if the report is finished (`true`) or not (`false`)." }, "recordsProcessed": { "type": "integer", "description": "Number of records processed at the moment." }, "recordsSum": { "type": "integer", "description": "Total number of records to be processed.", "nullable": true }, "startDate": { "type": "string", "description": "Report starting 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`.", "nullable": true }, "lastUpdateTime": { "type": "string", "description": "Report last update 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`.", "nullable": true }, "completedDate": { "type": "string", "description": "Report completion 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`.", "nullable": true }, "errorCount": { "type": "integer", "description": "Error counting numbers, when applicable.", "nullable": true }, "percentageProcessed": { "type": "number", "description": "Report processing percentage." }, "enqueueDate": { "type": "string", "description": "Request enqueue 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`.", "nullable": true }, "email": { "type": "string", "description": "Email of the user that receives the report." }, "canceled": { "type": "boolean", "description": "Defines if the report is canceled (`true`) or not (`false`)." }, "outputType": { "type": "string", "description": "Report file extension.", "nullable": true }, "zipped": { "type": "boolean", "description": "Defines if the report file is zipped (`true`) or not (`false`)." }, "linkToDownload": { "type": "string", "description": "Link do download the report.", "nullable": true }, "lastErrorMessage": { "type": "string", "description": "Error last message, when applicable.", "nullable": true }, "statusMessage": { "type": "string", "description": "Report status message." } } }, "PlanResponse": { "type": "object", "description": "[Subscription plan](https://help.vtex.com/en/tutorial/subscription-plans-beta--5kczKRqHEsrs1tYtRcY8wR) object.", "required": [ "frequency", "id", "purchaseDay", "validity" ], "properties": { "id": { "type": "string", "description": "Subscription plan ID.", "nullable": true }, "frequency": { "type": "object", "description": "Subscription plan frequency.", "required": [ "interval", "periodicity" ], "properties": { "periodicity": { "type": "string", "description": "Plan repurchase frequency, defines the subscription recurrence.", "nullable": true, "enum": [ "DAILY", "WEEKLY", "MONTHLY", "YEARLY" ] }, "interval": { "type": "integer", "description": "Time interval configured between subscription orders, which depends on the periodicity. For a `DAILY` periodicity, the value will be days, for `MONTHLY` it will be months, and so on." } } }, "validity": { "type": "object", "description": "Information about the period during which the subscription plan will be valid.", "required": [ "begin" ], "properties": { "begin": { "type": "string", "description": "Subscription plan beginning date and time in [UTC time format](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`." }, "end": { "type": "string", "description": "Subscription plan ending date and time in [UTC time format](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`.", "nullable": true } } }, "purchaseDay": { "type": "string", "description": "Time reference in which subscription orders will be created. It will depend on the cycle periodicity, for `WEEKLY` subscriptions, for example, the purchase day could be `Sunday`. For `MONTHLY`, would be `7`, as in the 7th day of the month. When the subscription periodicity is `DAILY`, this field corresponds to `Not_Applicable`." } } }, "SubscriptionGroupResponse": { "type": "object", "description": "Information about a given subscription.", "required": [ "createdAt", "customerEmail", "customerId", "cycleCount", "id", "isSkipped", "items", "lastUpdate", "nextPurchaseDate", "plan", "purchaseSettings", "shippingAddress", "status" ], "properties": { "id": { "type": "string", "description": "[Subscription](https://help.vtex.com/en/tutorial/how-subscriptions-work--frequentlyAskedQuestions_4453) ID." }, "customerId": { "type": "string", "description": "Customer ID." }, "customerEmail": { "type": "string", "description": "Customer email." }, "title": { "type": "string", "description": "Subscription title.", "nullable": true }, "status": { "type": "string", "description": "Subscription status.", "enum": [ "ACTIVE", "PAUSED", "CANCELED", "EXPIRED", "MISSING" ] }, "isSkipped": { "type": "boolean", "description": "Defines if the customer asked to skip the next subscription order (`true`), or not (`false`)." }, "nextPurchaseDate": { "type": "string", "description": "Next purchase 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`." }, "lastPurchaseDate": { "type": "string", "description": "Last purchase 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`.", "nullable": true }, "plan": { "$ref": "#/components/schemas/PlanResponse" }, "shippingAddress": { "type": "object", "description": "Information about the subscription shipping address.", "required": [ "addressId", "addressType" ], "properties": { "addressId": { "type": "string", "description": "Shipping address ID or [pickup point](https://help.vtex.com/en/tutorial/pickup-points--2fljn6wLjn8M4lJHA6HP3R) ID, according to the shipping address type." }, "addressType": { "type": "string", "description": "Type of the address. The possible values are `residential`, when the customer gives an address for delivery, or `pickup`, when the customer picks the order at a pickup point.", "enum": [ "residential", "pickup" ] } } }, "purchaseSettings": { "type": "object", "description": "Object with purchase information.", "required": [ "currencyCode", "paymentMethod" ], "properties": { "paymentMethod": { "type": "object", "description": "[Payment method](https://help.vtex.com/en/tutorial/difference-between-payment-methods-and-payment-conditions--3azJenhGFyUy2gsocms42Q) information.", "required": [ "paymentSystem" ], "properties": { "paymentAccountId": { "type": "string", "description": "Payment account ID.", "nullable": true }, "paymentSystem": { "type": "string", "description": "Payment system ID." }, "installments": { "type": "integer", "description": "Number of installments." }, "paymentSystemName": { "type": "string", "description": "Payment system name." }, "paymentSystemGroup": { "type": "string", "description": "Payment system group." } } }, "currencyCode": { "type": "string", "description": "Currency code in [ISO 4217](https://www.iban.com/currency-codes) format." }, "selectedSla": { "type": "string", "description": "Selected Service Level Agreement (SLA)." }, "salesChannel": { "type": "string", "description": "Sales channel ([trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV)) associated with the purchase." }, "seller": { "type": "string", "description": "Seller name. When the store acts both as marketplace and seller, this field corresponds to `1`, because every VTEX store is its own seller 1." } } }, "cycleCount": { "type": "integer", "description": "The cycle determines the position of an order counting from when the customer subscribed. The original order that creates the subscription corresponds to cycle count `0`, the first subscription order corresponds to `1`, the second corresponds to `2`, and so on." }, "createdAt": { "type": "string", "description": "Subscription creation 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`." }, "lastUpdate": { "type": "string", "description": "Date and time of the last subscription update 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`.", "nullable": true }, "items": { "type": "array", "description": "Information about subscription items.", "items": { "type": "object", "description": "Information about a given subscription item.", "required": [ "id", "isSkipped", "quantity", "skuId", "status" ], "properties": { "id": { "type": "string", "description": "Subscription item ID." }, "skuId": { "type": "string", "description": "SKU ID." }, "quantity": { "type": "integer", "description": "Quantity of units." }, "isSkipped": { "type": "boolean", "description": "Defines if the customer asked to skip the item in the next subscription order (`true`), or not (`false`)." }, "status": { "type": "string", "description": "Subscription status.", "enum": [ "ACTIVE", "PAUSED", "CANCELED", "EXPIRED", "MISSING" ] }, "originalOrderId": { "type": "string", "description": "Subscription original order ID." }, "cycleCount": { "type": "integer", "description": "The cycle determines the position of an order counting from when the customer subscribed. The original order that creates the subscription corresponds to cycle count `0`, the first subscription order corresponds to `1`, the second corresponds to `2`, and so on." }, "priceAtSubscriptionDate": { "type": "number", "description": "Price at subscription date." }, "manualPrice": { "type": "number", "description": "[Manual price](https://help.vtex.com/en/tutorial/change-the-price-of-an-item-in-the-shopping-cart--7Cd37aCAmtL1qmoZJJvjNf)." }, "attachments": { "type": "array", "description": "Information about subscription [attachments](https://help.vtex.com/en/tutorial/what-is-an-attachment--aGICk0RVbqKg6GYmQcWUm).", "nullable": true, "items": { "type": "object", "description": "Information about a given attachment.", "properties": { "name": { "type": "string", "description": "Attachment name.", "nullable": true }, "content": { "type": "object", "description": "Custom field for attachment content.", "nullable": true, "additionalProperties": { "type": "string", "description": "Custom field information." } } } } } } } }, "lastCycleId": { "type": "string", "description": "Last subscription cycle ID.", "nullable": true }, "customData": { "type": "object", "description": "Customizable fields created by the store for the shopping cart. This field is useful for storing data not included in other fields, for example, a message for a gift or a name to be printed in a shirt.", "nullable": true, "properties": { "customApps": { "type": "array", "description": "Customizable apps created by the store.", "nullable": true, "items": { "type": "string", "description": "Customizable apps details.", "nullable": true } } } } } }, "PlanRequest": { "type": "object", "description": "[Subscription plan](https://help.vtex.com/en/tutorial/subscription-plans-beta--5kczKRqHEsrs1tYtRcY8wR) object.", "required": [ "id", "frequency" ], "properties": { "id": { "type": "string", "description": "Subscription plan ID.", "example": "subscription.clothes" }, "frequency": { "required": [ "interval", "periodicity" ], "type": "object", "description": "Subscription plan frequency.", "properties": { "periodicity": { "type": "string", "description": "Plan repurchase frequency, defines the subscription recurrence.", "enum": [ "DAILY", "WEEKLY", "MONTHLY", "YEARLY" ], "example": "MONTHLY" }, "interval": { "type": "integer", "description": "Time interval configured between subscription orders, which depends on the periodicity. For a `DAILY` periodicity, the value will be measured in days, for `MONTHLY` it will be measured in months, and so on.", "example": 3 } } }, "validity": { "type": "object", "description": "Information about the period during which the subscription plan will be valid.", "properties": { "begin": { "type": "string", "description": "Subscription plan beginning date and time in [UTC time format](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`.", "example": "2024-08-21T00:00:00Z", "nullable": true }, "end": { "type": "string", "description": "Subscription plan ending date and time in [UTC time format](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`.", "example": "2025-08-21T00:00:00Z", "nullable": true } } }, "purchaseDay": { "type": "string", "description": "Time reference in which subscription orders will be created. It will depend on the cycle periodicity, for `WEEKLY` subscriptions, for example, the purchase day could be `Sunday`. For `MONTHLY`, would be `7`, as in the 7th day of the month. This field is not required for `DAILY` subscriptions.", "nullable": true, "example": "3" } } }, "ShippingAddressRequest": { "type": "object", "description": "Information about the subscription shipping address.", "required": [ "addressId", "addressType" ], "properties": { "addressId": { "type": "string", "description": "Shipping address ID or [pickup point](https://help.vtex.com/en/tutorial/pickup-points--2fljn6wLjn8M4lJHA6HP3R) ID, according to the shipping address type.", "example": "5028945524109" }, "addressType": { "type": "string", "description": "Type of the address. The possible values are `residential`, when the customer gives an address for delivery, or `pickup`, when the customer picks the order at a pickup point.", "enum": [ "residential", "pickup" ], "example": "residential" } } }, "PurchaseSettingsRequest": { "type": "object", "description": "Object with purchase settings information.", "required": [ "paymentMethod", "salesChannel" ], "properties": { "paymentMethod": { "type": "object", "description": "Object with [payment method](https://help.vtex.com/en/tutorial/difference-between-payment-methods-and-payment-conditions--3azJenhGFyUy2gsocms42Q) information.", "required": [ "paymentSystem", "paymentAccountId" ], "properties": { "paymentAccountId": { "type": "string", "description": "ID of the payment account. You can find the ID using the endpoint [Get client profile by email](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/profiles), in `availableAccounts.[].accountId`.", "example": "6559E125DB084A46994E045547DE504B" }, "paymentSystem": { "type": "string", "description": "Payment system ID.", "example": "4" }, "installments": { "type": "integer", "description": "Number of installments.", "nullable": true, "example": 3 }, "paymentSystemName": { "type": "string", "description": "Payment system name.", "nullable": true, "example": "creditCard" }, "paymentSystemGroup": { "type": "string", "description": "Payment system group.", "nullable": true, "example": "creditCard" } } }, "currencyCode": { "type": "string", "description": "Currency code in [ISO 4217](https://www.iban.com/currency-codes) format.", "example": "BRL" }, "selectedSla": { "type": "string", "description": "Selected Service Level Agreement (SLA).", "example": "Normal" }, "salesChannel": { "type": "string", "description": "Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV)) applied to the subscription. You can associate only one sales channel to each subscription. The default value is the main sales channel, which corresponds to `1`.", "example": "1" }, "seller": { "type": "string", "description": "Seller name. When the store acts both as marketplace and seller, this field corresponds to `1`, because every VTEX store is its own seller 1.", "example": "1" } } }, "SubscriptionGroupRequest": { "type": "object", "description": "Object with subscription information.", "required": [ "customerEmail", "items", "plan", "purchaseSettings", "shippingAddress" ], "properties": { "customerEmail": { "type": "string", "description": "Customer email.", "example": "customer@email.com" }, "title": { "type": "string", "description": "Subscription title.", "example": "fashionBasic", "nullable": true }, "status": { "type": "string", "description": "Subscription status.", "enum": [ "ACTIVE", "PAUSED", "CANCELED", "EXPIRED", "MISSING" ], "example": "ACTIVE", "nullable": true }, "nextPurchaseDate": { "type": "string", "description": "Subscription next purchase 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": "2024-09-21T00:00:00Z" }, "catalogAttachment": { "type": "string", "description": "Subscription [attachment](https://help.vtex.com/en/tutorial/what-is-an-attachment--aGICk0RVbqKg6GYmQcWUm) content.", "example": "vtex.subscription.tshirt-collection", "nullable": true }, "plan": { "$ref": "#/components/schemas/PlanRequest" }, "shippingAddress": { "$ref": "#/components/schemas/ShippingAddressRequest" }, "purchaseSettings": { "$ref": "#/components/schemas/PurchaseSettingsRequest" }, "items": { "type": "array", "description": "List with subscription items information.", "items": { "type": "object", "description": "Information about a given item.", "required": [ "skuId", "quantity" ], "properties": { "skuId": { "type": "string", "description": "SKU ID.", "example": "12" }, "quantity": { "type": "integer", "description": "Quantity of units.", "example": 5 }, "manualPrice": { "type": "number", "description": "[Manual price](https://help.vtex.com/en/tutorial/change-the-price-of-an-item-in-the-shopping-cart--7Cd37aCAmtL1qmoZJJvjNf).", "example": 400.0, "nullable": true }, "attachments": { "type": "array", "description": "Information about subscription [attachments](https://help.vtex.com/en/tutorial/what-is-an-attachment--aGICk0RVbqKg6GYmQcWUm).", "items": { "type": "object", "description": "Information about a given attachment.", "required": [ "name", "content" ], "properties": { "name": { "type": "string", "description": "Attachment name.", "example": "Engraving" }, "content": { "type": "object", "description": "Custom field for attachment content.", "additionalProperties": { "type": "string", "description": "Custom field information.", "example": "Happy Birthday!" } } } } } } } } } }, "PriceTag": { "type": "object", "description": "Information about a given price tag.", "properties": { "name": { "type": "string", "description": "Price tag name.", "nullable": true }, "valueAsInt": { "type": "integer", "format": "int64", "description": "Price tag value." }, "rawValue": { "type": "number", "format": "double", "description": "Price tag raw value." }, "isPercentual": { "type": "boolean", "description": "Defines if the price tag is applied as a percentage (`true`), or not (`false`)." }, "identifier": { "type": "string", "description": "Price tag identifier.", "nullable": true } } }, "SimulateResponseVO": { "type": "object", "description": "Subscription order simulation response.", "properties": { "simulation": { "type": "object", "description": "Object with subscription order simulation details.", "properties": { "items": { "type": "array", "description": "Simulation items information.", "items": { "type": "object", "description": "Simulation information about a given item.", "properties": { "id": { "type": "string", "description": "SKU ID.", "nullable": true }, "seller": { "type": "string", "description": "Seller name. When the store acts both as marketplace and seller, this field corresponds to `1`, because every VTEX store is its own seller 1.", "nullable": true }, "quantity": { "type": "integer", "description": "Quantity of units." }, "price": { "type": "integer", "format": "int64", "description": "Price in cents.", "nullable": true }, "sellingPrice": { "type": "integer", "format": "int64", "description": "Selling price in cents.", "nullable": true }, "manualPrice": { "type": "number", "description": "[Manual price](https://help.vtex.com/en/tutorial/change-the-price-of-an-item-in-the-shopping-cart--7Cd37aCAmtL1qmoZJJvjNf).", "nullable": true }, "unitMultiplier": { "type": "number", "description": "Item unit multiplier." }, "measurementUnit": { "type": "string", "description": "Item measurement unit." }, "attachments": { "type": "array", "description": "Information about subscription [attachments](https://help.vtex.com/en/tutorial/what-is-an-attachment--aGICk0RVbqKg6GYmQcWUm).", "nullable": true, "items": { "type": "object", "description": "Information about a given attachment.", "properties": { "name": { "type": "string", "description": "Attachment name.", "nullable": true }, "content": { "type": "object", "description": "Custom field for attachment content.", "nullable": true, "additionalProperties": { "type": "string", "description": "Custom field information." } } } } }, "name": { "type": "string", "description": "Item name.", "nullable": true }, "isGift": { "type": "boolean", "description": "Defines it the item is a gift (`true`), or not (`false`)." }, "priceTags": { "type": "array", "description": "List of price tags, which are price modifiers.", "nullable": true, "items": { "$ref": "#/components/schemas/PriceTag" } } } } }, "logisticsInfo": { "type": "array", "description": "Simulation logistics information.", "items": { "type": "object", "description": "Logistics details.", "properties": { "itemIndex": { "type": "integer", "description": "Each item in the subscription order is identified by an index. The position starts at `0`, followed by `1`, `2`, and so on." }, "quantity": { "type": "integer", "description": "Quantity of units." }, "selectedSla": { "type": "string", "description": "Selected Service Level Agreement (SLA).", "nullable": true }, "selectedDeliveryChannel": { "type": "string", "description": "Shipping type (shipping method) selected by the customer, like delivery or [pickup point](https://help.vtex.com/en/tutorial/pickup-points--2fljn6wLjn8M4lJHA6HP3R).", "enum": [ "delivery", "pickup-in-point" ], "nullable": true }, "lockTTL": { "type": "string", "description": "Logistics [reservation](https://help.vtex.com/en/tutorial/how-does-reservation-work--tutorials_92) waiting time of the SLA in days. One business day corresponds to `1bd`, for example.", "nullable": true }, "shippingEstimate": { "type": "string", "description": "Shipping estimate time in days. Three business days correspond to `3bd`, for example.", "nullable": true }, "addressId": { "type": "string", "description": "Shipping address ID.", "nullable": true }, "pickupId": { "type": "string", "description": "[Pickup point](https://help.vtex.com/en/tutorial/pickup-points--2fljn6wLjn8M4lJHA6HP3R) ID, when shipping type is pickup.", "nullable": true }, "price": { "type": "integer", "description": "Shipping cost.", "nullable": true }, "deliveryWindow": { "type": "string", "description": "[Scheduled delivery window](https://help.vtex.com/tutorial/scheduled-delivery--22g3HAVCGLFiU7xugShOBi) period.", "nullable": true }, "slas": { "type": "array", "description": "Service Level Agreement (SLA) of the [shipping policy](https://help.vtex.com/en/tutorial/shipping-policy--tutorials_140) considered for the simulation.", "items": { "type": "object", "description": "Subscription order SLA details.", "properties": { "id": { "type": "string", "description": "ID of the shipping type (shipping method) of the shipping policy.", "nullable": true }, "pickupPointId": { "type": "string", "description": "[Pickup point](https://help.vtex.com/en/tutorial/pickup-points--2fljn6wLjn8M4lJHA6HP3R) ID related to the SLA.", "nullable": true }, "deliveryChannel": { "type": "string", "description": "Defines if the delivery channel is `delivery` or `pickup-in-point`.", "enum": [ "delivery", "pickup-in-point" ], "nullable": true }, "price": { "type": "integer", "description": "Item shipping price in cents. This value does not account for the order total shipping price." }, "shippingEstimate": { "type": "string", "description": "Total shipping estimate time in days. For instance, three business days is represented as `3bd`.", "nullable": true }, "lockTTL": { "type": "string", "description": "Logistics [reservation](https://help.vtex.com/en/tutorial/how-does-reservation-work--tutorials_92) waiting time of the SLA. One business day is represented as `1bd`, for example.", "nullable": true }, "deliveryWindows": { "type": "array", "description": "[Delivery windows](https://help.vtex.com/en/tutorial/scheduled-delivery--22g3HAVCGLFiU7xugShOBi#delivery-window) information.", "nullable": true, "items": { "type": "object", "description": "Information about a given delivery window.", "properties": { "startDateUtc": { "type": "string", "description": "Delivery window starting 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`.", "nullable": true }, "endDateUtc": { "type": "string", "description": "Delivery window ending 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`.", "nullable": true }, "price": { "type": "integer", "format": "int64", "description": "Delivery window shipping price.", "nullable": true } } } }, "availableDeliveryWindows": { "type": "array", "description": "Available [delivery windows](https://help.vtex.com/en/tutorial/scheduled-delivery--22g3HAVCGLFiU7xugShOBi#delivery-window) information.", "nullable": true, "items": { "type": "object", "description": "Information about an available delivery window.", "properties": { "startDateUtc": { "type": "string", "description": "Available delivery window starting 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`.", "nullable": true }, "endDateUtc": { "type": "string", "description": "Available delivery window ending 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`.", "nullable": true }, "price": { "type": "integer", "format": "int64", "description": "Delivery window shipping price.", "nullable": true } } } } } } } } } }, "paymentData": { "type": "object", "description": "Simulation payment information.", "nullable": true, "properties": { "payments": { "type": "array", "description": "Payment information.", "nullable": true, "items": { "type": "object", "description": "Payment details.", "nullable": true, "properties": { "id": { "type": "string", "description": "Payment ID unique identifier in VTEX.", "nullable": true }, "paymentSystem": { "type": "string", "description": "Payment system ID.", "nullable": true }, "group": { "type": "string", "description": "Payment system group.", "nullable": true }, "bin": { "type": "string", "description": "Abbreviation for _Bank Identification Number_, which is a code that identifies the institution responsible for issuing the credit card.", "nullable": true }, "accountId": { "type": "string", "description": "Store account ID.", "nullable": true }, "parentAccountId": { "type": "string", "description": "Retrieves the main account ID if the payment was made in a subaccount.", "nullable": true }, "referenceValue": { "type": "integer", "format": "int64", "description": "Payment reference value in cents.", "nullable": true }, "value": { "type": "integer", "format": "int64", "description": "Payment value in cents.", "nullable": true }, "installments": { "type": "integer", "description": "Number of installments.", "nullable": true }, "url": { "type": "string", "description": "Payment URL.", "nullable": true }, "cardNumber": { "type": "string", "description": "Card number information.", "nullable": true }, "fields": { "type": "array", "description": "Payment parameters names and values.", "nullable": true, "items": { "type": "object", "description": "Information about a given payment parameter.", "properties": { "name": { "type": "string", "description": "Payment parameter name.", "nullable": true }, "value": { "type": "string", "description": "Payment parameter value.", "nullable": true } } } }, "paymentSystemName": { "type": "string", "description": "Payment system name.", "nullable": true } } } }, "transactions": { "type": "array", "description": "Financial transactions information. This array returns empty in the simulation.", "nullable": true, "items": { "type": "object", "description": "Financial transactions details.", "nullable": true, "properties": { "isActive": { "type": "boolean", "description": "Defines if the subscription order payment is active (`true`) or inactive (`false`).", "nullable": true } } } } } }, "country": { "type": "string", "description": "Subscription order simulation three-digit country code in [ISO 3166 ALPHA-3](https://www.iban.com/country-codes) format.", "nullable": true }, "postalCode": { "type": "string", "description": "Subscription order simulation postal code.", "nullable": true }, "messages": { "type": "array", "description": "Simulation messages information.", "nullable": true, "items": { "type": "object", "description": "Simulation message details.", "nullable": true, "properties": { "code": { "type": "string", "description": "Message code.", "nullable": true }, "status": { "type": "string", "description": "Message status.", "nullable": true }, "text": { "type": "string", "description": "Message text.", "nullable": true } } } }, "selectableGifts": { "type": "array", "description": "Information about subscription selectable gifts. For example, when the customer gains a gift from the store based on a promotion.", "nullable": true, "items": { "type": "object", "description": "Selectable gift information.", "properties": { "id": { "type": "string", "description": "Selectable gift ID.", "nullable": true }, "availableQuantity": { "type": "integer", "description": "Available quantity of selectable gifts.", "nullable": true }, "availableGifts": { "type": "array", "description": "Details about available gifts.", "nullable": true, "items": { "type": "object", "description": "Information about a given available gift.", "nullable": true, "properties": { "id": { "type": "string", "description": "Gift ID.", "nullable": true }, "seller": { "type": "string", "description": "Seller name.", "nullable": true }, "quantity": { "type": "integer", "description": "Quantity of units.", "nullable": true }, "price": { "type": "integer", "format": "int64", "description": "Price in cents.", "nullable": true }, "sellingPrice": { "type": "integer", "format": "int64", "description": "Selling price in cents.", "nullable": true }, "unitMultiplier": { "type": "number", "description": "Unit multiplier.", "nullable": true }, "attachments": { "type": "array", "description": "Available gift attachments information, when applicable.", "nullable": true, "items": { "type": "object", "description": "Information about a given attachment.", "nullable": true, "properties": { "name": { "type": "string", "description": "Gift attachment name.", "nullable": true }, "content": { "type": "object", "description": "Custom field for the gift attachment content.", "nullable": true, "additionalProperties": { "type": "string", "description": "Custom field information.", "nullable": true } } } } }, "name": { "type": "string", "description": "Gift name.", "nullable": true }, "isGift": { "type": "boolean", "description": "Defines it the item is from a gift list (`true`), or not (`false`).", "nullable": true }, "priceTags": { "type": "array", "description": "List of price tags, which are price modifiers.", "nullable": true, "items": { "$ref": "#/components/schemas/PriceTag" } }, "isSelected": { "type": "boolean", "description": "Defines if the item can be selected (`true`), or not (`false`).", "nullable": true } } } } } } }, "totals": { "type": "array", "description": "Information about simulation total counts.", "items": { "type": "object", "description": "Details about a given total count.", "properties": { "id": { "type": "string", "description": "Code that identifies if the information is about items, discounts, shipping or taxes.", "enum": [ "Items", "Discounts", "Shipping", "Tax" ] }, "name": { "type": "string", "description": "Total count name." }, "valueAsInt": { "type": "integer", "format": "int64", "description": "Total count value in cents." } } } }, "totalsBySimulationItems": { "type": "array", "description": "Information about simulation totals regarding items.", "items": { "$ref": "#/components/schemas/SimulationItemResult" } } } }, "shippingEstimate": { "type": "object", "description": "Subscription order shipping estimate information.", "properties": { "name": { "type": "string", "description": "ID of the shipping type (shipping method) of the [shipping policy](https://help.vtex.com/en/tutorial/shipping-policy--tutorials_140)." }, "estimate": { "type": "string", "description": "Total shipping estimate time in days. Three business days is represented as `3bd`, for example." }, "estimateDeliveryDate": { "type": "string", "description": "Estimate delivery 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`." }, "nextPurchaseDate": { "type": "string", "description": "Next purchase 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`." }, "matched": { "type": "boolean", "description": "Defines if the shipping estimate is matched (`true`), or not (`false`)." } } }, "totalsBySimulationItems": { "type": "array", "description": "Information about simulation totals regarding items.", "items": { "$ref": "#/components/schemas/SimulationItemResult" } }, "totals": { "type": "array", "description": "Information about total counts.", "items": { "type": "object", "description": "Total cost per shipping or items.", "properties": { "id": { "type": "string", "description": "Code that identifies if the information is about items, discounts, shipping or taxes.", "enum": [ "Items", "Discounts", "Shipping", "Tax" ] }, "value": { "type": "number", "description": "Total count value." } } } } } }, "Settings": { "description": "VTEX account subscriptions settings.", "type": "object", "required": [ "slaOption", "defaultSla", "isUsingV3", "onMigrationProcess", "executionHourInUtc", "workflowVersion", "deliveryChannels", "randomIdGeneration", "isMultipleInstallmentsEnabledOnCreation", "isMultipleInstallmentsEnabledOnUpdate", "orderCustomDataAppId", "postponeExpiration", "manualPriceAllowed", "useItemPriceFromOriginalOrder" ], "properties": { "slaOption": { "description": "Service Level Agreement (SLA) option, which is the shipping method. The possible values are:\r\n- `NONE`: The platform automatically chooses the smallest cost for shipping method at the time of the subscription cycle generation.\r\n- `CHEAPEST`: Smallest cost for shipping method at the time of cycle generation.\r\n- `CUSTOMER_CHOICE`: The customer can select the desired shipping method at checkout for every new subscription order.\r\n- `STORE_CHOICE`: The store sets the preferred shipping method. This is configured in the `defaultSla` field.", "type": "string", "enum": [ "NONE", "CHEAPEST", "CUSTOMER_CHOICE", "STORE_CHOICE" ] }, "defaultSla": { "description": "This field contains the shipping method set by the store for new cycle generation. The only case when its value is not `null` is when the `slaOption` field is set as `STORE_CHOICE`.", "type": "string", "nullable": true }, "isUsingV3": { "description": "Indicates if the store uses the updated Subscriptions V3 (`true`) or a previous version (`false`).", "type": "boolean" }, "onMigrationProcess": { "description": "Indicates if the store is in the process of migrating to Subscriptions V3 (`true`) or not (`false`).", "type": "boolean" }, "executionHourInUtc": { "description": "Indicates the time future subscription orders will be generated.", "type": "integer" }, "workflowVersion": { "description": "Workflow version.", "type": "string" }, "deliveryChannels": { "description": "Array containing delivery channels.", "type": "array", "items": { "description": "Type of delivery channel. The values that are possible are: `pickupInPoint` for [pickup point](https://help.vtex.com/en/tutorial/pickup-points--2fljn6wLjn8M4lJHA6HP3R) and `delivery` for regular delivery.", "type": "string", "enum": [ "delivery", "pickupInPoint" ] } }, "randomIdGeneration": { "description": "Defines if subscription order IDs are randomly generated (`true`) or not (`false`).", "type": "boolean" }, "isMultipleInstallmentsEnabledOnCreation": { "description": "Defines if the store allows multiple installments when a subscription is created (`true`) or not (`false`).", "type": "boolean" }, "isMultipleInstallmentsEnabledOnUpdate": { "description": "Defines if the store allows multiple installments when the subscription is updated (`true`) or not (`false`).", "type": "boolean" }, "attachmentPreferences": { "type": "object", "description": "Store settings on how to process original orders with SKUs that contain [attachments](https://help.vtex.com/en/tutorial/what-is-an-attachment--aGICk0RVbqKg6GYmQcWUm).", "properties": { "enableAttachments": { "type": "boolean", "description": "Defines if the store [keeps attachments from original orders](https://developers.vtex.com/docs/guides/how-to-keep-attachments-from-original-orders-in-subscriptions) and subscription orders incorporate them (`true`) or if these attachments are disconsidered (`false`). By default, this field is set as `false`." }, "splitSameSkuWithDifferentAttachments": { "type": "boolean", "description": "Defines if the [same SKUs that contain different attachments](https://developers.vtex.com/docs/guides/how-to-keep-attachments-from-original-orders-in-subscriptions) in the original order are split (`true`) or not (`false`). By default, this field is set as `false`. It can only be set as `true` if the `enableAttachments` field is also set as `true`." } } }, "orderCustomDataAppId": { "description": "When there are custom fields configured, this field passes along the `customData` information in the original order to the next subscriptions orders.", "type": "string", "nullable": true }, "postponeExpiration": { "description": "Defines if the expiration of subscriptions can be postponed (`true`) or not (`false`).", "type": "boolean" }, "manualPriceAllowed": { "description": "Defines if the [manual price](https://help.vtex.com/en/tutorial/change-the-price-of-an-item-in-the-shopping-cart--7Cd37aCAmtL1qmoZJJvjNf) configuration is enabled for subscriptions items (`true`), or not (`false`). This is valid for all existing subscriptions, provided that there is a manual price configured and that the `isUsingV3` field is set as `true`.", "type": "boolean" }, "useItemPriceFromOriginalOrder": { "description": "When set to `true`, this property enables using the manual price for each item from the original subscription order. This is only valid for new subscriptions created from the moment this configuration is enabled. For this to work, it is mandatory that the `manualPriceAllowed` and `isUsingV3` properties are set to `true`.", "type": "boolean" } } } } }, "tags": [ { "name": "Cycles" }, { "name": "Plans" }, { "name": "Reports" }, { "name": "Subscriptions" }, { "name": "Settings" } ] }