About Subscription Options

Wix site owners can create subscriptions to sell their products on a recurring basis. With the Subscription Options API, you can integrate with the store owner's subscriptions in their Wix store to create, delete, get, check and query the site owner's subscriptions.

Subscription frequency and duration

Wix supports the following frequencies and durations of subscriptions:

  • Every day for X days
  • Every week for X weeks
  • Every month for X months
  • Every year for X years

Subscription Settings

  • frequency - How often the payment will be made/product will be provided as part of the subscription. Supported frequencies: daily, weekly, monthly, yearly.
  • billingCycle - Number of billing cycles before subscription ends.
  • autoRenewal - Allow for automatic renewal of a subscription at the end of its specified period. Can only be used if billingCycle is empty.

Subscription Pricing

Each subscription option has a separate price that is set through a discount on the product’s price. For example, a coffee bag can be sold for $20 as a regular one-time purchase. However, with a monthly subscription (1 coffee bag per month) for 3 months the price of the coffee bag could be $18 per bag/month, and with a longer subscription of 12 months sold for $15 per bag/month.

Current Limitations

The following list contains currently unavailable functionality:

  • Providing/delivering a product X times per week/month/year (for example, 3 times a month).
  • Suspending a subscription.
  • Skipping a cycle.
  • Applying the same subscriptions to multiple different products in bulk.
  • Extending subscriptions (adding more billing cycles to an active subscription).
  • Creating a subscription from the whole cart.
  • Coupons on X first payments of a subscription.
  • Adding a subscription to a cart. Currently the subscription goes straight to checkout, similar to using ‘buy now’.
Was this helpful?
Yes
No

Example Flows

This article shares some possible flows when using the Subscription Options API.

Creating a subscription option and assigning it to a product

Part 1: Creating a Subscription Option

For this use case we're creating an 8 week-long subscription that provides a 10% discount off the original price. Using Create Subscription Option, your request would look something like this:

Copy Code
{
"subscriptionOption": {
"title": "Weekly sub - 8 weeks",
"description": "Save 10% on weekly subscription",
"subscriptionSettings": {
"frequency": "WEEK",
"billingCycles": 8
},
"discount": {
"type": "PERCENT",
"value": 10
}
}
}

The response is the newly created subscription option with its auto-generated ID:

Copy Code
{
"subscriptionOption": {
"id": "fb5f1365-472c-4445-bee0-1d3fb0591224",
"title": "Weekly sub - 8 weeks",
"description": "Save 10% on weekly subscription",
"subscriptionSettings": {
"frequency": "WEEK",
"billingCycles": 8
},
"discount": {
"type": "PERCENT",
"value": 10
}
}
}

Part 2: Assigning the Subscription Option to a Product

Now that we've created the subscription option, we can use Assign Subscription Options To Product.

  1. Pass the productId of the designated product for assignment as a path parameter in the url:

    Copy Code
    https://www.wixapis.com/stores/v1/subscription-options/product/{productId}/assign
  2. The request will contain one or more subscription option IDs to be assigned to the product, and whether to hide the subscription option from the product (default is false - not hidden).

    Copy Code
    {
    "assignedSubscriptionOptions": [
    {
    "id": "fb5f1365-472c-4445-bee0-1d3fb0591224",
    "hidden": false
    }
    ]
    }

    The response is an empty object.

Part 3: Checking that the Subscription Option was assigned to the Product

To check that the subscription option has been assigned to the product, use the Get Subscription Options For Product endpoint.

  1. Pass the same productId as the one used in part 2. To retrieve all the subscription options assigned to the product include the path parameter includeHiddenSubscriptionOptions=true:

    Copy Code
    curl -X GET \
    'https://www.wixapis.com/stores/v1/subscription-options/byProduct/{productId}? includeHiddenSubscriptionOptions=false' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <AUTH>'

    The response is an array of the subscription options assigned to the product.

    Copy Code
    {
    "subscriptionOptions": [
    {
    "id": "475c6eff-6e2d-4a27-9b2b-ef096eacd56d",
    "hidden": false,
    "title": "Coffee of the Month",
    "description": "Subscribe and save 15%",
    "subscriptionSettings": {
    "frequency": "WEEK",
    "autoRenewal": false,
    "billingCycles": 6
    },
    "discount": {
    "type": "PERCENT",
    "value": 15
    }
    },
    {
    "id": "ab3b23a2-af20-4b63-9f30-fe7981029405",
    "hidden": false,
    "title": "Monthly for a Year",
    "description": "Annual Subscription",
    "subscriptionSettings": {
    "frequency": "MONTH",
    "autoRenewal": false,
    "billingCycles": 12
    },
    "discount": {
    "type": "PERCENT",
    "value": 20
    }
    }
    ]
    }

Allowing a Product to be Sold as a One-Time Purchase

When a subscription option is assigned to a product, by default that product will only be available for purchase as a subscription. To allow for one-time purchase in addition to a subscription, you could use a flow like this:

  1. Using Get Product One Time Purchases Status, pass the productId of the product you'd like to check as a path parameter:

    Copy Code
    curl -X GET \
    'https://www.wixapis.com/stores/v1/subscription-options/product/{productId}/oneTimePurchasesStatus' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <AUTH>'

    The response is an object that holds a field with a boolean value:

    Copy Code
    {"allowed": false}
  2. Using Allow One Time Purchases of Product, pass the productId as a path parameter, and "allowed": true in the body

    Copy Code
    curl -X PATCH \
    'https://www.wixapis.com/stores/v1/subscription-options/product/{productId}/allowOneTimePurchase' \
    --data-binary '{
    "allowed": true
    }'\
    -H 'Content-Type: application/json' \
    -H 'Authorization: <AUTH>'

    The response is an empty object.

