Enabling Manual Prices for Subscriptions v3

The option of setting manual prices is only available for Subscriptions v3. If you are using a previous version of the Subscriptions system, check out the Subscriptions v3 migration guide.

Subscriptions is an app developed by VTEX to facilitate recurring sales in your store. It works as an automatic scheduler, executing a repurchase at the frequency requested by the customer. Check out our article How subscriptions work to know more.

When using subscriptions, stores might need to configure prices manually for each item. Considering that product prices can change over time, maintaining the same commercial rules for subscription orders can be a good strategy to retain clients over a longer period.

By enabling the Manual Price feature for Subscriptions v3, you can:

  • Apply a manual price on each subscription item instead of the current price applied.
  • Maintain the same manual price for every future recurrent order from that subscription, if desired.

Before you start

To enable Manual Prices for Subscriptions v3, it is first necessary to enable it in the Checkout settings. This means you must make a request to the post Update orderForm configuration endpoint, setting allowManualPrices to true, if you have not done this yet.

Setting Manual Prices for Subscriptions generally follows the same rules as applying manual prices to items in regular orders at Checkout. Still, it requires additional configurations and actions detailed in the following sections.

To apply manual prices, users must have at least one of the following roles or License Manager resources:

  • Owner (Admin Super) role
  • Call Center Operator (Telesales) role
  • Shopping Cart Full Access resource

Configuration

To enable Manual Prices for Subscriptions, you must follow the steps below:

  1. Make a request using the get Get Subscription Settings endpoint to retrieve the current settings related to Subscriptions in your store.
  2. Make a request using the post Edit Subscription Settings endpoint, setting the following properties to true:
Property nameTypeDescription
manualPriceAllowedbooleanThis property enables the manual price configuration in subscription items when set to true. This is valid for all existing subscriptions, provided that there is a manual price configured.
useItemPriceFromOriginalOrderbooleanThis property enables using the price manually set for each item from the original subscription order when set to true. This is only valid for new subscriptions created after enabling this configuration. The manualPriceAllowed property must also be set to true; otherwise, this configuration will not work.

Request body example

{
    "slaOption": "NONE",
    "defaultSla": null,
    "isUsingV3": true,
    "onMigrationProcess": false,
    "executionHourInUtc": 9,
    "workflowVersion": "1.1",
    "deliveryChannels": [
        "delivery"
    ],
    "randomIdGeneration": false,
    "isMultipleInstallmentsEnabledOnCreation": false,
    "isMultipleInstallmentsEnabledOnUpdate": false,
    "orderCustomDataAppId": null,
    "postponeExpiration": false,
    "manualPriceAllowed": true,
    "useItemPriceFromOriginalOrder": true
}

Setting a manual price in a subscription item

To apply a manual price to a subscription item, you must insert a new value into the manualPrice property:

Property nameTypeDescription
manualPriceint32The manual price you want to use for the subscription item. The value follows the same format as in Checkout, which means you must send it without decimal separators. Examples: If the desired value is 29.90, you must write 2990. In case the value is 0.90, you must write 90.

You can manually modify the price when:

Read the following sections for details on the endpoints you must use and their request body examples.

🚧

You can only apply a manual price to a subscription item if the manualPriceAllowed configuration is set to true, as described in the Configuration section.

Adding an item to a subscription

When making a post Add item to subscription request, you can apply a manual price by informing a new value in the manualPrice property in the request body.

Request body example

{
  "skuId": "12",
  "quantity": 5,
  "manualPrice": 40
}

Editing an item in a subscription

To apply a manual price when making a patch Edit item on subscription request, you must inform the desired value in the manualPrice property in the request body.

Keep in mind that all the other editable properties — status, isSkipped, and quantity — remain with the same behavior and can be set in the same request to edit the subscription item as the manualPrice.

Request body example

{
  "quantity": 5,
  "manualPrice": 500
}

Removing a manual price in a subscription item

To remove a manual price, you must set the manualPrice value to null when making a patch Edit item on subscription request.

Request body example

{
  "manualPrice": null
}

Another option is to completely remove the item from the subscription, making a request to the delete Remove item from subscription endpoint.


Did this page help you?