Core Resources

Bundle Selections

Plus planSCIRCS

A bundle selection represents the contents within a Bundle linked to an individual Subscription. It can represent the selection for upcoming orders or past orders. A BundleSelection is associated with a corresponding Subscription and a BundleVariant (the BundleVariant is used to validate contents in the selection). When a new order for the associated Subscription occurs, it will extract the current contents of the BundleSelection for the Bundle item in the order.

25 additions in V2, marked New

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

Endpoints

GET/bundle_selections
GET/bundle_selections/{id}
POST/bundle_selections
PUT/bundle_selections/{id}
DELETE/bundle_selections/{id}

#The bundle selection object

Plus planRCSSCI

Attributes

idinteger
The unique numeric identifier for the BundleSelection.
bundle_variant_idinteger
The ID of the BundleVariant associated with the BundleSelection.
purchase_item_idinteger
The ID of the PurchaseItem associated with the BundleSelection.
created_atdatetime
The date and time when the contents were selected.
external_product_idstring
The product id as it appears in the external e-commerce platform. The external_product_id of the Product record in Recharge, linking the BundleSelection to a Product associated with a Bundle.
external_variant_idstring
The variant id as it appears in the external e-commerce platform. The external_variant_id of the Product record in Recharge, linking the BundleSelection to a Product associated with a Bundle.
itemsarray of objects
A list of item objects, each containing information about a distinct product selected as part of the Bundle.
Show child attributesHide child attributes91 new
- idinteger
  The unique numeric identifier for the item selection.
- collection_idstring
  The collection id as it appears in the external e-commerce platform.
- collection_sourcestring
  The identifier of the external e-commerce platform.
- pricestringNew
  The price of the item.
- created_atdatetime
  The date and time when this item was selected.
- external_product_idstring
  The product id as it appears in the external e-commerce platform. This is the item which is going to be extracted when the Bundle is processed.
- external_variant_idstring
  The variant id as it appears in the external e-commerce platform. This is the item which is going to be extracted when the Bundle is processed.
- quantityinteger
  The quantity of this product.
- updated_atdatetime
  The date and time at which the item selection was most recently updated.
updated_atdatetime
The date and time at which the BundleSelection was most recently updated.
charge_idinteger · nullableNew
The ID of the Charge associated with the BundleSelection, when the selection applies to a specific upcoming charge.
order_idinteger · nullableNew
The ID of the Order associated with the BundleSelection.
items_countintegerNew
The item count of the BundleVariant associated with the BundleSelection.
is_fallbackbooleanNew
Whether the selection is the default selection of the BundleVariant, returned because no selection has been made for the PurchaseItem. Fallback selections have a null id.
Fallback selections are only returned when filtering by purchase_item_ids on stores that have default bundle selections enabled; otherwise the value is always false.

The bundle selection object

{
  "bundle_selection": {
    "id": 100714428,
    "bundle_variant": 382417,
    "purchase_item_id": 199820883,
    "created_at": "2022-08-26T18:31:28+00:00",
    "external_product_id": "7121697210548",
    "external_variant_id": "41450875650228",
    "items": [
      {
        "id": 541,
        "collection_id": "287569608884",
        "collection_source": "shopify",
        "created_at": "2022-08-26T18:31:28+00:00",
        "external_product_id": "7121693671604",
        "external_variant_id": "41450853105844",
        "price": "10.00",
        "quantity": 3,
        "updated_at": "2022-08-26T18:52:41+00:00"
      }
    ],
    "updated_at": "2022-08-26T18:31:28+00:00",
    "charge_id": null,
    "order_id": null,
    "items_count": 3
  }
}

#List bundle selections

GET/bundle_selections

Plus planRCSSCI

Returns a list of BundleSelections.

HTTP request examples

GET /bundle_selections?purchase_item_ids=:purchase_item_id_1,:purchase_item_id_2

GET /bundle_selections?bundle_variant_ids=:bundle_variant_id_1,:bundle_variant_id_2

GET /bundle_selections?limit=1

GET /bundle_selections?limit=1&page=2

GET /bundle_selections?sort_by=updated_at-desc

Returned BundleSelections are sorted descending by ID value by default.

Scoperead_subscriptions

Query parameters

