Skip to content

Custom Endpoints

GEThttps://rebuyengine.com/api/v1/custom/id/{ruleset_id}

Requirements

To use this endpoint you must add a valid ruleset ID to /api/v1/custom/id/{ruleset_id}

Using Rebuy's GUI

You can use our GET /api/v1/custom/id/{ruleset_id} endpoint through our Graphical User Interface (GUI). We allow access to this feature with what we call data sources. In data sources, you can create a set of conditional rules (ie. a ruleset). If those conditions are met by one of your customers, this endpoint will return them a list of products.

Once created, data sources can be applied to power widgets. However, this page doesn't go into detail on how to create and use widgets.

First, log into Rebuy Engine.

In the left navigation bar, select Data Sources

The Rebuy Data Source Editor

Creating Rulesets

To create a ruleset, select the Create Ruleset button.

The creation of a new ruleset in the data source editor

After creating a ruleset, you can set your first rule. Rulesets can be powered by only one rule, or you can choose to stack multiple rules for further customization.

Multiple example rules in the data source editor

For each rule block, there is an "IF" condition and a "RETURN" statement.

An example if and return block in the data source editor

"IF" conditions

For each "IF" condition, you define parameters that can tell us when a certain condition is met.

The if block and associated operator dropdown in the data source editor

This is where our GUI and endpoint synchronize so well. At this stage, you are literally defining what information you are sending to our API.

You can make your "IF" condition more complex if you add "AND IF" or "OR IF" statements into the rule.

The more complex or if block and and if mutator options in the data source editor

"RETURN" statements

For each "RETURN" Statement, you define parameters that can tell our API what to return to your customer. This is another area where our GUI and endpoint synchronize so well. At this stage, you are literally defining what information you are receiving from our API.

The return block and associated dropdown in the data source editor

You can make your "RETURN" statements more complex if you add "AND" statements into the rule.

The more complex and mutator option within the return block in the data source editor

Example Data Sources

Below you will find some great ways that our clients have effectively used this feature.

The associated upsell

In the example below, if the grooming kit is chosen by the customer, we will display them some essentials that go along with the kit. In other words, your shop is ready to sell them a product and as a result we want to upsell them another product.

An example of a ruleset where a pro shave kit is selected

More Reading

Read more on widgets

Query Parameters

key · string · required
Your Rebuy public API key. Find this in your Rebuy admin under Settings → API Keys.
shopify_product_ids · string
Comma separated list of Shopify product IDs. Also used if only passing up single product ID.
Allows for product level rules in your Data Source
shopify_variant_ids · string
Comma separated list of Shopify variant IDs of a product. Also used if only passing up single variant ID.
Allows for variant level rules in your Data Source.
shopify_customer_id · string
The Customer ID of the Shopify user.
cart_subtotal · string
The total cost of items inside the cart.
cart_line_count · string
A single line in an order. There is one line item for each product variant.
cart_item_count · string
The number of items inside the cart.
metafields · string
Valid values: yes. Returns product objects enriched with a metafields property.
variant_metafields · string
Valid values: yes. Returns product variant objects enriched with a metafields property.
time · string
The day of the user. This can be a unix timestamp or match any RFC time standard.
limit · string
Used to limit the number of results returned.
uuid · string
The 'Universally Unique Identifier' of the subject - the client is responsible for creating the token that represents the session. Example value: be6f5fab-32a4-43e5-967c-68017baa3aa5
url · string
A value to be searched and matched within a URL. Example: beanie-reversible
format · string
Valid values: pretty. Use pretty to make the response easy to read.
country_code · string

The ISO 3166-1 alpha-2 country code (e.g., US, CA, GB) corresponding to a Market region. Retrieves variant pricing from the Market’s catalog. The prices returned reflect the shop’s first active Market that matches the provided country_code. Only products included in that Market’s catalog will be returned in the response — products excluded from the catalog will not appear.

