API
GuidesWhat’s newGet API token
Core Resources

Collections

Collections allow to create and manage a logical list of Products called a Collection. A Collection contains an ordered list of Products and can be used for selective display of Products on chosen interfaces or for business logic automation (e.g. Discounts definition...).

15 additions in V2, marked New

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

Endpoints

#The collection object

Attributes

  • idinteger
    Unique numeric identifier for the Collection.
  • manual_sort_orderarrayNew
    The manual order of the Products in the Collection, as an array of external_product_id values.
  • created_atdatetime
    The date and time when the Collection was created.
  • descriptionstring
    The Collection description. Used to store a detailed explanation of the Collection content and its purpose.
  • sort_orderstring
    The order in which the Products in the collection should appear.
    Possible values
    id-ascid-desccreated_at-asccreated_at-descupdated_at-ascupdated_at-desctitle-asctitle-descmanual
  • titlestring
    The title of the Collection. A short descriptive definition of the Collection.
  • typestring
    The type of the Collection.
    Possible values
    automaticmanual
    manual stands for Collections which were manually created ie. when the products where explicitly selected to be part of the Collection.
  • updated_atdatetime
    The date and time when the Collection was last updated.
The collection object
{
  "id": 4021,
  "created_at": "2021-08-30T17:25:57+00:00",
  "description": "August 2021 cat products new release.",
  "manual_sort_order": [],
  "sort_order": "id-desc",
  "title": "Cats Summer Collection",
  "type": "manual",
  "updated_at": "2021-08-30T17:25:57+00:00"
}

#Create a collection

POST/collections
Create a Collection in Recharge.
Scopewrite_products
Returns 201 Created.

Body parameters

  • descriptionstringRequired
    The Collection description. Used to store a detailed explanation of the Collection content and its purpose.
  • sort_orderstring
    The order in which the Products in the collection should appear.
    Possible values
    id-ascid-desccreated_at-asccreated_at-descupdated_at-ascupdated_at-desctitle-asctitle-descmanual
    Default id-desc
  • titlestringRequired
    The title of the Collection. A short descriptive definition of the Collection.
  • typestringNew
    The type of the Collection. Defaults to manual. It cannot be changed after the collection is created.
    Possible values
    automaticmanual
POST/collections
curl -X POST 'https://api.rechargeapps.com/collections' \
  -H 'X-Recharge-Version: v2' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "description": "cat products new release",
  "title": "Cats Spring 2022"
}'
Response
{
  "collection": {
    "id": 134157,
    "created_at": "2022-03-29T04:57:36+00:00",
    "description": "cat products new release",
    "manual_sort_order": [],
    "sort_order": "id-desc",
    "title": "Cats Spring 2022",
    "type": "manual",
    "updated_at": "2020-12-17T18:50:39+00:00"
  }
}

#Retrieve a collection

GET/collections/{id}
Retrieve one Collection using collection_id.
Scoperead_products

Response attributes

  • errorstring
    Error message
  • messagestring
    Details about the error
GET/collections/{id}
curl 'https://api.rechargeapps.com/collections/134157' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'
Response
{
  "collection": {
    "id": 134157,
    "created_at": "2022-03-29T04:57:36+00:00",
    "description": "cat products new release",
    "manual_sort_order": [],
    "sort_order": "id-desc",
    "title": "Cats Spring 2022",
    "type": "manual",
    "updated_at": "2022-03-29T04:57:36+00:00"
  }
}

#Update a collection

PUT/collections/{id}
Modify an existing Collection to match the specified parameters.
Scopewrite_products
type cannot be updated; sending it returns a 422 error.

Body parameters

  • descriptionstring
    The Collection description. Used to store a detailed explanation of the Collection content and its purpose.
  • sort_orderstring
    The order in which the Products in the collection should appear.
    Possible values
    id-ascid-desccreated_at-asccreated_at-descupdated_at-ascupdated_at-desctitle-asctitle-descmanual
  • titlestring
    The title of the Collection. A short descriptive definition of the Collection.
  • manual_sort_orderarrayNew
    An array of external_product_id values to move to the top of the manual order of the Collection, in the order given. Products that are not in the collection are ignored and products left out keep their relative order.