purchase_item_idsstring
Filter BundleSelections by Subscription or Onetime ID.
If passing multiple values, must be comma separated. Non-integer values will result in a 422 error.
bundle_variant_idsstring
Filter BundleSelections by BundleVariants.
If passing multiple values, must be comma separated. Non-integer values will result in a 422 error.
limitstring
The amount of results.
Default 50Maximum 250
pagestringDeprecated
The page to show.
Default 1
Page-based pagination has been deprecated but still available to use for pages up to a 100. If you need data past this point, use cursor pagination.
sort_bystring
Sort listed BundleSelections in a specific order.
Available sort options: id-asc, id-desc, updated_at-asc, updated_at-desc.
active_purchase_itemsboolean
Bundle selections are not directly linked to Subscriptions. By default, the endpoint returns Bundle Selections, even those associated with cancelled subscriptions, unless the Bundle Selection has been deleted.
To exclude cancelled subscriptions from your results, include active_purchase_items=true in your query.
updated_at_mindatetimeNew
Show BundleSelections updated after the given date.
updated_at_maxdatetimeNew
Show BundleSelections updated before the given date.
cursorstringNew
Return either the next or previous page of bundle selections using the next_cursor or previous_cursor value from a previous response. Only limit can be passed together with cursor.
charge_idsstringNew
Filter BundleSelections by Charge ID. If passing multiple values, must be comma separated.
Only available to stores that can manage bundle selections for individual upcoming charges; other stores receive a 403.
item_external_product_idsstringNew
Filter BundleSelections that contain an item with one of the given external product IDs. If passing multiple values, must be comma separated.
Only available to stores that have item filters enabled for bundle selections; other stores receive a 403.
item_external_variant_idsstringNew
Filter BundleSelections that contain an item with one of the given external variant IDs. If passing multiple values, must be comma separated.
Only available to stores that have item filters enabled for bundle selections; other stores receive a 403.

GET/bundle_selections

curl 'https://api.rechargeapps.com/bundle_selections?limit=3' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "next_cursor": null,
  "previous_cursor": null,
  "bundle_selections": [
    {
      "id": 100714428,
      "bundle_variant": 382417,
      "purchase_item_id": 199820883,
      "created_at": "2022-08-26T18:31:28+00:00",
      "external_product_id": "7121697210548",
      "external_variant_id": "41450875650228",
      "items": [
        {
          "id": 541,
          "collection_id": "287569608884",
          "collection_source": "shopify",
          "created_at": "2022-08-26T18:31:28+00:00",
          "external_product_id": "7121693671604",
          "external_variant_id": "41450853105844",
          "price": "10.00",
          "quantity": 3,
          "updated_at": "2022-08-26T18:52:41+00:00"
        }
      ],
      "updated_at": "2022-08-26T18:31:28+00:00",
      "charge_id": null,
      "order_id": null,
      "items_count": 3
    }
  ]
}

#Retrieve a bundle selection

GET/bundle_selections/{id}

Plus planRCSSCI

Retrieve a BundleSelection using the bundle_selection_id.

Scoperead_subscriptions

Response attributes

errorstring
Error message
messagestring
Details about the error

GET/bundle_selections/{id}

curl 'https://api.rechargeapps.com/bundle_selections/100714428' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "bundle_selection": {
    "id": 100714428,
    "bundle_variant": 382417,
    "purchase_item_id": 199820883,
    "created_at": "2022-08-26T18:31:28+00:00",
    "external_product_id": "7121697210548",
    "external_variant_id": "41450875650228",
    "items": [
      {
        "id": 541,
        "collection_id": "287569608884",
        "collection_source": "shopify",
        "created_at": "2022-08-26T18:31:28+00:00",
        "external_product_id": "7121693671604",
        "external_variant_id": "41450853105844",
        "price": "10.00",
        "quantity": 3,
        "updated_at": "2022-08-26T18:52:41+00:00"
      }
    ],
    "updated_at": "2022-08-26T18:31:28+00:00",
    "charge_id": null,
    "order_id": null,
    "items_count": 3
  }
}

#Create a bundle selection

POST/bundle_selections

Plus planRCSSCI

Create a BundleSelection.

Scopewrite_subscriptions

BundleSelections endpoints are available for Recharge Plus merchants. If you’re interested in leveraging the Recharge bundle_selections endpoints, reach out to your account manager or our Support team.
Learn more about Recharge Plus.

Returns 201. Items with a quantity of zero or less are ignored.

Query parameters

commitbooleanNew
Controls whether the QUEUED charges linked to the purchase item are regenerated before the response is returned (true, default) or in the background (false).
skip_remote_validationbooleanNew
If true, the selected items are not validated against the external e-commerce platform.
Only honored for stores that have been enabled to skip remote validation; ignored otherwise.

Body parameters

purchase_item_idintegerRequired
The ID of the PurchaseItem associated with the BundleSelection.
plan_idinteger
A Recharge Plan ID. If provided in a dynamically-priced Bundle, the unit price of each product variant will be inferred from the plan associated with the ID; otherwise, it will be inferred from the plan with the greatest discount for each product in the selection. This is not used in fixed-priced Bundles.
itemsarray of objectsRequired
A list of item objects, each containing information about a distinct product selected as part of the Bundle.
Show child attributesHide child attributes61 new
- collection_idstringRequired
  The collection id as it appears in the external e-commerce platform.
- collection_sourcestring
  The identifier of the external e-commerce platform.
- external_product_idstringRequired
  The product id as it appears in the external e-commerce platform. This is the item which is going to be extracted when the Bundle is processed.
- external_variant_idstringRequired
  The variant id as it appears in the external e-commerce platform. This is the item which is going to be extracted when the Bundle is processed.
- pricestringNew
  The price of the item. Must not be negative.
  Only applied to dynamically priced bundles that allow custom prices; ignored for other bundles.
- quantityintegerRequired
  The quantity of this product.
