MyCashflow API

You can use the MyCashflow REST API to integrate your online store with a number of third-party applications, for example CRMs and accounting software.

The MyCashflow API is only available for the following plans:

  • Medium
  • Max
  • Enterprise

The MyCashflow API is recommended to be used in backend clients. Making API credentials public in front-end clients carries many security issues.

Get started using the API by going through the following documentation. This document will be updated, whenever changes to the API are made.

API Features

Currently, the following actions are possible with the MyCashflow API:

  • Fetching/creating/editing/deleting products 
  • Fetching/creating/editing/deleting product variations
  • Fetching/creating/editing/deleting product options
  • Fetching/editing stock items
  • Fetching/sending images
  • Fetching/creating/editing/deleting suppliers
  • Fetching/creating/editing categories
  • Fetching/creating/editing/deleting brands
  • Fetching/creating/editing/deleting customer groups
  • Fetching/editing customer accounts
  • Fetching payment and shipping methods
  • Fetching shipping costs
  • Fetching/editing store versions

For more details about the API features, see the Actions chapter.

Versioning and Development

The development of the MyCashflow API follows the major.minor.patch scheme.

The current version of the API is located at /api/v1. Any updates to the current 1.x.x series will only entail bug fixes and new features that have been tested.

Any experimental changes will be made to the 0.x.x series, which you should avoid using in live integrations.

Getting Started

All major versions of the API have their own endpoints. The endpoint defines the server path that receives your API requests and responds to them.

The MyCashflow API endpoints are defined according to the following scheme:

https://SHOPNAME.mycashflow.fi/api/v1

The last part of the endpoint address defines the targeted API version.

The API is only available over the default domain https://store-name.mycashflow.fi. Calls to custom domains are ignored.

Installation and Connection

Notify our customer service, if you wish to install the MyCashflow API in your store. We will manually install the API with no extra charge.

Once the API is installed, it will be shown as an extension on the Account » Extensions page of your store's admin panel. When the API is configured, you can access the API reference pages and  the interactive API console  at https://SHOPNAME.mycashflow.fi/api .

In the API extension settings you can manage the API users and authentication credentials:

  1. Select a user account, that is allowed to connect to the API.
    •  
    • The selected user's email address will be used as the username, when authenticating your API calls.
    • Currently it is possible to connect using only one user account.
  2. You can copy the password from the extension settings to authenticate your API calls.
    • If you need to create a new password, check the Create new password box, then press Save.
    • → Your old password will be disabled immediately.

Once the API extension is installed, you can access the API console from the bottom of the extension settings page. You need to be logged in to your online store's admin panel, in order to access the API reference pages.

Authentication and Security

Requirements

All requests must be authenticated by using  HTTP Basic access authentication . Any requests with missing or incorrect credentials will return a 401 Unauthorized response.

The MyCashflow API is only available through an encrypted HTTPS  connection. Any requests using an unencrypted connection will return a 400 Bad Request response. Using HTTPS guarantees that your authentication credentials are always hidden from malicious third parties.

All API calls must be made to the store's default URL, ie. https://STORENAME.mycashflow.fi.

Credentials

The API credentials for your store are available in the settings of the API extension at Account »  Extensions  »  API or on the Account » Users page in the API accounts column.

One MyCashflow store may have several API users, so make sure you use the correct credentials for each purpose.

Use dedicated credentials for your clients

It is recommended to create a dedicated set of API credentials for each individual client program.

If you don't have access to the admin panel of the store, contact the store owner for your API credentials.

Errors

The MyCashflow API uses two methods of reporting errors:

  1. HTTP headers (see section Headers of the Responses chapter for possible error codes): if a requested resource was not found, or an unknown action was used, an HTTP error code will be returned.

  2. Errors JSON element: if the request contains errors, the response JSON will contain the errors element, which provides details about the error.

    • For example, errors will be reported as JSON, if you try to add a product without a name, or insert unsupported data into certain fields.

Resources

The resources available through the MyCashflow API are listed in this chapter.

Expansion

Some resources have sub-resources that can be optionally included in the response content. For example, when fetching products you can choose to include the product's variations in the response:

GET /products/{id}?expand=variations

You can also expand several sub-resources in a single API request:

