API
GuidesWhat’s newGet API token
Core Resources

Products

Custom
Representation of the Products from your catalog in Recharge.

20 additions in V2, marked New

Everything marked New also works when you send X-Recharge-Version: 2021-11.

How Products relate to other resources
Endpoints

#The product object

Attributes

  • descriptionstring · nullableNew
    The description of the product.
  • external_product_idstring
    Unique numeric identifier of the product record in Recharge. The primary id of the record.
  • brandstring
    The brand name of the product.
  • external_created_atdatetime
    The date and time at which the product was created in an external product catalog.
  • external_updated_atdatetime
    The date and time at which the product was updated in an external product catalog.
  • imagesarray of objects
    An array of urls for various sizes of image files.
    Show child attributesHide child attributes5
    • largestring
      The url where a large image file is located.
    • mediumstring
      The url where a medium image file is located.
    • smallstring
      The url where a small image file is located.
    • originalstring
      The url of the original sized product image.
    • sort_orderinteger
      The sort order in which the x image from the array should appear when displayed.
  • optionsarray of objects
    An array of options for the product record, such as size, color, etc.
    Show child attributesHide child attributes3
    • namestring
      The name of the option, such as size, color, etc.
    • positioninteger
      The position in which the x option from the array should appear when displayed.
    • valuesarray of objects
      An array of values for the x option in the options array.
      Show child attributesHide child attributes2
      • labelstring
        The label of the option value. For example, if the option name is size, this value may be small, medium, large, etc.
      • positioninteger
        The position in which the y option value from the array should appear when displayed.
  • published_atdatetime
    The datetime at which the product became available for purchase. To make the product available, this should be set in the past.
  • requires_shippingboolean
    Indicator of shipping requirement.
    Dictates the default for the variants. Can be overriden at the variant level.
  • titlestring
    The title of the product.
  • variantsarray of objects
    An array of variants of the product.
    If your PIM does not use variants, create a single variant product.
    Show child attributesHide child attributes105 new
    • dimensionsobject
      A container of variant dimensions.
      Show child attributesHide child attributes2
      • weightfloat
        The weight of the product in the weight unit configured for your store.
      • weight_unitstring
        Read only. The weight unit specified for your store.
    • external_variant_idstring
      The variant id in your PIM. The primary key for the variant.
    • imageobject
      An object containing image urls for the variant.
      small is the default picture shown on the checkout. If small is not present we render original. Please note for better rendering we advise you populate small
      Show child attributesHide child attributes4
      • largestring
        The url where a large image file is located.
      • mediumstring
        The url where a medium image file is located.
      • smallstring
        The url where a small image file is located.
      • originalstring
        The url of the original sized product image.
    • option_valuesarray of objects
      An array of option values, linking the variant to the options listed at the product level.
      Show child attributesHide child attributes1
      • labelstring
        The label of the option value. Maps to a value specified in the product options list
    • pricesobject
      An object containing prices for the variant.
      Show child attributesHide child attributes35 new
      • compare_at_pricestring
        The compare-at price for the variant.
      • unit_pricestring
        The unit price for the variant.
      • pricesobjectNew
        An object containing the prices of the variant in other currencies.
        Only present when presentment prices have been provided for the variant.
        Show child attributesHide child attributes14 new
        • presentment_pricesobjectNew
          An object containing the price of the variant in a presentment currency. When sent, currency, unit_price_currency and discounted_price_currency are all required.
          Only present when presentment prices have been provided for the variant.
          Show child attributesHide child attributes33 new
          • currencystringNew
            The three-letter currency code of the presentment price.
            Only present when presentment prices have been provided for the variant.
          • unit_price_currencystringNew
            The unit price of the variant in the presentment currency.
            Only present when presentment prices have been provided for the variant.
          • discounted_price_currencystringNew
            The discounted price of the variant in the presentment currency.
            Only present when presentment prices have been provided for the variant.
    • requires_shippingboolean
      Indicator of shipping requirement. If true the product associated to the variant needs to be shipped.
      Default value is what is set at the Product level for requires_shipping.
    • skustring
      The stock keeping unit of the variant.
    • tax_codestring
      The tax code of the variant. This value will be used when calculating tax with a third party tax service.
    • taxableboolean
      A boolean indicator of the variant’s taxability.
    • titlestring
      The title of the variant.
  • vendorstring
    The vendor of the product.
