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:

  • Advanced
  • Pro
  • 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.

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

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

For more details about the API features, see the resources below.

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 with guaranteed backward compatibility.

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

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://STORENAME.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://STORENAME.mycashflow.fi or https://STORENAME.fonectanverkkokauppa.fi. Calls to custom domains are ignored.

Installation and Connection

First install the API 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://STORENAME.mycashflow.fi/api.

Once you have installed the API extension, you need to create an API user. The API user account's credentials are used to authenticate requests to the API (see Authentication and Security).

  1. Go to the Account » Users page of the admin panel.
  2. Under API accounts press Create account.
  3. Enter the user name and email of the API user.

The user will be automatically given an API key, which is used as the password when authenticating a request. If you need to create a new API key, check the Create new password box, then press Save.

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.

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/api/v1 or https://STORENAME.fonectanverkkokauppa.fi/api/v1.

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.

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:

  • 200: Request was successful.
  • 201: The item was created.
  • 204: No content

Client error:

  • 400: Bad Request
  • 401: Unauthorized
  • 404: Not Found
  • 422: Unprocessable Entity

Server error:

  • 500: Internal Server Error
  • 503: Service Unavailable
  • 5xx: Other connection errors

Response 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 a 422 Unprocessable Entity error was 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,
    }
}

The MyCashflow API uses two methods of reporting errors:

  1. HTTP headers: if a requested resource was not found, or an unknown action was used, an HTTP error code will be returned. See section Headers of the Responses chapter for possible error codes.
  2. The 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.

Below is a JSON example of an error message returned by a PATCHrequest. Each field affected by errors will have its own array of error messages, with the field name as a key:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8
Content-Length: undefined
{
  errors: {
    name: [
      "Value for 'name' is required."
    ],
    price: [
      "Value for 'price' must be greater than or equal to 0."
    ]
  }
}

The MyCashflow API contains an interactive API console, where you can test the features of our API.

You can find the API console in the store's admin panel at Account » Apps » API » API Console. Access the console through the Browse link at the top.

Read more about using the API console.

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

Read more about the JavaScript client in Github.

Brands

Collection of brands.

get

Retrieve a list of brands.

post

Create new brand.

Specific brand

get

Retrieve a specific brand by its unique ID.

patch

Modify the brand.

delete

Delete the brand.

Categories

Collection of categories.

get

Retrieve a list of categories.

post

Create new category.

get

Retrieve a specific category by its external ID.

patch

Modify a category.

Specific category

get

Retrieve a specific category by its unique ID.

patch

Modify the category.

The sub-categories of the designated category.

get

Get list of sub-categories of the designated category.

Collection of the category's visibilities in different versions of the store.

In this endpoint you can control, in which versions the category is shown on the frontend of the store.

get

Retrieve a list of the category's visibilities.

You can also fetch details of the visibilities in the GET /categories?expand=visibilities request.

patch

Change the visibility of the category in different versions.

Orders

Collection of the store's orders

NOTE! The Orders API is in beta testing and available only under /api/v0/orders.

Read more about working with orders ›

get

Retrieve a list of the store's orders.

post

Create new order.

Specific order

get

Retrieve a specific order by its unique ID.

get
post

Run the quick processing for an order. Read more about quick processing.

post

Cancel the order.

post

Archive the order.

Archiving must be enabled in the store.

Read more about archiving orders.

Collection of order comments

post

Submit a new comment (private or public) for the order.

The possible statuses of a payment are the following:

  • OPEN: Only when using a payment link (Checkout and Klarna) and the payment has not been carried out.
  • PENDING_ACTIVATION: The payment has been received, but it has not been activated yet (only with Klarna). Used also with payment links, when the payment has been carried out.
  • PAID: The payment has been activated.
  • REFUNDED: The payment has been refunded in full, after it had been activated.
  • CANCELLED: Payment has been cancelled, before it was activated.
get

Retrieve a specific payment by its unique ID.

You can fetch a list of payments for the order by using /api/v0/orders/{orderId}?expand=payments

post

Activate the payment (used only with Klarna payments, when the payment transaction status is PENDING_ACTIVATION).

The payment status after marking unpaid is PAID.

post

Cancel a payment.

The payment status after marking unpaid is CANCELLED.

post

Mark the payment as paid.

The payment status after marking unpaid is PAID.

post