GET /products/{id}?expand=variations,visibilities,translations

You can read more about expansion in the descriptions of the available API resources.

  Brands
Name Type Writable Validation
id integer No  
created_at datetime No  
updated_at datetime No  
name string Yes required
description string Yes string

  Categories
Name Type Writable Validation
id integer No  
external_id integer Yes integer
created_at datetime No  
updated_at datetime No  
parent_id integer Yes integer
parent_sort integer Yes integer
name string Yes required
description string Yes string
visibilities integer Yes  
type string No  
default_template string Yes string

  Customer groups
Name Type Writable Validation
id integer No  
created_at datetime No  
updated_at datetime No  
name string Yes required

  Customers
Name Type Writable Validation
id integer No  
created_at datetime No  
updated_at datetime No  
last_login_at datetime No  
login_allowed boolean Yes  
external_id string Yes string
email string Yes required, email

  Products
Name Type Writable Validation
id integer No  
created_at datetime No  
updated_at datetime No  
product_code string Yes string
supplier_code string Yes string
name string Yes required
description string Yes string
information string Yes string
keywords string Yes string
price price Yes min value: 0
purchase_price price Yes min value: 0
available_from datetime Yes  
available_to datetime Yes  
vat_rate float Yes numeric
weight weight Yes min value: 0
warranty string Yes string

The following expandable subresources are available for products:

  • Variations
  • Visibilities
  • Translations
  • Image links
  • Category links

Read more about expansion.

  Product options
Name Type Writable Validation
id integer No  
created_at datetime No  
updated_at datetime No  
product_id integer Only on create required
sort integer Yes  
type string Yes required
name string Yes required
help string Yes  

The following types are accepted for product option:

  • H3
  • TEXT
  • TEXTAREA
  • SELECT
  • RADIO
  • CHECKBOX
  • FILE

  Product option choices
Name Type Writable Validation
id integer No  
created_at datetime No  
updated_at datetime No  
product_id integer Only on create required
option_id integer Only on create required
sort string Yes  
name string Yes required
price string Yes  

Choices can be created only for selectable options i.e. where type is one of SELECT, RADIO or CHECKBOX.

  Stock
Name Type Writable Validation
id integer No  
created_at datetime No  
updated_at datetime No  
sku string Yes  
barcode string Yes  
location string Yes  
enabled boolean Yes  
quantity integer Yes integer
reserved integer No  
balance integer No  
balance_limit integer Yes integer
balance_alert boolean No  
backorder_enabled boolean Yes  
backorder_estimate string Yes max length: 5
code string No  
product_id integer No  
variation_id integer No  

The code, product_id and variation_id fields only contain data, if the stock item has been attached to a product or variation.

  Suppliers
Name Type Writable Validation
id integer No  
created_at datetime No  
updated_at datetime No  
name string Yes required
phone string Yes phone
email string Yes email
url string Yes url

  Variations
Name Type Writable Validation
id integer No  
created_at datetime No  
updated_at datetime No  
product_id integer No The product must exist, and it must not have stock tracking enabled.
product_code string Yes string
name string Yes required
price price Yes min value: 0
purchase_price price Yes min value: 0
weight weight Yes min value: 0

  Translations

When fetching products, the default response will be in the default language of the store. You can set the language of the response by using the Translations subresource.

Name

Type

Writable

Validation

language

string

No

name

string

Yes

description

string

Yes

information

string

Yes

  Visibilities

Information about a product's visibility in different store versions.

Name

Type

Writable

Validation

version_id

integer

No

is_visible

boolean

Yes

  Image links

Returns URL's for the product's image files.

Name

Type

Writable

Validation

version_id

integer

product_id

integer

 
image_id integer    
sort integer    

  Category links

Returns information about the product's categories.

Name

Type

Writable

Validation

version_id

integer

category_id

integer

 
category_sort integer    
product_id integer    
product_sort integer    

  Versions
Name Type Writable Validation
id integer No  
created_at datetime No  
updated_at datetime No  
name string Yes Required
language string No  
url string Yes Must be an existing URL that has been configured for the store.
ssl_enabled boolean Yes The URL of the store must have a valid SSL certificate configured.
shop_name string No  
shop_email string No  
default_country string No  
default_currency string No  
theme string Yes Must be a theme folder that exists in the store's file system.
minimum_order price Yes  
sort integer Yes  

