# Reflow API

Reflow has a simple public API that lets you fetch your store's products as JSON. It can be used both in the browser (from any origin), and in scripts when building static versions of your store with site generators or Next.js.

# Get all Products

GET https://api.reflowhq.com/v1/stores/<storeid>/products/

This endpoint will return the latest 20 products in your store. You can modify its behavior with query parameters (all are optional):

Parameter Possible Values Description
page number, defaults to 1 If set, will return the corresponding page number of products.
perpage number, min 1, max 100, defaults to 20 How many products to return per page.
category number, the id of the category If set, only returns products from the given category.
search string, search terms If set, only returns products which contain the search string in the name or product description.
order name_asc, name_desc, price_asc, price_desc, date_asc, date_desc, custom_asc, custom_desc Choose the display order of the products. Defaults to date_desc - products will be shown newest to oldest.

You can also perform multiple sorts by separating order clauses with commas:

Example: ?order=custom_desc,name_asc

This sorts products by using the Custom Sort number (which you enter in the product edit page), and then by name from A to Z. The result is that products with Custom Sort > 0 show before the rest.

# Examples

// Print the 20 newest products
let products = await fetch('https://api.reflowhq.com/v1/stores/267418190/products/').then(r => r.json());
console.log(products.data);

// Print the 10 oldest products
let products = await fetch('https://api.reflowhq.com/v1/stores/267418190/products/?order=date_asc&perpage=10').then(r => r.json());
console.log(products.data);

// Print all the products from a category
let products = await fetch('https://api.reflowhq.com/v1/stores/267418190/products/?category=123456789').then(r => r.json());
console.log(products.data);

# Get a Specific Product

GET https://api.reflowhq.com/v1/stores/<storeid>/products/<productid>

This endpoint will return the product with the given id from a store.

# Examples

// Fetch the given product and print its name
let product = await fetch('https://api.reflowhq.com/v1/stores/267418190/products/366797633').then(r => r.json());
console.log(product.name);

# Get all Categories

GET https://api.reflowhq.com/v1/stores/<storeid>/categories/

This endpoint will return the id, name, and subcategories of all categories in your store, ordered alphabetically and nested recursively. To get the products associated with a specific category, we recommend using the category parameter of the Get all products endpoint.

# Examples


// 1. Fetch all categories and print their names
let categories = await fetch('https://api.reflowhq.com/v1/stores/267418190/categories').then(r => r.json());
console.log(categories.map(c => c.name));

// 2. If your store has subcategories, a bit more work is needed
let printCategoryNames = (categories) => {
  for (let c of categories) {
    console.log(c.name);
    printCategoryNames(c.subcategories);
  }
};

// 2.1 Fetch all categories and print their names recursively
let categories = await fetch('https://api.reflowhq.com/v1/stores/267418190/categories').then(r => r.json());
printCategoryNames(categories);

// 2.2 Fetch only a specific category and its subcategories, and print their names
let categories = await fetch('https://api.reflowhq.com/v1/stores/267418190/categories?root-category=177837305').then(r => r.json());
printCategoryNames(categories);

# Get all Orders PRO Feature

GET https://api.reflowhq.com/v1/stores/<storeid>/orders/

Authentication Required

Requests to this endpoint require authentication using a Reflow API Key.

This endpoint will return the latest 20 orders in your store. You can modify its behavior with query parameters (all are optional):

Parameter Possible Values Description
page number, defaults to 1 If set, will return the corresponding page number of orders.
perpage number, min 1, max 100, defaults to 20 How many orders to return per page.
payment_status string, pending paid failed refunded If set, only orders with this payment_status will be returned.
fulfillment_status string, unfulfilled shipped ready_for_pickup delivered returned If set, only orders with this fulfillment_status will be returned.
is_cancelled string, true or false If set, only cancelled or non-cancelled orders will be returned.
is_archived string, true or false If set, only archived or non-archived orders will be returned.
customer_email string, valid email address Only return orders where the customer has this email address.
created_after number, unix timestamp If set, only orders created after this time will be returned.
created_before number, unix timestamp If set, only orders created before this time will be returned.

# Examples

# In the following examples, replace <storeid> with the id of your store 
# and <api_key> with an api key string token.