Response attributes

  • errorstring
    Error message
  • messagestring
    Details about the error
PUT/collections/{id}
curl -X PUT 'https://api.rechargeapps.com/collections/134157' \
  -H 'X-Recharge-Version: v2' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "sort_order": "title-asc"
}'
Response
{
  "collection": {
    "id": 134157,
    "created_at": "2022-03-29T04:57:36+00:00",
    "description": "cats products new release",
    "manual_sort_order": [],
    "sort_order": "title-asc",
    "title": "Cats Spring 2022",
    "type": "manual",
    "updated_at": "2022-03-29T05:27:39+00:00"
  }
}

#Delete a collection

DELETE/collections/{id}
Delete a Collection
Scopewrite_products
For safety and good UX, you can only delete a Collection if it is not in use in the Customer Portal

Response attributes

  • errorstring
    Error message
  • messagestring
    Details about the error
DELETE/collections/{id}
curl -X DELETE 'https://api.rechargeapps.com/collections/134129' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'
Response
{}

#List collections

GET/collections
Return a list of Collections in your store.

HTTP request examples

GET /collections

GET /collections?title=Cats
Scoperead_products
The title filter matches collections whose title contains the given text.

Query parameters

  • titlestring
    The title of the Collection. A short descriptive definition of the Collection.
  • idsstringNew
    Filter collections by id. If passing multiple values, must be comma separated.
  • typestringNew
    Return the collections of a specific type.
    Possible values
    automaticmanual
  • sort_bystringNew
    The order in which the collections are returned. Defaults to id-desc.
    Possible values
    id-ascid-desccreated_at-asccreated_at-descupdated_at-ascupdated_at-desctitle-asctitle-desc
  • 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.
  • pageintegerNew
    The page of results to show. Page-based pagination is deprecated in favor of cursor.
    Only for API tokens that are still allowed to use page-based pagination; other tokens must use cursor.
GET/collections
curl 'https://api.rechargeapps.com/collections?limit=3' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'
Response
{
  "next_cursor": null,
  "previous_cursor": null,
  "collections": [
    {
      "id": 134136,
      "created_at": "2022-03-28T15:38:27+00:00",
      "description": "cat products august 2022",
      "manual_sort_order": [],
      "sort_order": "title-asc",
      "title": "Cats",
      "type": "manual",
      "updated_at": "2022-03-28T15:38:27+00:00"
    },
    {
      "id": 134129,
      "created_at": "2022-03-28T12:27:03+00:00",
      "description": "kitten accessories soft.",
      "manual_sort_order": [],
      "sort_order": "id-asc",
      "title": "Soft Kitty",
      "type": "manual",
      "updated_at": "2022-02-23T11:27:34+00:00"
    }
  ]
}

#List collections products

GET/collection_products
Return a list of the product ids included in Collections in your store.

HTTP request examples

GET /collection_products

GET /collection_products?collection_id=134157
Scoperead_products
Each item of collection_products contains collection_id, external_product_id, created_at and updated_at. collection_id is optional.

Query parameters

  • collection_idinteger
    The id of the Collection for which you want to see the products.
  • external_product_idstringNew
    Return only the collection products with the given external_product_id, which shows the collections a product belongs to.
  • sort_bystringNew
    The order in which the results are returned. Defaults to id-desc.
    Possible values
    id-ascid-desc
  • 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.
  • pageintegerNew
    The page of results to show. Page-based pagination is deprecated in favor of cursor.
    Only for API tokens that are still allowed to use page-based pagination; other tokens must use cursor.

Response attributes

  • collection_idinteger
    Unique numeric identifier for a Collection.
  • created_atdatetime
    The date and time when the Product was added to the collection.
  • external_product_idstring
    The external_product_id.ecommerce of the Product.
  • updated_atdatetime
    The date and time when the Product entry for this Collection was last updated.
