/products
Overview
This article provides information about products.Use this endpoint to create or update products.
This article provides information about the /products endpoint of the FastSpring API.
Use this endpoint to create or update products. For more information about products, bundles, and subscriptions, see our article here.
- Get One or Multiple Products
- Get the List of All Product IDs
- Get Localized Product Price Data
- Create One or More New Products
- Update One or More Existing Products
- Delete One or More Existing Products
Get One or Multiple Products
GET /products/{id1}[,{id2},{id3},...]
Get Products by ID Response
{
"products": [
{
"product": "example-subscription-monthly", // product path
"parent": null, // path of the main product if this item is a product variation
"display": {
"en": "Example Subscription - Monthly"
},
"description": {
"summary": {
"en": "**Summary** description for Example Subscription Monthly"
},
"action": {
"en": "Buy Now"
},
"full": {
"en": "**Long Description** for Example Subscription Monthly"
}
},
"image": "https://d8y8nchqlnmka.cloudfront.net/p31bZYrcQUs/3h6HJXH4Qbk/example-subscription-monthly.png"",
"sku": "SKU1234",
"offers": [ // the product's cross-sell and upsell offers (if any) are listed here
{
"type": "cross-sell", // type of offer (or "upsell")
"display": { // optional heading for the offer
"en": "Customers Also Purchased..."
},
"items": [ // products offered
"example-product-1"
]
}
],
"fulfillments": {
"instructions": { // Post-Order Instructions for the product
"en": "Thank you for subscribing to _Example Subscription Monthly_. Please download the file using the button or link found on this page.\n\nOnce you have installed the product, go to **Help** | **About** | **Register**, and enter the license key shown above. Then, click **ACTIVATE** to complete your registration."
},
"example-subscription-monthly_file_0": {
"fulfillment": "example-subscription-monthly_file_0",
"name": "File Download (Example.pdf)",
"applicability": "NON_REBILL_ONLY",
"display": null,
"url": null,
"size": null,
"behavior": "PREFER_EXPLICIT", // or CURRENT, or REQUIRE_EXPLICIT
"previous": []
},
"example-subscription-monthly_license_0": {
"fulfillment": "example-subscription-monthly_license_0",
"name": "License Generator (Pre-defined List)",
"applicability": "NON_REBILL_ONLY"
}
},
"format": "digital",
"pricing": {
"interval": "month",
"intervalLength": 1,
"intervalCount": null,
"quantityBehavior": "allow",
"quantityDefault": 1,
"price": {
"USD": 30.0
},
"dateLimitsEnabled": false, // true if price includes a discount
"setupFee": { // optional one-time setup fee for subscription products
"price": {
"USD": 14.95
},
"title": {} // optional description of the one-time setup fee
},
"reminderNotification": {
"enabled": true,
"interval": "week",
"intervalLength": 1
},
"overdueNotification": {
"enabled": true,
"interval": "week",
"intervalLength": 1,
"amount": 4
},
"cancellation": {
"interval": "week",
"intervalLength": 1
}
},
"action": "products.get",
"result": "success"
}
]
}
Possible Error Response Example
{
"products": [
{
"action": "products.get",
"product": "nestz",
"result": "error",
"error": {
"product": "Product not found"
}
}
]
}
Get List of All Product IDs
GET /products
Get All Products Response
{
"action": "products.getall",
"result": "success",
"products": [
"product-1",
"product-2",
...
]
}
Get Localized Product Price Data
You can obtain current product price data in all currencies supported by your Store using a GET call with the /price parameter and optional additional parameters. You can also retrieve current product price data for one more specified countries in this way.
- If you do not pass optional parameters, the API responds with all products' prices for each country in each country's default currency.
- The prices returned via the API response include VAT/GST, where applicable.
- If a country's default currency is disabled for your Store, customers in that location see prices in your base currency instead. Therefore, it may be useful to request pricing in a specific country (inclusive of VAT or GST) for a specific currency.
Tip
FastSpring updates its currency exchange rates four times per day. You may want to call GET /products/price more often than once per day to obtain the latest localized pricing.
Request Parameters
| Paramter | Values | Description |
|---|---|---|
| country | ISO 2-character country code | Retrieve product pricing for a specific country, including applicable VAT or GST |
| currency | ISO 3-character currency code | In conjunction with country, retrieve product pricing in a specific currency, regardless of the country's default currency |
Get Price Examples
Get All Products' Prices
GET /products/price
Response Example
{
"page": 1,
"limit": 50,
"nextPage": 2,
"products": [
{
"action": "product.price.getall",
"result": "success",
"product": "example-product-1",
"pricing": {
"PR": {
"currency": "USD",
"price": 3.95,
"display": "$3.95"
},
"PS": {
"currency": "USD",
"price": 3.95,
"display": "$3.95"
},
"PT": {
"currency": "EUR",
"price": 4.54,
"display": "4,54 €"
},
...
}
},
{
"action": "product.price.getall",
"result": "success",
"product": "example-product-2",
"pricing": {
"PR": {
"currency": "USD",
"price": 9.95,
"display": "$9.95"
},
"PS": {
"currency": "USD",
"price": 9.95,
"display": "$9.95"
},
"PT": {
"currency": "EUR",
"price": 11.44,
"display": "11,44 €"
},
...
}
},
...
]
}
Get All Products' Prices in a Specified Country
GET /products/price?country={countryCode}
Response Example
{
"page": 1,
"limit": 50,
"nextPage": 2,
"products": [
{
"action": "product.price.getall",
"result": "success",
"product": "example-product-1",
"pricing": {
"DE": {
"currency": "EUR",
"price": 4.39,
"display": "4,39 €"
}
}
},
{
"action": "product.price.getall",
"result": "success",
"product": "example-product-2",
"pricing": {
"DE": {
"currency": "EUR",
"price": 100.0,
"display": "100,00 €"
}
}
},
...
]
}
Get All Products' Prices in a Specified Country and Currency
GET /products/price?country={countryCode}&cy={currencyCode}
Response Example
{
"page": 1,
"limit": 50,
"nextPage": 2,
"products": [
{
"action": "product.price.getall",
"result": "success",
"product": "example-product-1",
"pricing": {
"DE": {
"currency": "USD",
"price": 4.7,
"display": "4,70 $"
}
}
},
{
"action": "product.price.getall",
"result": "success",
"product": "example-product-2",
"pricing": {
"DE": {
"currency": "USD",
"price": 107.04,
"display": "107,04 $"
}
}
},
...
]
}
Get a Specific Product's Price
GET /products/price/{id1}
Response Example
{
"page": 1,
"limit": 50,
"products": [
{
"action": "product.price.get",
"result": "success",
"product": "example-product-1",
"pricing": {
"PR": {
"currency": "USD",
"price": 3.95,
"display": "$3.95"
},
"PS": {
"currency": "USD",
"price": 3.95,
"display": "$3.95"
},
"PT": {
"currency": "EUR",
"price": 4.54,
"display": "4,54 €"
},
...
}
}
]
}
Get a Specific Product's Price in a Specified Country
GET /products/price/{id1}?country={countryCode}
Response Example
{
"page": 1,
"limit": 50,
"products": [
{
"action": "product.price.get",
"result": "success",
"product": "example-product-1",
"pricing": {
"DE": {
"currency": "EUR",
"price": 4.39,
"display": "4,39 €"
}
}
}
]
}
Get a Specific Product's Price in a Specified Country and Currency
GET /products/price/{id1}?country={countryCode}&cy=
Response Example
{
"page": 1,
"limit": 50,
"products": [
{
"action": "product.price.get",
"result": "success",
"product": "example-product-1",
"pricing": {
"DE": {
"currency": "USD",
"price": 4.7,
"display": "4,70 $"
}
}
}
]
}
Create One or More New Products
POST /products
Request Example
{
"products": [
{
"product": "product-one", // Required. Must be a valid product path/ID: alphanumeric, all lower-case, no special characters except dash "-", must be greater than two characters in length
"display": { // Required at least in English
"en": "String"
},
"description": {
"summary": {
"en": "String" // This field also supports Markdown.
},
"action": {
"en": "String"
},
"full": {
"en": "String" // This field also supports Markdown.
}
},
"fulfillment": {
"instructions":{ // Optional Post Order Instructions (e.g., for a 'thank you message' and directions on how to register the product)
"en":"String", // This field also supports Markdown.
"es":"String" // This field also supports Markdown.
}
},
"fulfillments": [
{
"type":"file", // Required.
"url":"http://somedomain.net/files/8675309/filename.exe", // Required when uploading a new fulfillment file; specify external file URL for FastSpring to retrieve
"display":"filename.exe", // Required fulfillment file name; extension must match file specified in URL
"applicability":"ALWAYS", // Or "BASE", "CONFIGURATION", "REBILL_ONLY", "NON_REBILL_ONLY",
"behavior":"CURRENT" // Or "PREFER_EXPLICIT";
}
],
"image": "http://somedomain.net/images/8675309/filename.jpg", // Product icon image
"format": "digital", // Or "physical" or "digital-and-physical"
"sku": "string", // Optional SKU ID string
"attributes": { // Strings. Custom key / value attributes that will be passed back once this product is purchased (aggregate limit of approximately 4,000 characters total).
"key1": "value1",
"key2": "value2",
...
},
"pricing": {
"trial": 2, // Days, only needed if you are creating a subscription
"interval": "month", // Or "adhoc", "day", "week", "year", only needed if you are creating a subscription
"intervalLength": 1, // Required if "interval" is specified and is not "adhoc"
"quantityBehavior": "allow", // Or "lock" or "hide"
"quantityDefault": 1,
"price": {
"USD": 14.95, // Currency must be enabled in the Store Settings
"EUR": 10.99
},
"setupFee": { // Optional one-time setup fee for subscriptions; if set, this cannot be removed from the order. The amount will not be included in future rebills.
"title":{"en":"Setup fee title"}, // Optional description of the one-time setup fee, format "language code":"string"
"price":{"USD":10} // Amount of the one-time setup fee, format "currency":amount
},
"quantityDiscounts": { // "Volume Discounts". Support perentage or "amount off". Mixed values are not supported.
10: 25.00, // Quantity: percentage off. Everything more than 10 units will be discounted by 25%.
30: {"USD": 25.00, "EUR": 15} // Quantity: amount off in each supported currency. This value will be subtracted from the product price.
},
"discountReason": {
"en": "The Reason"
},
"discountDuration": 1,
"dateLimitsEnabled": true, // Pass "true" if you want to limit product discount availability by date range (for subscriptions, this only applies to the initial order).
"dateLimits": {
"start": "2020-06-05 12:00", // Beginning date for the discount availability. YYYY-MM-DD 00:00 GMT, or pass the date in milliseconds.
"end": "2020-07-04 19:33" // Expiration date for the discount. YYYY-MM-DD 00:00 GMT, or pass the date in milliseconds.
}
}
},
{
...next product definition...
}
]
}
Response Example
{
"products": [
{
"product": "product-one",
"action": "product.create",
"result": "success"
}
]
}
Examples of Possible Error Responses
{
"errors": [
{
"product": "product-id",
"error": {
"product": "product is required", // "product" is required when creating a new product
"display": "display is required", // "display" is required when creating a new product
"interval": "intervalLength must be specified", // "intervalLength" is required if "interval" is specified
"intervalLength": "interval must be specified", // "interval" is required if "intervalLength" is specified
"renew": "interval must be specified", // or "intervalLength must be specified" or "interval and intervalLength must be specified"
"trial": "interval must be specified", // or "intervalLength must be specified" or "interval and intervalLength must be specified"
"discountDuration": "interval must be specified", // or "intervalLength must be specified" or "interval and intervalLength must be specified"
"discountDuration": "quantityDiscounts must be specified",
"discountReason": "quantityDiscounts must be specified"
}
}
]
}
Update One or More Existing Products
POST /products
Specifying a product path / product ID that already exists in your Store allows you to update an existing product record via the API. By contrast, posting using a product path that does not exist will create a new product (provided all required data is included in your post).
Request Example
{
"products": [
{
"product": "product-one", // Required. Must be a valid product path/ID: alphanumeric, all lower-case, no special characters except dash "-"
"display": { // Required at least in English
"en": "String"
},
"description": {
"summary": {
"en": "String" // This field also supports Markdown.
},
"action": {
"en": "String"
},
"full": {
"en": "String" // This field also supports Markdown.
}
},
"fulfillment": {
"instructions":{ // Optional Post Order Instructions (e.g., for a 'thank you message' and directions on how to register the product)
"en":"String", // This field also supports Markdown.
"es":"String" // This field also supports Markdown.
}
},
"fulfillments": [
{
"type":"file", // Required.
"fulfillment":"product-test-hi_file_0", // Required when updating an existing fulfillment file already assigned to the existing product
"display":"test.jpg", // Fulfillment file name
"status":"ACTIVATE" // Or "DISABLED" to disable an existing file fulfillment
}
],
"image": "http://somedomain.net/images/8675309/filename.jpg", // Product icon image
"format": "digital", // Or "physical" or "digital-and-physical"
"sku": "string", // Optional SKU ID string
"attributes": { // Strings. Custom key / value attributes that will be passed back once this product is purchased (aggregate limit of approximately 4,000 characters total).
"key1": "value1",
"key2": "value2",
...
},
"pricing": {
"trial": 2, // Days, only needed if you are creating a subscription
"interval": "month", // Or "adhoc", "day", "week", "year", only needed if you are creating a subscription
"intervalLength": 1, // Required if "interval" is specified and is not "adhoc"
"quantityBehavior": "allow", // Or "lock" or "hide"
"quantityDefault": 1,
"price": {
"USD": 14.95, // Currency must be enabled in the Store Settings
"EUR": 10.99
},
"setupFee": { // Optional one-time setup fee for subscriptions; if set, this cannot be removed from the order. The amount will not be included in future rebills.
"title":{"en":"Setup fee title"}, // Optional description of the one-time setup fee, format "language code":"string"
"price":{"USD":10} // Amount of the one-time setup fee, format "currency":amount
},
"quantityDiscounts": { // "Volume Discounts". Support perentage or "amount off". Mixed values are not supported.
10: 25.00, // Quantity: percentage off. Everything more than 10 units will be discounted by 25%.
30: {"USD": 25.00, "EUR": 15} // Quantity: amount off in each supported currency. This value will be subtracted from the product price.
},
"discountReason": {
"en": "The Reason"
},
"discountDuration": 1,
"dateLimitsEnabled": true, // Pass "true" if you want to limit product discount availability by date range (for subscriptions, this only applies to the initial order).
"dateLimits": {
"start": "2020-06-05 12:00", // Beginning date for the discount availability. YYYY-MM-DD 00:00 GMT, or pass the date in milliseconds.
"end": "2020-07-04 19:33" // Expiration date for the discount. YYYY-MM-DD 00:00 GMT, or pass the date in milliseconds.
}
}
},
{
...next product definition...
}
]
}
Response Example
{
"products": [
{
"product": "product-one",
"action": "product.update",
"result": "success"
}
]
}
Examples of Possible Error Responses
{
"errors": [
{
"product": "product-id",
"error": {
"product": "product is required", // "product" is required when creating a new product
"display": "display is required", // "display" is required when creating a new product
"interval": "intervalLength must be specified", // "intervalLength" is required if "interval" is specified
"intervalLength": "interval must be specified", // "interval" is required if "intervalLength" is specified
"renew": "interval must be specified", // or "intervalLength must be specified" or "interval and intervalLength must be specified"
"trial": "interval must be specified", // or "intervalLength must be specified" or "interval and intervalLength must be specified"
"discountDuration": "interval must be specified", // or "intervalLength must be specified" or "interval and intervalLength must be specified"
"discountDuration": "quantityDiscounts must be specified",
"discountReason": "quantityDiscounts must be specified"
}
}
]
}
Delete One or More Existing Products
Using the DELETE method, you can delete one or more existing products or product variations.
Warning
Product deletion is PERMANENT and cannot be reversed. Use great care when exercising this request.
Warning
If you delete a product that has product variations, the variations are also deleted automatically.
DELETE /products/{id1},{id2},{id3}
Response Example
{
"products": [
{
"action": "products.delete",
"result": "success",
"product": "deletion-test-2"
}
]
}
Example of Possible Error Response
{
"products": [
{
"action": "products.delete",
"product": "deletion-test",
"result": "error",
"error": {
"product": "Not found"
}
}
]
}