Requests

All requests must have the Accept: application/json HTTP header. If the header is missing, a 406 Not Found response will be returned

Actions

The following API actions are currently available:

  Brands
HTTP verb URL Description
GET /brands Get list of brands
POST /brands Create brand
GET /brands/{id} Get brand
PATCH /brands/{id} Update brand
DELETE /brands/{id} Delete brand
  Categories
HTTP verb URL Description
GET /categories Get list of categories
GET /categories/{id} Get category
GET /categories/external_id={external_id} Get category by its external ID.
PATCH /categories/{id}

Update category (see category resources).

PATCH /categories/external_id={external_id}

Update category by its external ID (see category resources  ).

GET /categories/{id}/subcategories Get list of a category's sub-categories.
POST /categories

Create a new category (see category resources  ).

  Customer groups
HTTP verb URL Description
GET /customer-groups Get list of customer groups
POST /customer-groups Create customer group
GET /customer-groups/{id} Get customer group
PATCH /customer-groups/{id} Update customer group
DELETE /customer-groups/{id} Delete customer group
  Customers
HTTP verb URL Description
GET /customers Get list of customers
GET /customers/{id} Get customer
PATCH /customers/{id} Update customer
GET /customers/{id}/secondary_addresses Get list of customers secondary addresses
  Products
HTTP verb URL Description
GET /products?expand={subresource1, subresource2, ...} Get list of products
GET /products/{id}?expand={subresource1, subresource2, ...} Get product
PATCH /products/{id} Update product
POST /products Create a new product (see product resources).

The following expandable subresources are available:

  Product variations
HTTP Verb URL Description
GET /products/{product_id}/variations Get all variations of a product.
POST /products/{product_id}/variations Create variation for product (see variation resources).
GET /products/{product_id}/variations/{variation_id} Get one variation of a product by its ID.
PATCH /products/{product_id}/variations/{variation_id} Edit a variation.

DELETE

/products/{product_id}/variations/{variation_id}

Delete product variation.

  Product options
HTTP Verb URL Description
GET /products/{product_id}/options Get all options of a single product.
POST /products/{product_id}/options Create option for product (see product option resource).
GET /products/{product_id}/options/{option_id} Get product option by its ID.
PATCH /products/{product_id}/options/{option_id} Edit product option.
DELETE /products/{product_id}/options/{option_id} Delete product option.
GET /products/{product_id}/options/{option_id}/choices Get all choices of single option.
POST /products/{product_id}/options/{option_id}/choices Create choice for product option (see option choices resource).
GET /products/{product_id}/options/{option_id}/choices/{choice_id} Get choice by its ID.
PATCH /products/{product_id}/options/{option_id}/choices/{choice_id} Edit choice.
DELETE /products/{product_id}/options/{option_id}/choices/{choice_id} Delete choice.
  Product category links
HTTP Verb URL Description
GET /products/{product_id}/category-links Get all category links of a single product.
POST /products/{product_id}/category-links Create new category link for product.
DELETE /products/{product_id}/category-links/category_id={category_id} Delete category link.
  Product image links

HTTP Verb URL Description
GET /products/{product_id}/image-links Get all image links of a single product.
POST /products/{product_id}/image-links Create new image link for product.
DELETE /products/{product_id}/image-links/filename={filename} Delete image link by filename.
DELETE /products/{product_id}/image-links/image_id={image_id} Delete image link by image ID.
  Visibilities
HTTP Verb URL Description

GET

/products/{id}/visibilities

Get product visibilities.

PATCH

/products/{id}/visibilities

Update product visibilities (see visibility resources).

GET /categories/{id}/visibilities Get category visibilities.
PATCH /categories/{id}/visibilities Update category visibilities (see visibility resources).
  Translations
HTTP Verb URL Description

GET

/products/{id}/translations

Get product translations.

PATCH

/products/{id}/translations

Update product translations (see translation resources).

  Images

HTTP Verb

URL

Description

GET

/images

Get all images.

GET

/images/{id}

Get single image by the image ID.