GET/collection_products
curl 'https://api.rechargeapps.com/collection_products?limit=3' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'
Response
{
  "next_cursor": null,
  "previous_cursor": null,
  "collection_products": [
    {
      "collection_id": 111733,
      "created_at": "2022-03-30T18:12:09+00:00",
      "external_product_id": "5",
      "updated_at": "2022-03-30T18:12:09+00:00"
    },
    {
      "collection_id": 111733,
      "created_at": "2022-02-12T12:53:33+00:00",
      "external_product_id": "2",
      "updated_at": "2022-02-12T12:53:33+00:00"
    },
    {
      "collection_id": 111735,
      "created_at": "2022-02-12T06:46:49+00:00",
      "external_product_id": "3",
      "updated_at": "2022-02-12T06:46:49+00:00"
    }
  ]
}

#Add collection products

POST/collections/{id}/collection_products-bulk
Add products to a Collection in Recharge.
Scopewrite_products
A request can add at most 250 distinct products, and a collection can hold at most 10,000 products. Adding a product that is already in the collection returns a 422 error.

Body parameters

  • collection_productsarray of objectsRequired
    An array of products and their collection definition to be added to the Collection.
    Important: there is a set limit of 250 products that can be added per request.
    Show child attributesHide child attributes1

Response attributes

  • collection_idinteger
    Unique numeric identifier for a Collection.
  • created_atdatetime
    The date and time when the Product was added to the collection.
  • external_product_idstring
    The external_product_id.ecommerce of the Product.
  • updated_atdatetime
    The date and time when the Product entry for this Collection was last updated.
POST/collections/{id}/collection_products-bulk
curl -X POST 'https://api.rechargeapps.com/collections/134129/collection_products-bulk' \
  -H 'X-Recharge-Version: v2' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "collection_products": [
    {
      "external_product_id": "7"
    }
  ]
}'
Response
{
  "collection_products": [
    {
      "collection_id": 111733,
      "created_at": "2022-03-29T04:57:36+00:00",
      "external_product_id": "7",
      "updated_at": "2022-03-30T18:32:35+00:00"
    }
  ]
}

#Delete collection products

DELETE/collections/{id}/collection_products-bulk
Removes products from a Collection in Recharge.
Scopewrite_products

Body parameters

  • collection_productsarray of objectsRequired
    The array of products to be removed from the Collection identified by their external_product_id.
    Important: there is a set limit of 250 products that can be added per request.
    Show child attributesHide child attributes1

Response attributes

  • errorstring
    Error message
  • messagestring
    Details about the error
DELETE/collections/{id}/collection_products-bulk
curl '-X DELETE https://api.rechargeapps.com/collections/134129/collection_products-bulk' \
 -H 'X-Recharge-Version: v2' \
 -H 'Content-Type: application/json' \
 -H 'X-Recharge-Access-Token: your_api_token' \
 -d '{
  "collection_products": [
    {
      "external_product_id": "7"
      }
    ]
}'
Response
{}

#Reorder collection productsNew

POST/collections/{id}/modify_sort
Changes the manual order of the Products in a Collection and returns the updated collection. Send exactly one of move_to_top, move_to_bottom or move_to_position. The moved products keep their order relative to each other, and products that are not in the collection are ignored.
Scopewrite_products

Body parameters

  • move_to_toparray
    An array of external_product_id values to move to the top of the collection.
  • move_to_bottomarray
    An array of external_product_id values to move to the bottom of the collection.
  • move_to_positionobject
    An object describing products to move to a specific position in the collection.
    Show child attributesHide child attributes2
    • external_product_idsarray
      An array of external_product_id values to move. Required, with at least one value.
    • new_positioninteger
      The position, starting at 1, to which the first of the products is moved. Required.
POST/collections/{id}/modify_sort
curl -X POST 'https://api.rechargeapps.com/collections/129593/modify_sort' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'
Response
{
  "collection": {
    "id": 134129,
    "created_at": "2026-03-02T15:04:31",
    "description": "Our seasonal coffee selection",
    "manual_sort_order": [
      "7654321099",
      "7654321098"
    ],
    "sort_order": "manual",
    "title": "Seasonal coffees",
    "type": "manual",
    "updated_at": "2026-03-04T09:12:00"
  }
}