charge_idinteger · nullableNew
The ID of the upcoming Charge the BundleSelection applies to. The charge must be in QUEUED status.
Only available to stores that can manage bundle selections for individual upcoming charges; other stores receive a 403.
order_idinteger · nullableNew
The ID of the Order the BundleSelection applies to. Requires charge_id, and the order must belong to that charge.
Only available to stores that can manage bundle selections for individual upcoming charges.

Response attributes

errorsobject
Error object

POST/bundle_selections

curl -X POST 'https://api.rechargeapps.com/bundle_selections' \
  -H 'X-Recharge-Version: v2' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "purchase_item_id": 199820883,
  "items": [
    {
      "collection_id": "287569608884",
      "collection_source": "shopify",
      "external_product_id": "7121693671604",
      "external_variant_id": "41450853105844",
      "quantity": 3
    }
  ]
}'

Response

{
  "bundle_selection": {
    "id": 100714428,
    "bundle_variant": 382417,
    "purchase_item_id": 199820883,
    "created_at": "2022-08-26T18:31:28+00:00",
    "external_product_id": "7121697210548",
    "external_variant_id": "41450875650228",
    "items": [
      {
        "id": 541,
        "collection_id": "287569608884",
        "collection_source": "shopify",
        "created_at": "2022-08-26T18:31:28+00:00",
        "external_product_id": "7121693671604",
        "external_variant_id": "41450853105844",
        "price": "10.00",
        "quantity": 3,
        "updated_at": "2022-08-26T18:52:41+00:00"
      }
    ],
    "updated_at": "2022-08-26T18:31:28+00:00",
    "charge_id": null,
    "order_id": null,
    "items_count": 3
  }
}

#Update a bundle selection

PUT/bundle_selections/{id}

Plus planRCSSCI

Modify an existing BundleSelection to match the specified parameters.

Scopewrite_subscriptions

BundleSelections endpoints are available for Recharge Plus merchants. If you’re interested in leveraging the Recharge bundle_selections endpoints, reach out to your account manager or our Support team.
Learn more about Recharge Plus.

The items list replaces the current selection: items sent with an id are updated, items sent without an id are created, and existing items that are not in the list are removed.

Query parameters

commitbooleanNew
Controls whether the QUEUED charges linked to the purchase item are regenerated before the response is returned (true, default) or in the background (false).
skip_remote_validationbooleanNew
If true, the selected items are not validated against the external e-commerce platform.
Only honored for stores that have been enabled to skip remote validation; ignored otherwise.

Body parameters

plan_idinteger
A Recharge Plan ID. If provided in a dynamically-priced Bundle, the unit price of each product variant will be inferred from the plan associated with the ID; otherwise, it will be inferred from the plan with the greatest discount for each product in the selection. This is not used in fixed-priced Bundles.
itemsarray of objects
A list of item objects, each containing information about a distinct product selected as part of the Bundle.
Show child attributesHide child attributes66 new
- idintegerNew
  The unique numeric identifier of an existing item selection to update. Items sent without an id are created.
- collection_idstringRequiredNew
  The collection id as it appears in the external e-commerce platform.
- external_product_idstringRequiredNew
  The product id as it appears in the external e-commerce platform.
- external_variant_idstringRequiredNew
  The variant id as it appears in the external e-commerce platform.
- pricestringNew
  The price of the item. Must not be negative.
  Only applied to dynamically priced bundles that allow custom prices; ignored for other bundles.
- quantityintegerRequiredNew
  The quantity of this product.

Response attributes

errorstring
Error message
messagestring
Details about the error

PUT/bundle_selections/{id}

curl -X PUT 'https://api.rechargeapps.com/bundle_selections/100714428' \
  -H 'X-Recharge-Version: v2' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "purchase_item_id": 199820883,
  "items": [
    {
      "collection_id": "287569608884",
      "collection_source": "shopify",
      "external_product_id": "7121693671604",
      "external_variant_id": "41450853105844",
      "quantity": 3
    }
  ]
}'

Response

{
  "bundle_selection": {
    "id": 100714428,
    "bundle_variant": 382417,
    "purchase_item_id": 199820883,
    "created_at": "2022-08-26T18:31:28+00:00",
    "external_product_id": "7121697210548",
    "external_variant_id": "41450875650228",
    "items": [
      {
        "id": 541,
        "collection_id": "287569608884",
        "collection_source": "shopify",
        "created_at": "2022-08-26T18:31:28+00:00",
        "external_product_id": "7121693671604",
        "external_variant_id": "41450853105844",
        "price": "10.00",
        "quantity": 3,
        "updated_at": "2022-08-26T18:52:41+00:00"
      }
    ],
    "updated_at": "2022-08-26T18:31:28+00:00",
    "charge_id": null,
    "order_id": null,
    "items_count": 3
  }
}

#Delete a bundle selection

DELETE/bundle_selections/{id}

Plus planRCSSCI

Delete a BundleSelection

Scopewrite_subscriptions

Query parameters

commitbooleanNew
Controls whether the QUEUED charges linked to the purchase item are regenerated before the response is returned (true, default) or in the background (false).

Response attributes

errorstring
Error message
messagestring
Details about the error

DELETE/bundle_selections/{id}

curl -X DELETE 'https://api.rechargeapps.com/bundle_selections/100714428' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{}