Was this helpful?
Yes
No

Subscription Option Object

Attributes
idstringformat GUID
Subscription option ID (auto-generated upon subscription option creation).

titlestringminLength 1maxLength 20
Subscription option title.

descriptionstringmaxLength 60
Subscription option description (optional).

subscriptionSettingsobject
Subscription charge times. For example, if frequency: MONTH and billingCycles: 6; payment will be made monthly for 6 months.

discountobject
Discount info (optional). For example, a $20 discount would be value: 20, type: AMOUNT.
Was this helpful?
Yes
No

PostCreate Subscription Option

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Creates a subscription option. To assign to a product, call Assign Subscription Options to Product. Subscription options that are not assigned to a product will not be visible in the Wix business manager.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

POST
https://www.wixapis.com/stores/v1/subscription-options

Was this helpful?
Yes
No

PatchBulk Update Subscription Options

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Updates multiple subscription options. Only parameters passed will be updated.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

PATCH
https://www.wixapis.com/stores/v1/subscription-options

Was this helpful?
Yes
No

PatchUpdate Subscription Option

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Updates a subscription option. Only parameters passed will be updated.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

PATCH
https://www.wixapis.com/stores/v1/subscription-options/{subscriptionOption.id}

Was this helpful?
Yes
No

DeleteDelete Subscription Option

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Deletes a subscription option.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

DELETE
https://www.wixapis.com/stores/v1/subscription-options/{id}

Was this helpful?
Yes
No

PostBulk Create Subscription Options

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Creates multiple subscription options (up to 100). To assign to a product, call Assign Subscription Options to Product. Subscription options that are not assigned to a product will not be visible in the Wix business manager.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

POST
https://www.wixapis.com/stores/v1/subscription-options/createBulk

Was this helpful?
Yes
No

PostBulk Delete Subscription Options

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Deletes multiple subscription options.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

POST
https://www.wixapis.com/stores/v1/subscription-options/deleteBulk

Was this helpful?
Yes
No

PostAssign Subscription Options To Product

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Assign up to 6 subscription options to a specified product. Pass an empty array to remove all subscription options assigned to a product.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

POST
https://www.wixapis.com/stores/v1/subscription-options/product/{productId}/assign

Was this helpful?
Yes
No

PatchAllow One Time Purchases Of Product

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Allow for one-time purchase of a product. By default, product can be sold only as part of a subscription, not as a one-time purchase.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

PATCH
https://www.wixapis.com/stores/v1/subscription-options/product/{productId}/allowOneTimePurchase

Was this helpful?
Yes
No

GetGet Subscription Option

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves a subscription option by ID.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Read Products
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Was this helpful?
Yes
No

GetGet Subscription Options For Product

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves all subscription options assigned to a specified product. By default, hidden subscription options are not returned. To retrieve all subscription options you must pass includeHiddenSubscriptionOptions = true.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Read Products
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Was this helpful?
Yes
No

PostList Subscription Options

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Returns the specified subscription options. If the specified subscription option doesn't exist, the request will be successful but the response will be empty.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Read Products
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Was this helpful?
Yes
No

GetGet Product Ids For Subscription Option

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves the IDs of products associated with a specified subscription option.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Read Products
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Was this helpful?
Yes
No

GetGet Product One Time Purchases Status

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Checks whether a specified product (associated with subscription options) is available for one-time purchase.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Read Products
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Was this helpful?
Yes
No

Subscription Option Created

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a subscription option is created.

Permissions

WIX_STORES.READ_SUBSCRIPTION_OPTIONS
Learn more about permissions.

Event Body

Event Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.stores.v1.subscription_option.

slugstring
Event name. Expected created.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

createdEventobject
Event information.
Was this helpful?
Yes
No

Subscription Option Updated

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a subscription option is changed.

Permissions

WIX_STORES.READ_SUBSCRIPTION_OPTIONS
Learn more about permissions.

Event Body

Event Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.stores.v1.subscription_option.

slugstring
Event name. Expected updated.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

updatedEventobject
Event information.
Was this helpful?
Yes
No

Subscription Option Deleted

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a subscription option is deleted.

Permissions

WIX_STORES.READ_SUBSCRIPTION_OPTIONS
Learn more about permissions.

Event Body

Event Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.stores.v1.subscription_option.

slugstring
Event name. Expected deleted.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

deletedEventstruct
Event information.
Was this helpful?
Yes
No

Option Subscription Options Assignment Changed For Product

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when subscription options are assigned or unassigned to a product, or the subscription option's visibility in a product is changed.

Permissions

WIX_STORES.READ_SUBSCRIPTION_OPTIONS
Learn more about permissions.

Event Body

Event Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
productIdstring
Product ID.

assignedSubscriptionOptionsArray <SubscriptionOptionWithVisibility>maxItems 6
Subscription options assigned to the product.
Was this helpful?
Yes
No

One Time Purchases Changed

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a product's one-time purchase setting is changed.

Permissions

WIX_STORES.READ_SUBSCRIPTION_OPTIONS
Learn more about permissions.

Event Body

Event Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
productIdstring
Product ID.

allowedboolean
Whether the product is available for one-time purchase.
Was this helpful?
Yes
No