# Print the 20 newest orders
curl --header 'Authorization: Bearer <api_key>' \
     'https://api.reflowhq.com/v1/stores/<storeid>/orders/'

# Print 50 orders with the fulfillment_status "shipped"
curl --header 'Authorization: Bearer <api_key>' \
     'https://api.reflowhq.com/v1/stores/<storeid>/orders/?perpage=50&fulfillment_status=shipped'

# Print orders created in the period between two dates
curl --header 'Authorization: Bearer <api_key>' \
     'https://api.reflowhq.com/v1/stores/<storeid>/orders/?created_after=1669852800&created_before=1672531200'

# Get a Specific Order PRO Feature

GET https://api.reflowhq.com/v1/stores/<storeid>/orders/<orderid>

Authentication Required

Requests to this endpoint require authentication using a Reflow API Key.

This endpoint will return the order with the given id from a store.

# Examples

# Fetch the given order and print its status
# Replace <storeid> with the id of your store, <orderid> with the id of 
# the order you want to fetch, and <api_key> with an api key string token.
curl --header 'Authorization: Bearer <api_key>' \
     'https://api.reflowhq.com/v1/stores/<storeid>/orders/<orderid>'

# Update an Order PRO Feature

POST https://api.reflowhq.com/v1/stores/<storeid>/orders/<orderid>

Authentication Required

Requests to this endpoint require authentication using a Reflow API Key.

Update the existing order with the given id from a store. The updated property needs to be added in the request body.

Parameter Possible Values Description
payment_status string, pending paid failed refunded The new payment_status for the order.

To learn more about order statuses visit the order docs.
fulfillment_status string, unfulfilled shipped ready_for_pickup delivered returned The new fulfillment_status for the order.

To learn more about order statuses visit the order docs.
is_cancelled string, true or false Set the is_cancelled property of the order.

To learn more about order statuses visit the order docs.
is_archived string, true or false Set the is_archived property of the order.

To learn more about order statuses visit the order docs.

On success the updated order object will be returned, including all the applied changes.

# Examples

# Update the given order fulfillment_status to "shipped".
# Replace <storeid> with the id of your store, <orderid> with the id of the order 
# you want to update, and <api_key> with an api key string token.
curl --header 'Authorization: Bearer <api_key>' \
     --header 'Content-Type: application/json' \
     -X POST --data '{"fulfillment_status": "shipped"}' \
     'https://api.reflowhq.com/v1/stores/<storeid>/orders/<orderid>'

# Get all Users Accounts PRO Feature

GET https://api.reflowhq.com/v1/stores/<storeid>/users/

Authentication Required

Requests to this endpoint require authentication using a Reflow API Key.

This endpoint will return the latest 20 users registered in your store. You can modify its behavior with query parameters (all are optional):

Parameter Possible Values Description
page number, defaults to 1 If set, will return the corresponding page number of users.
perpage number, min 1, max 100, defaults to 20 How many users to return per page.

# Examples

# In the following examples, replace <storeid> with the id of your store 
# and <api_key> with an api key string token.

# Print all of the users
curl --header 'Authorization: Bearer <api_key>' \
     'https://api.reflowhq.com/v1/stores/<storeid>/users/'

# Get a Specific User Account PRO Feature

GET https://api.reflowhq.com/v1/stores/<storeid>/users/<userid>

Authentication Required

Requests to this endpoint require authentication using a Reflow API Key.

This endpoint will return the user with the given id from a store.

# Examples

# Fetch the given user account
# Replace <storeid> with the id of your store, <userid> with the id of 
# the user you want to fetch, and <api_key> with an api key string token.
curl --header 'Authorization: Bearer <api_key>' \
     'https://api.reflowhq.com/v1/stores/<storeid>/users/<userid>'

# Usage with the Reflow Library

If you have the Reflow JS file included in a web page, you can use a convenience wrapper that gives you direct access to the API, without having to pass the full API URL and store id:

// Fetch a product and print its name using the Reflow library.
// https://cdn.reflowhq.com/v1/toolkit.min.js has been included in the page.
let product = await Reflow.api('/products/366797633');
console.log(product.name);

// Print the 20 newest products
let product = await Reflow.api('/products/');
console.log(product.data);

This way you can retrieve your product data and build entirely custom store experiences, but still add an Add to Cart button and a Shopping Cart so that the Reflow toolkit does the heavy lifting.