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:

  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:

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

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

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": [
        ]
      }
    ],
  • "meta": {
    • "page": 1,
    • "page_size": 100,
    • "page_count": 3,
    • "item_count": 300
    }
}

Create a 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.

Responses

Request samples

Content type
application/json
{
  • "code": "group-code",
  • "title": "My banner group",
  • "translations": [
    • {
      • "language": "en",
      • "title": "My banner group"
      },
    • {
      • "language": "fi",
      • "title": "Banneriryhmä"
      }
    ]
}

Response samples

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": [
      • {
        },
      • {
        }
      ]
    }
}

Retrieve a banner group

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

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": [
      • {
        },
      • {
        }
      ]
    }
}

Modify a banner group

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.

Responses