Collapse Menu
Docs Home
Extensibility Options
Contact Support

/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 /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

ParamterValuesDescription
countryISO 2-character country codeRetrieve product pricing for a specific country, including applicable VAT or GST
currencyISO 3-character currency codeIn 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 400,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
      }
    },
    {
      ...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 400,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
      }
    },
    {
      ...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"
      }
    }
  ]
}

Try FastSpring

Get a free account and see why FastSpring is the ecommerce partner of choice for software providers around the world. Try our full-service ecommerce solution today to unlock revenue growth for your online company.