/products
Overview
Use the /products endpoint to create or update products.
See also:
Use the /products endpoint
- 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",
"taxcode": "DC020502",
"taxcodeDescription": "Computer Software - non-educational - prewritten/canned - electronically downloaded",
"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
Obtain current product price data in all currencies supported by your Store using a GET call with the /price parameter and optional additional parameters. 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 product 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. It may be useful to request pricing in a specific country (inclusive of VAT or GST) for a specific currency.
- FastSpring updates its currency exchange rates four times per day. Call GET /products/price more often than once per day to obtain the latest localized pricing.
Request Parameters
country- ISO 2-character country code
- Retrieve product pricing for a specific country, including applicable VAT or GST
- 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 Product 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
When creating products in bulk via the API, we recommend that you create no more than 300 at a time to avoid time out errors.
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",
"taxcode": "DC020502",
// 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 percentage 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"
"taxcode": "DC020502",
"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 percentage 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
Use the DELETE method to delete one or more existing products or product variations.
- Product deletion is permanent and cannot be reversed.
- 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"
}
}
]
}