The product object
{
  "brand": "Recharge",
  "description": "A cotton shirt with the Recharge logo",
  "external_created_at": "2021-01-01T00:00:00+00:00",
  "external_product_id": "5",
  "external_updated_at": "2021-01-01T00:00:00+00:00",
  "images": [
    {
      "small": "https:...",
      "medium": "https:...",
      "large": "https:...",
      "original": "https:...",
      "sort_order": 2
    }
  ],
  "options": [
    {
      "name": "Size",
      "position": 0,
      "values": [
        {
          "label": "small",
          "position": 0
        },
        {
          "label": "medium",
          "position": 1
        },
        {
          "label": "large",
          "position": 2
        }
      ]
    }
  ],
  "published_at": "2021-01-01:00:00+00:00",
  "requires_shipping": true,
  "title": "Recharge Logo Shirt",
  "variants": [
    {
      "external_variant_id": " 9",
      "dimensions": {
        "weight": 1234.5
      },
      "image": {
        "small": "https:....jpeg",
        "medium": "https:....jpeg",
        "large": "https:....jpeg",
        "original": "https:....jpeg"
      },
      "option_values": [
        {
          "label": "small"
        }
      ],
      "requires_shipping": true,
      "sku": "CLO123",
      "title": "Recharge Logo Shirt - Small",
      "taxable": true,
      "tax_code": "CLOTHING",
      "prices": {
        "compare_at_price": "14.22",
        "unit_price": "12.22"
      }
    }
  ],
  "vendor": "Recharge Apparel Store"
}

#Create a product

POST/products
Custom
Create a new product in your Recharge Product Catalog. After adding the record, subscription preferences may be added using the Products page of Recharge Admin Portal or with the Plans resource.
Scopewrite_products
Only available to stores on a custom (headless) platform; stores on other platforms receive a 422 error. variants must contain at least one variant, and every option value label must be used by at least one variant.

Body parameters

  • descriptionstring · nullableNew
    The description of the product.
  • external_product_idstringRequired
    Unique numeric identifier of the product record in Recharge. The primary id of the record.
  • brandstring
    The brand name of the product.
  • imagesarray of objects
    An array of urls for various sizes of image files.
    small is the default picture shown on the checkout. If small is not present we render original. Please note for better rendering we advise you populate small.
    Show child attributesHide child attributes5
    • largestring
      The url where a large image file is located.
    • mediumstring
      The url where a medium image file is located.
    • smallstring
      The url where a small image file is located.
    • originalstring
      The url of the original sized product image.
    • sort_orderinteger
      The sort order in which the x image from the array should appear when displayed.
  • optionsarray of objectsRequired
    An array of options for the product record, such as size, color, etc.
    Show child attributesHide child attributes3
    • namestringRequired
      The name of the option, such as size, color, etc.
    • positionintegerRequired
      The position in which the x option from the array should appear when displayed.
    • valuesarray of objectsRequired
      An array of values for the x option in the options array.
      Show child attributesHide child attributes2
      • labelstringRequired
        The label of the option value. For example, if the option name is size, this value may be small, medium, large, etc.
      • positionintegerRequired
        The position in which the y option value from the array should appear when displayed.
  • published_atdatetime
    The date and time at which the product became available for purchase. To make the product available, this should be set in the past.
  • requires_shippingboolean
    Indicator of shipping requirement. If true the product associated to the variant needs to be shipped.
    This is usually false for digital goods.
  • titlestringRequired
    The title of the product.
  • variantsarray of objectsRequired
    An array of variants of the product.
    If your PIM does not use variants, create a single variant product.
    Show child attributesHide child attributes105 new
    • dimensionsobjectRequired
      A container of variant dimensions.
      Show child attributesHide child attributes1
      • weightfloatRequired
        The weight of the product in the weight unit configured for your store.
    • external_variant_idstringRequired
      The variant id in your PIM. The primary key for the variant.
    • imageobject
      An object containing image urls for the variant.
      small is the default picture shown on the checkout. If small is not present we render original. Please note for better rendering we advise you populate small
      Show child attributesHide child attributes4
      • largestring
        The url where a large image file is located.
      • mediumstring
        The url where a medium image file is located.
      • smallstring
        The url where a small image file is located.
      • originalstring
        The url of the original sized product image.
    • option_valuesarray of objectsRequired
      An array of option values, linking the variant to the options listed at the product level.
      Show child attributesHide child attributes1
      • labelstringRequired
        The label of the option value. Maps to a value specified in the product options list
    • pricesobjectRequired
      An object containing prices for the variant.
      Show child attributesHide child attributes35 new
      • compare_at_pricestring
        The compare-at price for the variant.
      • unit_pricestringRequired
        The unit price for the variant.
      • pricesobjectNew
        An object containing the prices of the variant in other currencies.
        Show child attributesHide child attributes14 new
        • presentment_pricesobjectNew
          An object containing the price of the variant in a presentment currency. When sent, currency, unit_price_currency and discounted_price_currency are all required.
          Show child attributesHide child attributes33 new
    • requires_shippingboolean
      Indicator of shipping requirement. If true the product associated to the variant needs to be shipped.
      Default value is what is set at the Product level for requires_shipping.
    • skustring
      The stock keeping unit of the variant.
    • tax_codestring
      The tax code of the variant. This value will be used when calculating tax with a third party tax service.
    • taxablebooleanRequired
      A boolean indicator of the variant’s taxability.
    • titlestring
      The title of the variant.
  • vendorstringRequired
    The vendor of the product.
