/products

Last modified October 5, 2018

This article applies to Contextual Commerce. (Looking for Classic Commerce documentation?)

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