Subscriptions API (v3)
A Subscription is a list of items (SKUs) tied to certain recurring purchase settings: User profile Address Payment method Frequency Cycle Once you have…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
A Subscription is a list of items (SKUs) tied to certain recurring purchase settings:
- User profile
- Address
- Payment method
- Frequency
- Cycle
Once you have configured subscriptions in your store, the Subscriptions API allows you to create, manage and monitor your customers' subscriptions.
To read more about the Subscriptions feature, check our article How Subscription works.
Endpoints 20
Cycles
- GETList cycles
/api/rns/pub/cycles?beginDate=string&endDate=string&subscriptionId=string&customerEmail=string&status=string&page=1&size=15List cycles filtering by some arguments. - GETGet cycle details
/api/rns/pub/cycles/:cycleIdRetrieve a specific cycle by its ID. - POSTRetry cycle
/api/rns/pub/cycles/:cycleId/retryEvery subscription order has an execution count called cycle, which determines the position of an order counting from when the shopper subscribed. This…
Plans
- GETList plans
/api/rns/pvt/plans?periodicity=string&interval=string&page=1&size=15List plans filtering by some arguments. - GETGet plan details
/api/rns/pvt/plans/:idThis endpoint retrieves a specific plan by its ID.
Reports
- GETList report templates
/api/rns/pvt/reportsList all report templates available. - POSTGenerate report
/api/rns/pvt/reports/:reportName/documents?email=receiver@email.com&beginDate=2022-09-01&endDate=2022-10-01This endpoint creates a new report in the format of a CSV file and sends it via email. You can generate one of the following reports: subscriptionsWithStatus… - GETGet report document details
/api/rns/pvt/reports/:reportName/documents/:documentIdRetrieve a specific report document by its Id.
Subscriptions
- GETList subscriptions
/api/rns/pub/subscriptions?customerEmail=string&status=string&addressId=string&paymentId=string&planId=string&nextPurchaseDate=string&originalOrderId=string&page=1&size=15List subscriptions filtering by some arguments. - POSTCreate subscription
/api/rns/pub/subscriptionsCreate a new subscription. - POSTCalculate the current prices for the provided subscription template
/api/rns/pub/subscriptions/simulateSimulates an order made by subscriptions on checkout and retrieves the current price for items and shipping. - GETGet subscription details
/api/rns/pub/subscriptions/:idRetrieve a specific subscription by its ID. - PATCHUpdate subscription
/api/rns/pub/subscriptions/:idUpdate a specific subscription. - POSTAdd item to subscription
/api/rns/pub/subscriptions/:id/itemsAdd a new item to a given subscription. - DELETERemove items from a subscription.
/api/rns/pub/subscriptions/:id/items/:itemIdRemoves a specific item from a given subscription - PATCHEdit items on a subscription.
/api/rns/pub/subscriptions/:id/items/:itemIdEdit a given item on a specific subscription - POSTCalculate the current prices for a specific subscription
/api/rns/pub/subscriptions/:id/simulateSimulates an order made by the specific subscription on checkout and retrieves the current price for items and shipping. - GETGet conversation messages
/api/rns/pub/subscriptions/:subscriptionId/conversation-messageRetrieve all conversation messages sent to a customer regarding a given subscription.
Settings
- GETGet Subscription Settings
/api/rns/settingsList the details of the settings of a given subscription. - POSTEdit Subscriptions settings
/api/rns/settingsEdits Subscriptions settings in your store.
API details
- Base URL
https://vtex.localhttps://{accountName}.{environment}.com.br- Authentication
- An API key in the X-VTEX-API-AppKey header
An API key in the X-VTEX-API-AppToken header - Operations
- 20 operations on 16 pathsGET 10POST 7PATCH 2DELETE 1
- Main resources
- Subscriptions 10Cycles 3Reports 3Plans 2Settings 2
- Response formats
application/jsontext/jsontext/plain- Description format
- OpenAPI 3.0.0, API version
1.0 - Links
- OpenAPI document
- Listed from
- APIs.guru OpenAPI Directory (CC0-1.0)
Source updated
How to test the Subscriptions API (v3) in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Subscriptions API (v3) collection, without the publisher's secrets.
- Add your credentialsThis API uses an API key in the X-VTEX-API-AppKey header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “List cycles” (GET /api/rns/pub/cycles?beginDate=string&endDate=string&subscriptionId=string&customerEmail=string&status=string&page=1&size=15), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Subscriptions API (v3)?
A Subscription is a list of items (SKUs) tied to certain recurring purchase settings: User profile Address Payment method Frequency Cycle Once you have… It is listed under Other and has 20 endpoints.
Who publishes the Subscriptions API (v3)?
It is listed from VTEX's public API description (an OpenAPI document), not published by VTEX on Swastik Codes. Anyone who controls vtex.com can claim the profile by adding a DNS TXT record.
What is the base URL of the Subscriptions API (v3)?
Its description lists 2 base URLs: https://vtex.local, https://{accountName}.{environment}.com.br. The first is the usual one; the others are typically sandbox or regional servers.
How do I authenticate with the Subscriptions API (v3)?
It accepts 2 methods: an API key in the X-VTEX-API-AppKey header; an API key in the X-VTEX-API-AppToken header.
How many endpoints does the Subscriptions API (v3) have?
20 operations on 16 paths (10 GET, 7 POST, 2 PATCH, 1 DELETE). The largest groups are Subscriptions, Cycles, Reports, Plans.
Is forking the Subscriptions API (v3) free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.