POST/products
curl -X POST 'https://api.rechargeapps.com/products' \
  -H 'X-Recharge-Version: v2' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "external_product_id": "10",
  "brand": "Recharge",
  "description": "A cotton shirt with the Recharge logo",
  "images": [
    {
      "small": "https:...",
      "medium": "https:...",
      "large": "https:...",
      "original": "https:...",
      "sort_order": 2
    }
  ],
  "options": [
    {
      "name": "Size",
      "position": 0,
      "values": [
        {
          "label": "small",
          "position": 0
        },
        {
          "label": "medium",
          "position": 1
        },
        {
          "label": "large",
          "position": 2
        }
      ]
    }
  ],
  "published_at": "2021-01-01:00:00+00:00",
  "requires_shipping": true,
  "title": "Recharge Logo Shirt",
  "variants": [
    {
      "external_variant_id": "9",
      "dimensions": {
        "weight": 1234.5
      },
      "image": {
        "small": "https:...",
        "medium": "https:...",
        "large": "https:...",
        "original": "https:..."
      },
      "option_values": [
        {
          "label": "small"
        }
      ],
      "sku": "CLO123",
      "title": "Recharge Logo Shirt - Small",
      "taxable": true,
      "tax_code": "CLOTHING",
      "prices": {
        "compare_at_price": "14.22",
        "unit_price": "12.22"
      }
    }
  ],
  "vendor": "Recharge Apparel Store"
}'
Response
{
  "product": {
    "brand": "Recharge",
    "description": "A cotton shirt with the Recharge logo",
    "external_created_at": "2021-01-01T00:00:00+00:00",
    "external_product_id": "10",
    "external_updated_at": "2021-01-01T00:00:00+00:00",
    "images": [
      {
        "large": "https:...",
        "medium": "https:...",
        "original": "https:...",
        "small": "https:...",
        "sort_order": 2
      }
    ],
    "options": [
      {
        "name": "Size",
        "position": 0,
        "values": [
          {
            "label": "small",
            "position": 0
          },
          {
            "label": "medium",
            "position": 1
          },
          {
            "label": "large",
            "position": 2
          }
        ]
      }
    ],
    "published_at": "2021-01-01T00:00:00+00:00",
    "requires_shipping": true,
    "title": "Recharge Logo Shirt",
    "variants": [
      {
        "dimensions": {
          "weight": 1234.5,
          "weight_unit": "lb"
        },
        "external_variant_id": "9",
        "image": {
          "large": "https:...",
          "medium": "https:...",
          "original": "https:...",
          "small": "https:..."
        },
        "option_values": [
          {
            "label": "small"
          }
        ],
        "prices": {
          "compare_at_price": "14.22",
          "unit_price": "12.22"
        },
        "sku": "CLO123",
        "tax_code": "CLOTHING",
        "taxable": true,
        "title": "Recharge Logo Shirt - Small",
        "requires_shipping": true
      }
    ],
    "vendor": "Recharge Apparel Store"
  }
}

