API
GuidesGet 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...).

Endpoints

#The collection object

Attributes

  • idinteger
    Unique numeric identifier for the Collection.
  • 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-desctitle-asctitle-desccreated_at-asccreated_at-desc
  • titlestring
    The title of the Collection. A short descriptive definition of the Collection.
  • typestring
    The type of the Collection.
    Possible values
    manual
    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.",
  "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

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-desctitle-asctitle-desccreated-asccreated-desc
    Default id-desc
  • titlestringRequired
    The title of the Collection. A short descriptive definition of the Collection.
POST/collections
curl -X POST 'https://api.rechargeapps.com/collections' \
  -H 'X-Recharge-Version: 2021-11' \
  -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",
    "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: 2021-11' \
  -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",
    "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

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-desctitle-asctitle-desccreated-asccreated-desc
  • titlestring
    The title of the Collection. A short descriptive definition of the Collection.

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: 2021-11' \
  -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",
    "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: 2021-11' \
  -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

Query parameters

  • titlestring
    The title of the Collection. A short descriptive definition of the Collection.
GET/collections
curl 'https://api.rechargeapps.com/collections?limit=3' \
  -H 'X-Recharge-Version: 2021-11' \
  -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",
      "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.",
      "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

Query parameters

  • collection_idinteger
    The id of the Collection for which you want to see the products.

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: 2021-11' \
  -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

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: 2021-11' \
  -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: 2021-11' \
 -H 'Content-Type: application/json' \
 -H 'X-Recharge-Access-Token: your_api_token' \
 -d '{
  "collection_products": [
    {
      "external_product_id": "7"
      }
    ]
}'
Response
{}