MyCashflow API (v1)

Download OpenAPI specification:Download

Introduction

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

MyCashflow API is only available for the following plans:

Advanced
Pro
Enterprise

NOTE: MyCashflow also has support for Zapier for your more lightweight integration needs. See further info at https://support.mycashflow.com/en/user-guide/zapier.

MyCashflow API is recommended to be used in backend clients. Making API credentials public in frontend 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.

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

Any experimental changes will be made to the 0.x.x series which is available under /api/v0.

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://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. Calls to custom domains are ignored.

Do not include a trailing slash in the request URL. The API will return an error if a trailing slash is present.

Installation and Connection

First, install the API extension on the Account » Extensions page of your store's admin panel.

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).

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:

200 Ok
201 Created
204 No content

Client error:

400 Bad Request
401 Unauthorized
404 Not Found
409 Conflict
422 Unprocessable Entity

Server error:

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

Response body

The 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.

Errors

MyCashflow API uses two methods of reporting errors:

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.
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:

Authentication

HTTP Basic Access Authentication

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

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.

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.

Security Scheme Type	HTTP
HTTP Authorization Scheme	basic

Banners

Retrieve a list of banner groups

Authorizations:

HTTP Basic Access Authentication

query Parameters

expand	string Value: "translations" Comma-separated list of expandable sub-resources.
page_size	integer Default: 50 Example: page_size=50 Determines the number of items included on a page of the response list.
page	integer Default: 0 Example: page=2 Determines the page that is retrieved (used only in conjunction with `page_size`).
sort	string Default: "id-asc" Enum: "id-asc" "id-desc" Example: sort=id-asc Determines the sorting of the response list.

Responses

Response samples

200
409
500

Content type

application/json

{"data": [{"id": 1,
"created_at": "2013-06-19T20:41:47+03:00",
"updated_at": "2013-06-19T20:41:47+03:00",
"code": "group-code",
"title": "My banner group",
"translations": [{"language": "en",
"title": "My banner group"
},
{"language": "fi",
"title": "Banneriryhmä"
}
]
}
],
"meta": {"page": 1,
"page_size": 100,
"page_count": 3,
"item_count": 300
}
}

Create a banner group

Authorizations:

HTTP Basic Access Authentication

Request Body schema: application/json

code	string The banner group code. Can be used to identify the banner group in theme files.
title	string The banner group title. If present in both the root of the request body and the `translations` array, the `translations` array will take prevalence.
translations	Array of any[ items ] Array of translations for translatable fields.

Responses

Request samples

Payload

Content type

application/json

{"code": "group-code",
"title": "My banner group",
"translations": [{"language": "en",
"title": "My banner group"
},
{"language": "fi",
"title": "Banneriryhmä"
}
]
}

Response samples

201
409
422
500

Content type

application/json

{"data": {"id": 1,
"created_at": "2013-06-19T20:41:47+03:00",
"updated_at": "2013-06-19T20:41:47+03:00",
"code": "group-code",
"title": "My banner group",
"translations": [{"language": "en",
"title": "My banner group"
},
{"language": "fi",
"title": "Banneriryhmä"
}
]
}
}

Retrieve a banner group

Authorizations:

HTTP Basic Access Authentication

path Parameters

bannerGroupID

required

integer >= 1

Unique identifier for the banner group

query Parameters

expand

string

Value: "translations"

Comma-separated list of expandable sub-resources.

Responses

Response samples

200
409
500

Content type

application/json

{"data": {"id": 1,
"created_at": "2013-06-19T20:41:47+03:00",
"updated_at": "2013-06-19T20:41:47+03:00",
"code": "group-code",
"title": "My banner group",
"translations": [{"language": "en",
"title": "My banner group"
},
{"language": "fi",
"title": "Banneriryhmä"
}
]
}
}

Modify a banner group

Authorizations:

HTTP Basic Access Authentication

path Parameters

bannerGroupID

required

integer >= 1

Unique identifier for the banner group

Request Body schema: application/json

code	string The banner group code. Can be used to identify the banner group in theme files.
title	string The banner group title. If present in both the root of the request body and the `translations` array, the `translations` array will take prevalence.
translations	Array of any[ items ] Array of translations for translatable fields.