Reflow API
Reflow has a simple API that lets you fetch your store's subscribers, users and 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. Note that some endpoints require authentication with an API key.
Subscriptions
The following API endpoints will help you integrate Reflow Subscriptions in your project.
Get all Subscription Plans
GET https://api.reflowhq.com/v2/stores/<storeid>/plans/
This API endpoint will return all active subscription plans and prices. Note that only plans that can be subscribed to will show up here. Plans that have been created but are deactivated, archived or deleted will not appear in the list.
Example
// Print all subscription plans of the store
let plans = await fetch(
"https://api.reflowhq.com/v2/stores/267418190/plans/"
).then((r) => r.json());
console.log(plans.data);
Get a Specific Subscription Plan
GET https://api.reflowhq.com/v2/stores/<storeid>/plans/<planid>
This API endpoint will return the details of a single subscription plan. Both active and inactive plans can be requested with this endpoint.
Example
// Print all subscription plans of the store
let plan = await fetch(
"https://api.reflowhq.com/v2/stores/267418190/plans/13156819"
).then((r) => r.json());
console.log(plan);
Auth
The following API endpoints let you retrieve data objects related to the Reflow Auth service.
Get all User Accounts
GET https://api.reflowhq.com/v2/stores/<storeid>/users/
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/v2/stores/<storeid>/users/'
Get a Specific User Account
GET https://api.reflowhq.com/v2/stores/<storeid>/users/<userid>
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/v2/stores/<storeid>/users/<userid>'
Ecommerce
You can use the following API endpoints for integration with Reflow's Ecommerce functionality.
Get all Products
GET https://api.reflowhq.com/v2/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_ascThis sorts products by using the Custom Sort number (which you enter in the [product edit](@site/guide/products.md) 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/v2/stores/267418190/products/"
).then((r) => r.json());
console.log(products.data);
// Print the 10 oldest products
let products = await fetch(
"https://api.reflowhq.com/v2/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/v2/stores/267418190/products/?category=123456789"
).then((r) => r.json());
console.log(products.data);
Get a Specific Product
GET https://api.reflowhq.com/v2/stores/<storeid>/products/<product>
This endpoint will return the product with the given id or handle from a store.
Examples
// Fetch the given product by its id and print its name
let product = await fetch(
"https://api.reflowhq.com/v2/stores/267418190/products/366797633"
).then((r) => r.json());
console.log(product.name);
// Fetch the given product by its handle
let product = await fetch(
"https://api.reflowhq.com/v2/stores/267418190/products/radio-clock"
).then((r) => r.json());
Update a Product
POST https://api.reflowhq.com/v2/stores/<storeid>/products/<product>
Requests to this endpoint require authentication using a Reflow API Key.
Update the existing product with the given id or handle from a store. Add one or more of the following parameters in the request body to select which product properties to update and their new values:
| Parameter | Possible Values | Description |
|---|---|---|
| name | string | The new name of the product. Must be a string between 1 and 128 characters in length. |
| price | integer | The new price of the product. The passed value must be equal to the price in the currency’s smallest unit. To set the product price to $10.00 provide a value of 1000. For zero-decimal currencies, provide the new price without multiplying by 100. For a price of ¥500 provide 500. |
On success the updated product object will be returned, including all the applied changes.
Examples
# Update the given product name and price. The price is in the smallest unit (typically cents).
# Replace <storeid> with the id of your store, <productid> with the id of the product
# 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 '{"name": "The new product name", "price": 123456}' \
'https://api.reflowhq.com/v2/stores/<storeid>/products/<productid>'
Get a Specific Category
GET https://api.reflowhq.com/v2/stores/<storeid>/categories/<category>
This endpoint will return the category with the given id or handle from a store.
Examples
// Fetch the given category by its handle and print its name
let category = await fetch(
"https://api.reflowhq.com/v2/stores/267418190/categories/accessories"
).then((r) => r.json());
console.log(category.name);
Get all Categories
GET https://api.reflowhq.com/v2/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/v2/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/v2/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/v2/stores/267418190/categories?root-category=177837305"
).then((r) => r.json());
printCategoryNames(categories);
Get all Orders
GET https://api.reflowhq.com/v2/stores/<storeid>/orders/
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_canceled | string, true or false | If set, only canceled or non-canceled 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/v2/stores/<storeid>/orders/'
# Print 50 orders with the fulfillment_status "shipped"
curl --header 'Authorization: Bearer <api_key>' \
'https://api.reflowhq.com/v2/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/v2/stores/<storeid>/orders/?created_after=1669852800&created_before=1672531200'
Get a Specific Order
GET https://api.reflowhq.com/v2/stores/<storeid>/orders/<orderid>
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/v2/stores/<storeid>/orders/<orderid>'
Update an Order
POST https://api.reflowhq.com/v2/stores/<storeid>/orders/<orderid>
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](@site/guide/orders.md#managing-order-status). |
| 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](@site/guide/orders.md#managing-order-status). |
| is_canceled | string, true or false | Set the is_canceled property of the order. To learn more about order statuses visit the [order docs](@site/guide/orders.md#managing-order-status). |
| is_archived | string, true or false | Set the is_archived property of the order. To learn more about order statuses visit the [order docs](@site/guide/orders.md#managing-order-status). |
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/v2/stores/<storeid>/orders/<orderid>'
Usage with the Reflow HTML Toolkit
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/v2/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.