/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},...]
{ "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" } ] }
{ "products": [ { "action": "products.get", "product": "nestz", "result": "error", "error": { "product": "Product not found" } } ] }
Get List of All Product IDs
GET /products
{ "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
{ "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}
{ "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}
{ "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}
{ "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}
{ "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=
{ "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
{ "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... } ] }
{ "products": [ { "product": "product-one", "action": "product.create", "result": "success" } ] }
{ "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).
{ "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... } ] }
{ "products": [ { "product": "product-one", "action": "product.update", "result": "success" } ] }
{ "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}
{ "products": [ { "action": "products.delete", "result": "success", "product": "deletion-test-2" } ] }
{ "products": [ { "action": "products.delete", "product": "deletion-test", "result": "error", "error": { "product": "Not found" } } ] }