#Retrieve a product

GET/products/{external_product_id}
Custom
Retrieves a Product from store’s product catalog using the external_product_id as lookup id.
Scoperead_products
Only available to stores on a custom (headless) platform; stores on other platforms receive a 422 error.
GET/products/{external_product_id}
curl 'https://api.rechargeapps.com/products/10' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'
Response
{
  "product": {
    "brand": "Recharge",
    "description": "A cotton shirt with the Recharge logo",
    "external_created_at": "2021-01-01T00:00:00+00:00",
    "external_product_id": "10",
    "external_updated_at": "2021-01-01T00:00:00+00:00",
    "images": [
      {
        "large": "https:...",
        "medium": "https:...",
        "original": "https:...",
        "small": "https:...",
        "sort_order": 2
      }
    ],
    "options": [
      {
        "name": "Size",
        "position": 0,
        "values": [
          {
            "label": "small",
            "position": 0
          },
          {
            "label": "medium",
            "position": 1
          },
          {
            "label": "large",
            "position": 2
          }
        ]
      }
    ],
    "published_at": "2021-01-01T00:00:00+00:00",
    "requires_shipping": true,
    "title": "Recharge Logo Shirt",
    "variants": [
      {
        "dimensions": {
          "weight": 1234.5,
          "weight_unit": "lb"
        },
        "external_variant_id": "9",
        "image": {
          "large": "https:...",
          "medium": "https:...",
          "original": "https:...",
          "small": "https:..."
        },
        "option_values": [
          {
            "label": "small"
          }
        ],
        "prices": {
          "compare_at_price": "14.22",
          "unit_price": "12.22"
        },
        "sku": "CLO123",
        "tax_code": "CLOTHING",
        "taxable": true,
        "title": "Recharge Logo Shirt - Small",
        "requires_shipping": true
      }
    ],
    "vendor": "Recharge Apparel Store"
  }
}

#Update a product

PUT/products/{external_product_id}
Custom
Update an existing product.
Scopewrite_products
Only available to stores on a custom (headless) platform; stores on other platforms receive a 422 error. The fields listed as required only apply when their parent (options or variants) is sent. An empty body returns a 422 error.