GET /images/filename={filename} Get image by its filename.
POST /images

Upload an image to the store's file system.

You can add images in three alternate ways:

  1. By specifying the name of an image already in the store's file system.
    • {"filename":"image.png"}
      
  2. By specifying the remote URL of the image.
    • {"url":"http://www.domain.fi/image.png"}
      
  3. By sending the image in base64 encoded format in the POST request.
    • {"image":
        {
          "filename":"image.png",
          "data":"[base64 encoded file contents]"
        }
      }
      

You can link the image to a product by using the Product image link request.

  Stock

When fetching stock items, use the unique product code (not the ID) to identify the item.

If you are fetching a product variation, use the variation code. The main product's code will not work.

HTTP verb URL Description
GET /stock

Get list of stock items.

This request does not return any products or variations that don't have stock tracking enabled.

GET

/stock/{product_code}

Get stock item.

If the product code is not unique, a 404 Not found response will be returned.

PATCH /stock/{product_code} Update stock item.
  Suppliers
HTTP verb URL Description
GET /suppliers Get list of suppliers
POST /suppliers Create supplier
GET /suppliers/{id} Get supplier
PATCH /suppliers/{id} Update supplier
DELETE /suppliers/{id} Delete supplier
  Payment methods

HTTP Verb

URL

Description

GET

/payment-methods

Get list of payment methods

GET

/payment-methods/{id}

Get payment method

  Shipping methods

HTTP Verb

URL

Description

GET

/shipping-methods

Get list of shipping methods

GET

/shipping-methods/{id}

Get shipping method

GET

/shipping-methods/{id}/costs

Get shipping costs for shipping method

  Versions
HTTP verb URL Description
GET /versions Get list of versions
GET /versions/{id} Get version

Responses

The MyCashflow API uses JSON to deliver any data returned by requests to the API.

Headers

All responses with content have the following HTTP headers:

  • Content-Type: application/json

  • Content-Length

Requests may return the following HTTP status response codes:

  Success
Code Description
200 OK
201 Created
204 No content
  Client error
Code Description
400 Bad Request
401 Unauthorized
404 Not Found
422 Unprocessable Entity
  Server error
Code Description
500 Internal Server Error
503 Service Unavailable
5xx Other connection errors

Body

The MyCashflow API returns the response body for requests in JSON format – provided that the requested resource was found:

  • Details about the response will be included in the meta element.

  • The actual payload of the response is provided inside the data element.

  • In case errors were encountered while processing your request, the errors element will also be present in the response body.

The following demonstrates a JSON response to a request that returns a content body (the example is a response to getting a stock item):

HTTP/1.1 200 OK
Content-Type: application/json
...

{
    "meta":{
        "page":2,
        "page_size":100,
        "page_count":10,
        "item_count":999,
        "next":"?page=3&page_size=100",
        "previous":"?page=1&page_size=100"
    },
	"data": {
		"id": 247,
		"created_at": "2016-06-01T08:00:00+03:00",
		"updated_at": "2016-06-07T15:59:59+03:00",
		"sku": "MCF-24-7",
		"barcode": "0123456789",
		"location": "A-12-34-5",
		"enabled": true,
		"quantity": 7,
		"reserved": 3,
		"balance": 4,
		"balance_limit": 3,
		"balance_alert": false,
		backorder_enabled": true,
		"backorder_estimate": "7 - 14",
		"code": "MYCASHFLOW-247",
		product_id": 24,
		variation_id": 7,
	}
}

Using the API Console

In the API console you can browse the available actions of the MyCashflow API, and check their output for your store.

Using the API console is an excellent way of verifying your API requests. This way you can eliminate errors from your API calls before even typing them into your code.

You can access the API console at https://STORENAME.mycashflow.fi/api/browse .

You need to be logged in to the MyCashflow admin panel, in order to use the API console.

  1. Choose a request from the top menu on the console page. All supported requests are listed in this menu.

  2. Depending on the resource type, enter any required resource identifiers for the request.

  3. Press the GET button.

The response for the selected request is shown on the console. On the bottom of the page you can see the HTTP verb and request address that produce the presented response.

API Clients

Currently MyCashflow provides only a Javascript client for working with our API.

Read more about the Javascript client in Github.