Required Shopify Scope: read_markets

Replaces the deprecated presentment_prices query parameter.

Code Example

// GET https://rebuyengine.com/api/v1/custom/id/{ RULESET_ID }
const API_KEY = "YOUR_PUBLIC_API_KEY";

const params = new URLSearchParams({
  key: API_KEY,
  shopify_product_ids: "YOUR_VALUE",
  shopify_variant_ids: "YOUR_VALUE"
});

fetch(`https://rebuyengine.com/api/v1/custom/id/{ RULESET_ID }?${params}`)
  .then(response => response.json())
  .then(data => console.log(data));

Response Examples

200 OK

{
  "data": [
    {
      "id": 4484974870564,
      "title": "Classic Beanie",
      "body_html": "Keep your head warm and look good doing it! Comfortable rib knitted hat in soft acrylic. Double yarn gives it a marbled look. Small folded leather logo on the side.",
      "vendor": "Example Brand",
      "product_type": "Beanie",
      "created_at": "2020-01-28T16:23:44-05:00",
      "handle": "beanie-classic",
      "updated_at": "2020-08-20T16:55:58-04:00",
      "published_at": "2020-01-28T16:23:44-05:00",
      "template_suffix": "",
      "published_scope": "web",
      "tags": "clothing",
      "admin_graphql_api_id": "gid://shopify/Product/4484974870564",
      "variants": [
        {
          "id": 31628219449380,
          "product_id": 4484974870564,
          "title": "Default Title",
          "price": "24.00",
          "sku": "BEANIE1",
          "position": 1,
          "inventory_policy": "deny",
          "compare_at_price": null,
          "fulfillment_service": "manual",
          "inventory_management": null,
          "option1": "Default Title",
          "option2": null,
          "option3": null,
          "created_at": "2020-01-28T16:23:45-05:00",
          "updated_at": "2020-08-20T16:51:01-04:00",
          "taxable": true,
          "barcode": "",
          "grams": 0,
          "image_id": null,
          "weight": 0,
          "weight_unit": "lb",
          "inventory_item_id": 33399553163300,
          "inventory_quantity": -26,
          "old_inventory_quantity": -26,
          "requires_shipping": true,
          "admin_graphql_api_id": "gid://shopify/ProductVariant/31628219449380"
        }
      ],
      "options": [
        {
          "id": 5868989841444,
          "product_id": 4484974870564,
          "name": "Title",
          "position": 1,
          "values": [
            "Default Title"
          ]
        }
      ],
      "images": [
        {
          "id": 14057549561892,
          "product_id": 4484974870564,
          "position": 1,
          "created_at": "2020-01-28T16:24:01-05:00",
          "updated_at": "2020-01-28T16:24:01-05:00",
          "alt": null,
          "width": 600,
          "height": 600,
          "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/classic-beanie.jpg?v=1580246641",
          "variant_ids": [],
          "admin_graphql_api_id": "gid://shopify/ProductImage/14057549561892"
        }
      ],
      "image": {
        "id": 14057549561892,
        "product_id": 4484974870564,
        "position": 1,
        "created_at": "2020-01-28T16:24:01-05:00",
        "updated_at": "2020-01-28T16:24:01-05:00",
        "alt": null,
        "width": 600,
        "height": 600,
        "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/classic-beanie.jpg?v=1580246641",
        "variant_ids": [],
        "admin_graphql_api_id": "gid://shopify/ProductImage/14057549561892"
      }
    },
    {
      "id": 4484976148516,
      "title": "Reversible Beanie",
      "body_html": "Classic Beanie",
      "vendor": "Example Brand",
      "product_type": "Beanie",
      "created_at": "2020-01-28T16:24:50-05:00",
      "handle": "beanie-reversible",
      "updated_at": "2020-12-17T15:09:30-05:00",
      "published_at": "2020-01-28T16:24:50-05:00",
      "template_suffix": "",
      "published_scope": "web",
      "tags": "clothing",
      "admin_graphql_api_id": "gid://shopify/Product/4484976148516",
      "variants": [
        {
          "id": 31628220530724,
          "product_id": 4484976148516,
          "title": "Default Title",
          "price": "24.00",
          "sku": "BEANIE1",
          "position": 1,
          "inventory_policy": "deny",
          "compare_at_price": null,
          "fulfillment_service": "manual",
          "inventory_management": "shopify",
          "option1": "Default Title",
          "option2": null,
          "option3": null,
          "created_at": "2020-01-28T16:24:50-05:00",
          "updated_at": "2020-12-17T15:09:30-05:00",
          "taxable": true,
          "barcode": "",
          "grams": 0,
          "image_id": null,
          "weight": 0,
          "weight_unit": "lb",
          "inventory_item_id": 33399558504484,
          "inventory_quantity": 100,
          "old_inventory_quantity": 100,
          "requires_shipping": true,
          "admin_graphql_api_id": "gid://shopify/ProductVariant/31628220530724"
        }
      ],
      "options": [
        {
          "id": 5868992036900,
          "product_id": 4484976148516,
          "name": "Title",
          "position": 1,
          "values": [
            "Default Title"
          ]
        }
      ],
      "images": [
        {
          "id": 14057553854500,
          "product_id": 4484976148516,
          "position": 1,
          "created_at": "2020-01-28T16:25:05-05:00",
          "updated_at": "2020-01-28T16:25:05-05:00",
          "alt": null,
          "width": 600,
          "height": 600,
          "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/reversible-beanie.jpg?v=1580246705",
          "variant_ids": [],
          "admin_graphql_api_id": "gid://shopify/ProductImage/14057553854500"
        }
      ],
      "image": {
        "id": 14057553854500,
        "product_id": 4484976148516,
        "position": 1,
        "created_at": "2020-01-28T16:25:05-05:00",
        "updated_at": "2020-01-28T16:25:05-05:00",
        "alt": null,
        "width": 600,
        "height": 600,
        "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/reversible-beanie.jpg?v=1580246705",
        "variant_ids": [],
        "admin_graphql_api_id": "gid://shopify/ProductImage/14057553854500"
      }
    }
  ],
  "metadata": {
    "input_products": [
      {
        "id": 562405015588,
        "title": "50/50 T - The Best T Shirt On The Market and Definitely The Best Fabric Too",
        "body_html": "50/50 T",
        "vendor": "Example Brand",
        "product_type": "",
        "created_at": "2018-03-20T14:16:12-04:00",
        "handle": "hanes-50-50-t-shirt",
        "updated_at": "2021-01-06T18:40:04-05:00",
        "published_at": "2019-09-26T22:48:25-04:00",
        "template_suffix": "",
        "published_scope": "global",
        "tags": "clothing",
        "admin_graphql_api_id": "gid://shopify/Product/562405015588",
        "variants": [
          {
            "id": 7162531512356,
            "product_id": 562405015588,
            "title": "Lime",
            "price": "8.00",
            "sku": "H5050TS-1",
            "position": 1,
            "inventory_policy": "deny",
            "compare_at_price": null,
            "fulfillment_service": "manual",
            "inventory_management": "shopify",
            "option1": "Lime",
            "option2": null,
            "option3": null,
            "created_at": "2018-03-20T14:16:12-04:00",
            "updated_at": "2021-01-06T18:36:35-05:00",
            "taxable": true,
            "barcode": "",
            "grams": 0,
            "image_id": 2155956699172,
            "weight": 0,
            "weight_unit": "lb",
            "inventory_item_id": 7159756619812,
            "inventory_quantity": 98,
            "old_inventory_quantity": 98,
            "requires_shipping": true,
            "admin_graphql_api_id": "gid://shopify/ProductVariant/7162531512356"
          },
          {
            "id": 7162531545124,
            "product_id": 562405015588,
            "title": "Yellow",
            "price": "8.00",
            "sku": "H5050TS-2",
            "position": 2,
            "inventory_policy": "continue",
            "compare_at_price": null,
            "fulfillment_service": "manual",
            "inventory_management": null,
            "option1": "Yellow",
            "option2": null,
            "option3": null,
            "created_at": "2018-03-20T14:16:12-04:00",
            "updated_at": "2020-05-01T14:33:59-04:00",
            "taxable": true,
            "barcode": "",
            "grams": 0,
            "image_id": 2155957387300,
            "weight": 0,
            "weight_unit": "lb",
            "inventory_item_id": 7159756652580,
            "inventory_quantity": -12,
            "old_inventory_quantity": -12,
            "requires_shipping": true,
            "admin_graphql_api_id": "gid://shopify/ProductVariant/7162531545124"
          }
        ],
        "options": [
          {
            "id": 833046904868,
            "product_id": 562405015588,
            "name": "Color",
            "position": 1,
            "values": [
              "Lime",
              "Yellow"
            ]
          }
        ],
        "images": [
          {
            "id": 2155956699172,
            "product_id": 562405015588,
            "position": 1,
            "created_at": "2018-03-20T14:16:17-04:00",
            "updated_at": "2019-11-15T23:59:46-05:00",
            "alt": null,
            "width": 1528,
            "height": 1528,
            "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/Hanes_50_50_T-shirt-lime-A.png?v=1573880386",
            "variant_ids": [
              7162531512356
            ],
            "admin_graphql_api_id": "gid://shopify/ProductImage/2155956699172"
          },
          {
            "id": 2155957157924,
            "product_id": 562405015588,
            "position": 2,
            "created_at": "2018-03-20T14:16:20-04:00",
            "updated_at": "2019-11-15T23:59:46-05:00",
            "alt": null,
            "width": 1528,
            "height": 1528,
            "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/Hanes_50_50_T-shirt-lime-B.png?v=1573880386",
            "variant_ids": [],
            "admin_graphql_api_id": "gid://shopify/ProductImage/2155957157924"
          },
          {
            "id": 2155957387300,
            "product_id": 562405015588,
            "position": 3,
            "created_at": "2018-03-20T14:16:22-04:00",
            "updated_at": "2019-11-15T23:59:46-05:00",
            "alt": null,
            "width": 1528,
            "height": 1528,
            "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/Hanes_50_50_T-shirt-yellow-A.png?v=1573880386",
            "variant_ids": [
              7162531545124
            ],
            "admin_graphql_api_id": "gid://shopify/ProductImage/2155957387300"
          },
          {
            "id": 2155957583908,
            "product_id": 562405015588,
            "position": 4,
            "created_at": "2018-03-20T14:16:25-04:00",
            "updated_at": "2019-11-15T23:59:46-05:00",
            "alt": null,
            "width": 1528,
            "height": 1528,
            "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/Hanes_50_50_T-shirt-yellow-B.png?v=1573880386",
            "variant_ids": [],
            "admin_graphql_api_id": "gid://shopify/ProductImage/2155957583908"
          }
        ],
        "image": {
          "id": 2155956699172,
          "product_id": 562405015588,
          "position": 1,
          "created_at": "2018-03-20T14:16:17-04:00",
          "updated_at": "2019-11-15T23:59:46-05:00",
          "alt": null,
          "width": 1528,
          "height": 1528,
          "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/Hanes_50_50_T-shirt-lime-A.png?v=1573880386",
          "variant_ids": [
            7162531512356
          ],
          "admin_graphql_api_id": "gid://shopify/ProductImage/2155956699172"
        }
      }
    ],
    "matched_rules": [
      {
        "logic": [
          {
            "rules": [
              {
                "type": "product",
                "operator": "contains_any",
                "value": "",
                "products": [
                  {
                    "product_id": 562407407652,
                    "variant_ids": []
                  },
                  {
                    "product_id": 562405015588,
                    "variant_ids": []
                  },
                  {
                    "product_id": 562399838244,
                    "variant_ids": []
                  }
                ]
              }
            ]
          }
        ],
        "output": [
          {
            "type": "product",
            "products": [
              {
                "product_id": 591006728228,
                "variant_ids": []
              },
              {
                "product_id": 4484974870564,
                "variant_ids": []
              },
              {
                "product_id": 4484976148516,
                "variant_ids": []
              }
            ]
          }
        ],
        "exit_if_matched": true
      }
    ],
    "unmatched_rules": [],
    "unevaluated_rules": [
      {
        "logic": [
          {
            "rules": [
              {
                "type": "cart_subtotal",
                "operator": "greater_than",
                "value": "50"
              }
            ]
          }
        ],
        "output": [
          {
            "type": "endpoint",
            "endpoint": "/products/recommended"
          }
        ],
        "exit_if_matched": true
      }
    ],
    "filtered_oos_products": [
      {
        "id": 591006728228,
        "title": "Classic Beanie",
        "body_html": "Classic Beanie",
        "vendor": "Example Brand",
        "product_type": "",
        "created_at": "2018-03-30T11:53:26-04:00",
        "handle": "classic-beanie",
        "updated_at": "2020-12-24T14:40:35-05:00",
        "published_at": "2020-01-28T16:11:45-05:00",
        "template_suffix": "",
        "published_scope": "web",
        "tags": "clothing",
        "admin_graphql_api_id": "gid://shopify/Product/591006728228",
        "variants": [
          {
            "id": 7321573425188,
            "product_id": 591006728228,
            "title": "Default Title",
            "price": "15.00",
            "sku": "BEANIE1",
            "position": 1,
            "inventory_policy": "deny",
            "compare_at_price": null,
            "fulfillment_service": "manual",
            "inventory_management": "shopify",
            "option1": "Default Title",
            "option2": null,
            "option3": null,
            "created_at": "2018-03-30T11:53:26-04:00",
            "updated_at": "2020-12-24T14:40:35-05:00",
            "taxable": true,
            "barcode": "",
            "grams": 0,
            "image_id": null,
            "weight": 0,
            "weight_unit": "lb",
            "inventory_item_id": 7334298255396,
            "inventory_quantity": 0,
            "old_inventory_quantity": 0,
            "requires_shipping": true,
            "admin_graphql_api_id": "gid://shopify/ProductVariant/7321573425188"
          }
        ],
        "options": [
          {
            "id": 872156528676,
            "product_id": 591006728228,
            "name": "Title",
            "position": 1,
            "values": [
              "Default Title"
            ]
          }
        ],
        "images": [
          {
            "id": 2245076910116,
            "product_id": 591006728228,
            "position": 1,
            "created_at": "2018-03-30T11:53:29-04:00",
            "updated_at": "2019-11-15T23:59:46-05:00",
            "alt": null,
            "width": 1130,
            "height": 1112,
            "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/Beanie-black.png?v=1573880386",
            "variant_ids": [],
            "admin_graphql_api_id": "gid://shopify/ProductImage/2245076910116"
          }
        ],
        "image": {
          "id": 2245076910116,
          "product_id": 591006728228,
          "position": 1,
          "created_at": "2018-03-30T11:53:29-04:00",
          "updated_at": "2019-11-15T23:59:46-05:00",
          "alt": null,
          "width": 1130,
          "height": 1112,
          "src": "https://cdn.shopify.com/s/files/1/0011/0746/0132/products/Beanie-black.png?v=1573880386",
          "variant_ids": [],
          "admin_graphql_api_id": "gid://shopify/ProductImage/2245076910116"
        }
      }
    ],
    "filtered_input_products": [],
    "errors": []
  }
}

400 Bad Request

{
  "error": "Missing key"
}
See something that needs updating? Suggest an edit