Body parameters

  • brandstring
    The brand name of the product.
  • descriptionstring · nullableNew
    The description of the product.
  • imagesarray of objects
    An array of urls for various sizes of image files.
    Show child attributesHide child attributes5
    • largestring
      The url where a large image file is located.
    • mediumstring
      The url where a medium image file is located.
    • smallstring
      The url where a small image file is located.
    • originalstring
      The url of the original sized product image.
    • sort_orderinteger
      The sort order in which the x image from the array should appear when displayed.
  • optionsarray of objects
    An array of options for the product record, such as size, color, etc.
    Show child attributesHide child attributes3
    • namestringRequired
      The name of the option, such as size, color, etc.
    • positionintegerRequired
      The position in which the x option from the array should appear when displayed.
    • valuesarray of objectsRequired
      An array of values for the x option in the options array.
      Show child attributesHide child attributes2
      • labelstringRequired
        The label of the option value. For example, if the option name is size, this value may be small, medium, large, etc.
      • positionintegerRequired
        The position in which the y option value from the array should appear when displayed.
  • published_atdatetime
    The datetime at which the product became available for purchase. To make the product available, this should be set in the past.
  • requires_shippingboolean
    Indicator of shipping requirement. If true the product associated to the variant needs to be shipped.
    This is usually false for digital goods.
  • titlestring
    The title of the product.
  • variantsarray of objects
    An array of variants of the product.
    If your PIM does not use variants, create a single variant product.
    Show child attributesHide child attributes105 new
    • dimensionsobjectRequired
      A container of variant dimensions.
      Show child attributesHide child attributes1
      • weightfloat
        The weight of the product in the weight unit configured for your store.
    • external_variant_idstring
      The variant id in your PIM. The primary key for the variant.
    • imageobject
      An object containing image urls for the variant.
      small is the default picture shown on the checkout. If small is not present we render original. Please note for better rendering we advise you populate small
      Show child attributesHide child attributes4
      • largestring
        The url where a large image file is located.
      • mediumstring
        The url where a medium image file is located.
      • smallstring
        The url where a small image file is located.
      • originalstring
        The url of the original sized product image.
    • option_valuesarray of objectsRequired
      An array of option values, linking the variant to the options listed at the product level.
      Show child attributesHide child attributes1
      • labelstringRequired
        The label of the option value. Maps to a value specified in the product options list
    • pricesobjectRequired
      An object containing prices for the variant.
      Show child attributesHide child attributes35 new
      • compare_at_pricestring
        The compare-at price for the variant.
      • unit_pricestringRequired
        The unit price for the variant.
      • pricesobjectNew
        An object containing the prices of the variant in other currencies.
        Show child attributesHide child attributes14 new
        • presentment_pricesobjectNew
          An object containing the price of the variant in a presentment currency. When sent, currency, unit_price_currency and discounted_price_currency are all required.
          Show child attributesHide child attributes33 new
    • requires_shippingboolean
      Indicator of shipping requirement. If true the product associated to the variant needs to be shipped.
      Default value is what is set at the Product level for requires_shipping.
    • skustring
      The stock keeping unit of the variant.
    • tax_codestring
      The tax code of the variant. This value will be used when calculating tax with a third party tax service.
    • taxablebooleanRequired
      A boolean indicator of the variant’s taxability.
    • titlestring
      The title of the variant.
  • vendorstring
    The vendor of the product.
PUT/products/{external_product_id}
curl -X PUT 'https://api.rechargeapps.com/products/1327844' \
  -H 'X-Recharge-Version: v2' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "brand": "Recharge",
  "variants": [
    {
      "external_variant_id": "101",
      "dimensions": {
        "weight": 1234.5
      },
      "image": {
        "small": "https:...",
        "medium": "https:...",
        "large": "https:...",
        "original": "https:..."
      },
      "option_values": [
        {
          "label": "small"
        }
      ],
      "sku": "CLO123",
      "title": "Small Recharge Logo Shirt",
      "taxable": true,
      "tax_code": "CLOTHING",
      "prices": {
        "compare_at_price": "14.22",
        "unit_price": "12.22"
      }
    },
    {
      "external_variant_id": "102",
      "dimensions": {
        "weight": 1234.5
      },
      "image": {
        "small": "https:...",
        "medium": "https:...",
        "large": "https:...",
        "original": "https:..."
      },
      "option_values": [
        {
          "label": "medium"
        }
      ],
      "sku": "CLO124",
      "title": "Medium Recharge Logo Shirt",
      "taxable": true,
      "tax_code": "CLOTHING",
      "prices": {
        "compare_at_price": "14.22",
        "unit_price": "12.22"
      }
    }
  ]
}'
Response
{
  "product": {
    "brand": "Recharge",
    "description": "A cotton shirt with the Recharge logo",
    "external_created_at": "2021-01-01T00:00:00+00:00",
    "external_product_id": "10",
    "external_updated_at": "2021-01-01T00:00:00+00:00",
    "images": [
      {
        "large": "https:...",
        "medium": "https:...",
        "original": "https:...",
        "small": "https:...",
        "sort_order": 2
      }
    ],
    "options": [
      {
        "name": "Size",
        "position": 0,
        "values": [
          {
            "label": "small",
            "position": 0
          },
          {
            "label": "medium",
            "position": 1
          },
          {
            "label": "large",
            "position": 2
          }
        ]
      }
    ],
    "published_at": "2021-01-01T00:00:00+00:00",
    "requires_shipping": true,
    "title": "Recharge Logo Shirt",
    "variants": [
      {
        "dimensions": {
          "weight": 1234.5,
          "weight_unit": "lb"
        },
        "external_variant_id": "9",
        "image": {
          "large": "https:...",
          "medium": "https:...",
          "original": "https:...",
          "small": "https:..."
        },
        "option_values": [
          {
            "label": "small"
          }
        ],
        "prices": {
          "compare_at_price": "14.22",
          "unit_price": "12.22"
        },
        "sku": "CLO123",
        "tax_code": "CLOTHING",
        "taxable": true,
        "title": "Recharge Logo Shirt - Small",
        "requires_shipping": true
      }
    ],
    "vendor": "Recharge Apparel Store"
  }
}

