/products

Last modified March 22, 2017

Products

Use this endpoint to create or update products.  Read more about Products, Bundles and Subscriptions.

Get one or multiple products

GET /products/{id1}[,{id2},{id3},...]

Get products by id response
{
	"products": [
		{
			"product": "nest",                                                       // product path
			"parent": null,                                                          // path of the main product if this item is a product variation
			"display": {
				"en": "Nest"
			},
			"description": {
				"summary": {
					"en": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor."
				},
				"action": {
					"en": "Buy Now"
				},
				"full": {
					"en": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque vel mi quam."
				}
			},
			"image": "https://d8y8nchqlnmka.cloudfront.net/VTetZH1kQD8/r7kju5MHTRQ/nest-box.png",
			"sku": "furious14",
			"fulfillments": {
				"instructions": {                                                    // Post-Order Instructions for the product
					"en": "Thank you for purchasing **_Nest_**!"
				},
				"nest_file_0": {
					"fulfillment": "nest_file_0",
					"name": "File Download (Net Fulfillment File.pdf)",
					"applicability": "NON_REBILL_ONLY",
					"display": null,
					"url": null,
					"size": null,
					"behavior": "PREFER_EXPLICIT",                                   // or CURRENT, or REQUIRE_EXPLICIT
					"previous": []
				},
				"nest_license_0": {
					"fulfillment": "nest_license_0",
					"name": "License Generator (Pre-defined List)",
					"applicability": "NON_REBILL_ONLY"
				}
			},
			"format": "digital",
			"pricing": {
				"quantityBehavior": "allow",
				"quantityDefault": 1,
				"price": {
					"USD": 4.95
				},
				"quantityDiscounts": {
					"1": 15
				},
				"dateLimitsEnabled": true,
				"dateLimits": {
					"start": "2017-03-01",                                           // discount begin date
					"end": "2017-03-31"                                              // discount end date
				},
				"discountReason": {
					"en": "Summer Sale"
				}
			},
			"action": "products.get",
			"result": "success"
		}
	]
}
Possible Error Response Example
{
	"products": [
		{
			"action": "products.get",
			"product": "nestz",
			"result": "error",
			"error": {
				"product": "Product not found"
			}
		}
	]
}

Get the list of all product ids

GET /products
Get all products
{
  "action": "products.getall",
  "result": "success",
  "products": [
    "product-1",
    "product-2",
    ...
  ]
}

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 "-"
      "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.
        },
        "instructions":{ 
          "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
        },
        "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.
        },
        "instructions":{ 
          "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
        },
        "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"
      }
    }
  ]
}