Collapse Menu
Docs Home
Extensibility Options
Contact Support

/products

Overview

Use the /products endpoint to create or update products.

See also:

Use the /products endpoint

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

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"
            }
        }
    ]
}

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.