#Delete a product

DELETE/products/{external_product_id}
Custom
Delete product from Store.
Scopewrite_products
Only available to stores on a custom (headless) platform; stores on other platforms receive a 422 error.
DELETE/products/{external_product_id}
curl -X DELETE 'https://api.rechargeapps.com/products/509780' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'
Response
{}

#List products

GET/products
Custom
List products from store’s product catalog.
Scoperead_products
Only available to stores on a custom (headless) platform; stores on other platforms receive a 422 error. Results are paginated with cursor only; page is not supported on this endpoint.

Query parameters

  • external_product_idsstring
    Filter products by external product ids.
    GET /products/?external_product_ids=123,223 will return all products with the associated external_product_ids.
  • limitintegerNew
    The number of results to return. Defaults to 50; the maximum is 250.
  • cursorstringNew
    The cursor of the page to return, taken from next_cursor or previous_cursor in a previous response. Only limit can be sent together with cursor.
GET/products
curl 'https://api.rechargeapps.com/products' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'
Response
{
  "next_cursor": null,
  "previous_cursor": null,
  "products": [
    {
      "brand": "Recharge",
      "description": "A cotton shirt with the Recharge logo",
      "external_created_at": null,
      "external_product_id": "10",
      "external_updated_at": "2021-07-21T17:25:46+00:00",
      "images": [
        {
          "large": "https:...",
          "medium": "https:...",
          "original": "https:...",
          "small": "https:...",
          "sort_order": 2
        }
      ],
      "options": [
        {
          "name": "Size",
          "position": 0,
          "values": [
            {
              "label": "small",
              "position": 0
            },
            {
              "label": "medium",
              "position": 1
            },
            {
              "label": "large",
              "position": 2
            }
          ]
        }
      ],
      "published_at": "2021-01-01T00:00:00+00:00",
      "requires_shipping": true,
      "title": "Recharge Logo Shirt",
      "variants": [
        {
          "dimensions": {
            "weight": 1234.5,
            "weight_unit": "lb"
          },
          "external_variant_id": "101",
          "image": {
            "large": "https:...",
            "medium": "https:...",
            "original": "https:...",
            "small": "https:..."
          },
          "option_values": [
            {
              "label": "small"
            }
          ],
          "prices": {
            "compare_at_price": "14.22",
            "unit_price": "12.22"
          },
          "sku": "CLO123",
          "tax_code": "CLOTHING",
          "taxable": true,
          "title": "Small Recharge Logo Shirt",
          "requires_shipping": true
        },
        {
          "dimensions": {
            "weight": 1234.5,
            "weight_unit": "lb"
          },
          "external_variant_id": "102",
          "image": {
            "large": "https:...",
            "medium": "https:...",
            "original": "https:...",
            "small": "https:..."
          },
          "option_values": [
            {
              "label": "medium"
            }
          ],
          "prices": {
            "compare_at_price": "14.22",
            "unit_price": "12.22"
          },
          "sku": "CLO124",
          "tax_code": "CLOTHING",
          "taxable": true,
          "title": "Medium Recharge Logo Shirt",
          "requires_shipping": true
        }
      ],
      "vendor": "Recharge Apparel Store"
    }
  ]
}