Mark the payment as unpaid.

The payment status after marking unpaid is OPEN.

post

Register shipment to get address label and possibly tracking code.

Customer Groups

Collection of customer-groups.

get

Retrieve a list of customer-groups.

post

Create new customer-group.

Specific customer-group

get

Retrieve a specific customer-group by its unique ID.

patch

Modify the customer-group.

delete

Delete the customer group.

NOTE! Deleting the customer group does not delete the accounts that belong to it.

Customers

Collection of customers.

get

Retrieve a list of customers.

post

Create new customer.

Specific customer

get

Retrieve a specific customer by its unique ID.

patch

Modify the customer.

Collection of secondary-addresses.

get

Retrieve a list of the customer's secondary shipping addresses.

Email Subscribers

Collection of email-subscribers.

get

Retrieve a list of the store's email subscribers.

post

Subscribe a new email address to the newsletter.

Specific email-subscriber

delete

Unsubscribe an email subscriber.

The subscriber will be removed from the mailing list, but their customer account will be left intact.

Products

Collection of products.

get

Retrieve a list of products. 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.

post

Create new product.

Specific product

get

Retrieve a specific product by its unique ID.

patch

Modify the product.

delete

Delete the product.

Collection of variations.

get

Retrieve all variations of a product.

post

Create new variation for a product.

Specific variation

get

Retrieve a specific variation by its unique ID.

patch

Modify the variation.

delete

Delete the variation.

Collection of the product's option fields

post

Create new option.

get

Retrieve a list of options.

Specific product option.

get

Retrieve a specific product option by its unique ID.

patch

Modify a specific product option.

delete

Delete a specific product option.

The choices of a specific product option.

get

Retrieve all choices of a product option.

post

Create new choice for a product option.

Specific choice

get

Retrieve a single product option choice by its ID.

patch

Modify a product option choice.

delete

Delete a product option choice.

Collection of the product's visibilities in different versions of the store.

In this endpoint you can control, in which versions the product is shown on the frontend of the store.

get

Retrieve a list of the product's visibilities in different versions.

You can also fetch details about the product's visibilities by using the GET /api/v1/products?expand=visibilities request.

patch

Change the product's visibility in different versions.

Collection of the product's multilingual fields.

It is not recommended to use this endpoint to manage the translations of products.

Instead, we recommend that you include the translations array in any POST / PATCH requests, when you need to edit multilingual content.

See further instructions on the Use Cases page.

get

Retrieve a list of the product's multilingual fields in all available languages.

You can also fetch details about the product's multilingual fields by using the GET /api/v1/products?expand=translations request.

patch

Modify the content of any available multilingual fields in the specified language.

Stock Items

Collection of stock items.

Stock items can be attached to products or product variations. One stock item can belong to several products or variations.

Contrary to most resources, stock items are identified in request by the unique product code of the product or variation they belong to.

get

Retrieve a list of all stock items.

Specific stock

get

Retrieve a stock item specified by the unique product code of a product or variation.

patch

Modify a stock item specified by the unique product code of a product or variation.

Suppliers

Collection of suppliers.

get

Retrieve a list of suppliers.

post

Create new supplier.

Specific supplier

get

Retrieve a specific supplier by its unique ID.

patch

Modify the supplier.

delete

Delete the supplier.

Payment Methods

Collection of payment-methods.

get

Retrieve a list of payment-methods.

Specific payment-method

get

Retrieve a specific payment-method by its unique ID.

Shipping Methods

Collection of shipping-methods.

get

Retrieve a list of shipping-methods.

Specific shipping-method

get

Retrieve a specific shipping-method by its unique ID.

Collection of shipping costs for the specified shipping method.

get

Retrieve a list of shipping costs for the specified shipping method.

Versions

Collection of the store's different versions.

get

Retrieve a list of versions.

Specific version

get

Retrieve a specific version by its unique ID.

Images

Collection of the store's product image files.

Product images are always stored in the /tuotekuvat folder of the store's file system.

Images are attached to products, and removed from them, in the following endpoint:

/api/v1/products/{productId}/image-links
get

Retrieve a list of the store's product images.

post

There are 3 alternative ways of adding an image to the store's file system. See further instructions on the Use cases page.

Specific image

get

Retrieve an image file by specifying the image ID.

Specific image

get

Retrieve an image by specifying the filename of the target image.