logo
Documentation Powered by ReDoc

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

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

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

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

Array of translations for translatable fields.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "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

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

Content type
application/json
{
  • "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

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

Array of translations for translatable fields.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "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": [
    ]
}

Delete a banner group

Authorizations:
HTTP Basic Access Authentication
path Parameters
bannerGroupID
required
integer >= 1

Unique identifier for the banner group

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Retrieve a list of banners.

Authorizations:
HTTP Basic Access Authentication
query Parameters
expand
string
Enum: "translations" "visibilities"

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

Create a banner

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
group_id
integer

The ID of the banner group this banner belongs to

sort
integer

A number that represents the banner's position in the banner group relative to other banners.

code
string

The banner's individual code. Set in the banner form's Codename field.

title
string

The banner's title. If present in both the root of the request body and the translations array, the translations array will take prevalence.

content
string

The banner's text/HTML content. If present in both the root of the request body and the translations array, the translations array will take prevalence.

visible_from
string <date>

The date when the banner becomes visible in the store.

visible_to
string <date>

The date when the banner is hidden.

file
string

The banner image. Enter only the filename of the image. The image file must reside in the store's file archive, and cannot be sent in the same request, with which you create or update a banner. The default path of the images is the files/tuotekuvat directory.

link
string

The banner link. If present in both the root of the request body and the translations array, the translations array will take prevalence.

translations
Array of any

An array of translation objects that contain content for any multilingual fields of the banner.

Responses

Request samples

Content type
application/json
{
  • "group_id": 4,
  • "sort": 1,
  • "code": "new-discounts",
  • "title": "New discounts for the summer",
  • "content": "<p>We have some exciting stuff for you this summer!</p>",
  • "visible_from": "2018-07-01",
  • "visible_to": "2018-08-01",
  • "file": "discounts.jpg",
  • "link": "/campaigns/43",
  • "translations": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "group_id": 4,
  • "sort": 1,
  • "code": "new-discounts",
  • "title": "New discounts for the summer",
  • "content": "<p>We have some exciting stuff for you this summer!</p>",
  • "visible_from": "2018-07-01",
  • "visible_to": "2018-08-01",
  • "file": "discounts.jpg",
  • "link": "/campaigns/43",
  • "translations": [
    ]
}

Retrieve a banner

Authorizations:
HTTP Basic Access Authentication
path Parameters
bannerID
required
integer >= 1

Unique identifier for the banner

query Parameters
expand
string
Enum: "translations" "visibilities"

Comma-separated list of expandable sub-resources.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "group_id": 4,
  • "sort": 1,
  • "code": "new-discounts",
  • "title": "New discounts for the summer",
  • "content": "<p>We have some exciting stuff for you this summer!</p>",
  • "visible_from": "2018-07-01",
  • "visible_to": "2018-08-01",
  • "file": "discounts.jpg",
  • "link": "/campaigns/43",
  • "translations": [
    ]
}

Modify a banner

Authorizations:
HTTP Basic Access Authentication
path Parameters
bannerID
required
integer >= 1

Unique identifier for the banner

Request Body schema: application/json
group_id
integer

The ID of the banner group this banner belongs to

sort
integer

A number that represents the banner's position in the banner group relative to other banners.

code
string

The banner's individual code. Set in the banner form's Codename field.

title
string

The banner's title. If present in both the root of the request body and the translations array, the translations array will take prevalence.

content
string

The banner's text/HTML content. If present in both the root of the request body and the translations array, the translations array will take prevalence.

visible_from
string <date>

The date when the banner becomes visible in the store.

visible_to
string <date>

The date when the banner is hidden.

file
string

The banner image. Enter only the filename of the image. The image file must reside in the store's file archive, and cannot be sent in the same request, with which you create or update a banner. The default path of the images is the files/tuotekuvat directory.

link
string

The banner link. If present in both the root of the request body and the translations array, the translations array will take prevalence.

translations
Array of any

An array of translation objects that contain content for any multilingual fields of the banner.

Responses

Request samples

Content type
application/json
{
  • "group_id": 4,
  • "sort": 1,
  • "code": "new-discounts",
  • "title": "New discounts for the summer",
  • "content": "<p>We have some exciting stuff for you this summer!</p>",
  • "visible_from": "2018-07-01",
  • "visible_to": "2018-08-01",
  • "file": "discounts.jpg",
  • "link": "/campaigns/43",
  • "translations": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "group_id": 4,
  • "sort": 1,
  • "code": "new-discounts",
  • "title": "New discounts for the summer",
  • "content": "<p>We have some exciting stuff for you this summer!</p>",
  • "visible_from": "2018-07-01",
  • "visible_to": "2018-08-01",
  • "file": "discounts.jpg",
  • "link": "/campaigns/43",
  • "translations": [
    ]
}

Delete a banner

Authorizations:
HTTP Basic Access Authentication
path Parameters
bannerID
required
integer >= 1

Unique identifier for the banner

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Retrieve a banner designated by its banner code

Authorizations:
HTTP Basic Access Authentication
path Parameters
bannerCode
required
string
Example: bannerCode

Banner code

query Parameters
expand
string
Enum: "translations" "visibilities"

Comma-separated list of expandable sub-resources.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "group_id": 4,
  • "sort": 1,
  • "code": "new-discounts",
  • "title": "New discounts for the summer",
  • "content": "<p>We have some exciting stuff for you this summer!</p>",
  • "visible_from": "2018-07-01",
  • "visible_to": "2018-08-01",
  • "file": "discounts.jpg",
  • "link": "/campaigns/43",
  • "translations": [
    ]
}

Modify a banner designated by its banner code

Authorizations:
HTTP Basic Access Authentication
path Parameters
bannerCode
required
string
Example: bannerCode

Banner code

Request Body schema: application/json
group_id
integer

The ID of the banner group this banner belongs to

sort
integer

A number that represents the banner's position in the banner group relative to other banners.

code
string

The banner's individual code. Set in the banner form's Codename field.

title
string

The banner's title. If present in both the root of the request body and the translations array, the translations array will take prevalence.

content
string

The banner's text/HTML content. If present in both the root of the request body and the translations array, the translations array will take prevalence.

visible_from
string <date>

The date when the banner becomes visible in the store.

visible_to
string <date>

The date when the banner is hidden.

file
string

The banner image. Enter only the filename of the image. The image file must reside in the store's file archive, and cannot be sent in the same request, with which you create or update a banner. The default path of the images is the files/tuotekuvat directory.

link
string

The banner link. If present in both the root of the request body and the translations array, the translations array will take prevalence.

translations
Array of any

An array of translation objects that contain content for any multilingual fields of the banner.

Responses

Request samples

Content type
application/json
{
  • "group_id": 4,
  • "sort": 1,
  • "code": "new-discounts",
  • "title": "New discounts for the summer",
  • "content": "<p>We have some exciting stuff for you this summer!</p>",
  • "visible_from": "2018-07-01",
  • "visible_to": "2018-08-01",
  • "file": "discounts.jpg",
  • "link": "/campaigns/43",
  • "translations": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "group_id": 4,
  • "sort": 1,
  • "code": "new-discounts",
  • "title": "New discounts for the summer",
  • "content": "<p>We have some exciting stuff for you this summer!</p>",
  • "visible_from": "2018-07-01",
  • "visible_to": "2018-08-01",
  • "file": "discounts.jpg",
  • "link": "/campaigns/43",
  • "translations": [
    ]
}

Delete a banner designated by its banner code

Authorizations:
HTTP Basic Access Authentication
path Parameters
bannerCode
required
string
Example: bannerCode

Banner code

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Brands

Retrieve a list of brands

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

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Retrieve a brand

Authorizations:
HTTP Basic Access Authentication
path Parameters
brandID
required
integer >= 1

Unique identifier for the brand

query Parameters
expand
string
Value: "translations"

Comma-separated list of expandable sub-resources.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "name": "Bernard's",
  • "description": "Quality clothes from Bernard's",
  • "seo_title": "Document title",
  • "seo_page_title": "Page title",
  • "seo_meta_description": "Meta description",
  • "translations": [
    ],
  • "visibilities": [
    ]
}

Modify a brand

Authorizations:
HTTP Basic Access Authentication
path Parameters
brandID
required
integer >= 1

Unique identifier for the brand

Request Body schema: application/json
name
required
string

The brand name

description
string

The brand description. Accepts HTML content.

seo_title
string

The SEO document title. Shown, for example, in Google search results as the title.

seo_page_title
string

The SEO page title. Shown on the page, in place of the usual page title, if set.

seo_meta_description
string

The SEO meta description. Shown, for example, in Google search results as the page description.

translations
Array of any

An array of translation objects that contain content for any multilingual fields of the brand.

Responses

Request samples

Content type
application/json
{
  • "name": "Bernard's",
  • "description": "Quality clothes from Bernard's",
  • "seo_title": "Document title",
  • "seo_page_title": "Page title",
  • "seo_meta_description": "Meta description",
  • "translations": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "name": "Bernard's",
  • "description": "Quality clothes from Bernard's",
  • "seo_title": "Document title",
  • "seo_page_title": "Page title",
  • "seo_meta_description": "Meta description",
  • "translations": [
    ],
  • "visibilities": [
    ]
}

Delete a brand

Authorizations:
HTTP Basic Access Authentication
path Parameters
brandID
required
integer >= 1

Unique identifier for the brand

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Campaigns

Retrieve a list of campaigns

Authorizations:
HTTP Basic Access Authentication
query Parameters
expand
string
Enum: "prices" "translations" "visibilities"

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

Retrieve a campaign

Authorizations:
HTTP Basic Access Authentication
path Parameters
campaignID
required
integer >= 1

Unique identifier for the campaign

query Parameters
expand
string
Enum: "prices" "translations" "visibilities"

Comma-separated list of expandable sub-resources.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "published": true,
  • "conditions": {
    },
  • "discounts": {
    },
  • "page": {
    },
  • "translations": [
    ]
}

Modify a campaign

Authorizations:
HTTP Basic Access Authentication
path Parameters
campaignID
required
integer >= 1

Unique identifier for the campaign

Request Body schema: application/json
published
boolean

Determines whether the campaign is published or not. With the value true the campaign is published in the versions that are selected in the campaign settings.

translations
Array of any

Responses

Request samples

Content type
application/json
{
  • "published": true,
  • "translations": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "published": true,
  • "conditions": {
    },
  • "discounts": {
    },
  • "page": {
    },
  • "translations": [
    ]
}

Change campaign prices

Update the discount prices of campaign products. NOTE: The product discount row is identified by using a combination of the resource id and quantity. For example - to change the price of a variation, use a combination of product_id, variation_id and quantity, - for product downloads, use product_id, download_id and quantity.

Authorizations:
HTTP Basic Access Authentication
path Parameters
campaignID
required
integer >= 1

Unique identifier for the campaign

Request Body schema: application/json
Array ()
any

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Delete campaign prices

Remove a product discount from a campaign. NOTE: The product discount row is identified by using a combination of the resource id and quantity. For example

  • to remove the price of a variation, use a combination of product_id, variation_id and quantity, - for product downloads, use product_id, download_id and quantity.
Authorizations:
HTTP Basic Access Authentication
path Parameters
campaignID
required
integer >= 1

Unique identifier for the campaign

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Categories

Retrieve a list of categories

Authorizations:
HTTP Basic Access Authentication
query Parameters
expand
string
Enum: "translations" "visibilities"

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

Retrieve a category

Authorizations:
HTTP Basic Access Authentication
path Parameters
categoryID
required
integer >= 1

Unique identifier for the category

query Parameters
expand
string
Enum: "translations" "visibilities"

Comma-separated list of expandable sub-resources.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "parent_id": 1,
  • "parent_sort": 4,
  • "name": "Pants",
  • "description": "<p>Category description content</p>",
  • "default_template": "category-front",
  • "external_id": 56,
  • "translations": [
    ]
}

Modify a product category

Authorizations:
HTTP Basic Access Authentication
path Parameters
categoryID
required
integer >= 1

Unique identifier for the category

Request Body schema: application/json
parent_id
required
integer

The parent category's ID

parent_sort
integer

An integer that determines the category's location relative to the parent category's other child categories

name
required
string

You can provide the name of the category in either the main POST / PATCH body or in the translations array, when managing multilingual content.

description
string

The category description.

default_template
string
Enum: "category-front" "product-list" "homepage"

The display type of the product category

external_id
integer

The category's ID in an external system

translations
Array of any

An array of translation objects, which contain content for any multilingual fields of the category.

Responses

Request samples

Content type
application/json
{
  • "parent_id": 1,
  • "parent_sort": 4,
  • "name": "Pants",
  • "description": "<p>Category description content</p>",
  • "default_template": "category-front",
  • "external_id": 56,
  • "translations": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "parent_id": 1,
  • "parent_sort": 4,
  • "name": "Pants",
  • "description": "<p>Category description content</p>",
  • "default_template": "category-front",
  • "external_id": 56,
  • "translations": [
    ]
}

Delete a product category

Authorizations:
HTTP Basic Access Authentication
path Parameters
categoryID
required
integer >= 1

Unique identifier for the category

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Retrieve a category by its external ID

Authorizations:
HTTP Basic Access Authentication
path Parameters
externalID
required
string

The category's external ID

query Parameters
expand
string
Enum: "translations" "visibilities"

Comma-separated list of expandable sub-resources.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "parent_id": 1,
  • "parent_sort": 4,
  • "name": "Pants",
  • "description": "<p>Category description content</p>",
  • "default_template": "category-front",
  • "external_id": 56,
  • "translations": [
    ]
}

Modify a category designated by its external ID

Authorizations:
HTTP Basic Access Authentication
path Parameters
externalID
required
string

The category's external ID

Request Body schema: application/json
parent_id
required
integer

The parent category's ID

parent_sort
integer

An integer that determines the category's location relative to the parent category's other child categories

name
required
string

You can provide the name of the category in either the main POST / PATCH body or in the translations array, when managing multilingual content.

description
string

The category description.

default_template
string
Enum: "category-front" "product-list" "homepage"

The display type of the product category

external_id
integer

The category's ID in an external system

translations
Array of any

An array of translation objects, which contain content for any multilingual fields of the category.

Responses

Request samples

Content type
application/json
{
  • "parent_id": 1,
  • "parent_sort": 4,
  • "name": "Pants",
  • "description": "<p>Category description content</p>",
  • "default_template": "category-front",
  • "external_id": 56,
  • "translations": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "parent_id": 1,
  • "parent_sort": 4,
  • "name": "Pants",
  • "description": "<p>Category description content</p>",
  • "default_template": "category-front",
  • "external_id": 56,
  • "translations": [
    ]
}

Retrieve a list of a category's subcategories

Authorizations:
HTTP Basic Access Authentication
path Parameters
categoryID
required
integer >= 1

Unique identifier for the category

query Parameters
expand
string
Enum: "translations" "visibilities"

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

Retrieve a list of a category's visibilities

Authorizations:
HTTP Basic Access Authentication
path Parameters
categoryID
required
integer >= 1

Unique identifier for the category

query Parameters
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
[
  • {
    },
  • {
    }
]

Modify a category's visibilities.

Authorizations:
HTTP Basic Access Authentication
path Parameters
categoryID
required
integer >= 1

Unique identifier for the category

Request Body schema: application/json
version_id
integer >= 1

ID of the version, where the item's visibility is toggled.

is_visible
boolean

true = visible in the designated version, false = not visible.

Responses

Request samples

Content type
application/json
{
  • "version_id": 1,
  • "is_visible": false
}

Response samples

Content type
application/json
{
  • "version_id": 1,
  • "is_visible": false
}

Customers

Retrieve a list of customer groups

Authorizations:
HTTP Basic Access Authentication
query Parameters
expand
string
Enum: "translations" "customer_links"

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

Create a customer group

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
name
required
string

Name of the customer group

Responses

Request samples

Content type
application/json
{
  • "name": "Jälleenmyyjät"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "name": "Jälleenmyyjät",
  • "customer_links": [
    ]
}

Retrieve a customer group

Authorizations:
HTTP Basic Access Authentication
path Parameters
customerGroupID
required
integer >= 1

Unique identifier for the customer group

query Parameters
expand
string
Enum: "translations" "customer_links"

Comma-separated list of expandable sub-resources.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "name": "Jälleenmyyjät",
  • "customer_links": [
    ]
}

Modify a customer group

Authorizations:
HTTP Basic Access Authentication
path Parameters
customerGroupID
required
integer >= 1

Unique identifier for the customer group

Request Body schema: application/json
name
required
string

Name of the customer group

Responses

Request samples

Content type
application/json
{
  • "name": "Jälleenmyyjät"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "name": "Jälleenmyyjät",
  • "customer_links": [
    ]
}

Delete a customer group

Authorizations:
HTTP Basic Access Authentication
path Parameters
customerGroupID
required
integer >= 1

Unique identifier for the customer group

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Remove a customer from a customer group

Authorizations:
HTTP Basic Access Authentication
path Parameters
customerGroupID
required
integer >= 1

Unique identifier for the customer group

customerID
required
integer >= 1

Unique identifier for the customer

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Retrieve a list of customers

Authorizations:
HTTP Basic Access Authentication
query Parameters
expand
string
Value: "customer_groups"

Comma-separated list of expandable sub-resources.

created_at-from
string <date-time>
Example: created_at-from=2017-06-14T20:45:52+03:00

Retrieve customer accounts that have been created on or after the specified date and time. You can provide the datetime value in any of these three following formats:

  • YYYY-MM-DD: 2017-06-14 - YYYY-MM-DDTHH:MM:SS: 2017-06-14T20:45:52 - YYYY-MM-DDTHH:MM:SS+HH:MM: 2017-06-14T20:45:52+03:00
created_at-to
string <date-time>
Example: created_at-to=2017-06-14T20:45:52+03:00

Retrieve customer accounts that have been created on or before the specified date and time. You can provide the datetime value in any of these three following formats:

  • YYYY-MM-DD: 2017-06-14 - YYYY-MM-DDTHH:MM:SS: 2017-06-14T20:45:52 - YYYY-MM-DDTHH:MM:SS+HH:MM: 2017-06-14T20:45:52+03:00
updated_at-from
string <date-time>
Example: updated_at-from=2017-06-14T20:45:52+03:00

Retrieve customer accounts that have been updated on or after the specified date and time. You can provide the datetime value in any of these three following formats:

  • YYYY-MM-DD: 2017-06-14 - YYYY-MM-DDTHH:MM:SS: 2017-06-14T20:45:52 - YYYY-MM-DDTHH:MM:SS+HH:MM: 2017-06-14T20:45:52+03:00
updated_at-to
string <date-time>
Example: updated_at-to=2017-06-14T20:45:52+03:00

Retrieve customer accounts that have been updated on or before the specified date and time. You can provide the datetime value in any of these three following formats:

  • YYYY-MM-DD: 2017-06-14 - YYYY-MM-DDTHH:MM:SS: 2017-06-14T20:45:52 - YYYY-MM-DDTHH:MM:SS+HH:MM: 2017-06-14T20:45:52+03:00
last_login_at-from
string <date-time>
Example: last_login_at-from=2017-06-14T20:45:52+03:00

Retrieve customer accounts that have most recently logged in on or after the specified date and time. You can provide the datetime value in any of these three following formats:

  • YYYY-MM-DD: 2017-06-14 - YYYY-MM-DDTHH:MM:SS: 2017-06-14T20:45:52 - YYYY-MM-DDTHH:MM:SS+HH:MM: 2017-06-14T20:45:52+03:00
last_login_at-to
string <date-time>
Example: last_login_at-to=2017-06-14T20:45:52+03:00

Retrieve customer accounts that have most recently logged in on or before the specified date and time. You can provide the datetime value in any of these three following formats:

  • YYYY-MM-DD: 2017-06-14 - YYYY-MM-DDTHH:MM:SS: 2017-06-14T20:45:52 - YYYY-MM-DDTHH:MM:SS+HH:MM: 2017-06-14T20:45:52+03:00
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": [
    ],
  • "meta": {
    }
}

Create a new customer account

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
first_name
required
string

The customer's first name

last_name
required
string

The customer's last name

login_allowed
required
boolean

true = enable customer to login to your store with.

company
string

The customer's company

vat_code
string

The customer's VAT code. Required if company is provided. Validated against the EU's VIES database.

street_address
required
string

Street address

postal_code
required
string

Postal code

city
required
string

City

country
required
string

Country code

phone
string

Phone number

email
required
string

Email address

Responses

Request samples

Content type
application/json
{
  • "first_name": "Example",
  • "last_name": "Customer",
  • "login_allowed": true,
  • "company": "Example Company Inc.",
  • "vat_code": "1234567-6",
  • "street_address": "Example street 2",
  • "postal_code": "00100",
  • "city": "Helsinki",
  • "country": "FI",
  • "phone": "05012312312",
  • "email": "mail@domain.fi"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "first_name": "Example",
  • "last_name": "Customer",
  • "login_allowed": true,
  • "company": "Example Company Inc.",
  • "vat_code": "1234567-6",
  • "street_address": "Example street 2",
  • "postal_code": "00100",
  • "city": "Helsinki",
  • "country": "FI",
  • "phone": "05012312312",
  • "email": "mail@domain.fi",
  • "version_id": 4,
  • "language": "fi",
  • "email_subscription": true,
  • "einvoice_address": {
    },
  • "sms_subscription": false,
  • "customer_groups": [
    ]
}

Retrieve a customer

Authorizations:
HTTP Basic Access Authentication
path Parameters
customerID
required
integer >= 1

Unique identifier for the customer

query Parameters
expand
string
Value: "customer_groups"

Comma-separated list of expandable sub-resources.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "first_name": "Example",
  • "last_name": "Customer",
  • "login_allowed": true,
  • "company": "Example Company Inc.",
  • "vat_code": "1234567-6",
  • "street_address": "Example street 2",
  • "postal_code": "00100",
  • "city": "Helsinki",
  • "country": "FI",
  • "phone": "05012312312",
  • "email": "mail@domain.fi",
  • "version_id": 4,
  • "language": "fi",
  • "email_subscription": true,
  • "einvoice_address": {
    },
  • "sms_subscription": false,
  • "customer_groups": [
    ]
}

Modify a customer's details

Authorizations:
HTTP Basic Access Authentication
path Parameters
customerID
required
integer >= 1

Unique identifier for the customer

Request Body schema: application/json
first_name
required
string

The customer's first name

last_name
required
string

The customer's last name

login_allowed
required
boolean

true = enable customer to login to your store with.

company
string

The customer's company

vat_code
string

The customer's VAT code. Required if company is provided. Validated against the EU's VIES database.

street_address
required
string

Street address

postal_code
required
string

Postal code

city
required
string

City

country
required
string

Country code

phone
string

Phone number

email
required
string

Email address

Responses

Request samples

Content type
application/json
{
  • "first_name": "Example",
  • "last_name": "Customer",
  • "login_allowed": true,
  • "company": "Example Company Inc.",
  • "vat_code": "1234567-6",
  • "street_address": "Example street 2",
  • "postal_code": "00100",
  • "city": "Helsinki",
  • "country": "FI",
  • "phone": "05012312312",
  • "email": "mail@domain.fi"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "first_name": "Example",
  • "last_name": "Customer",
  • "login_allowed": true,
  • "company": "Example Company Inc.",
  • "vat_code": "1234567-6",
  • "street_address": "Example street 2",
  • "postal_code": "00100",
  • "city": "Helsinki",
  • "country": "FI",
  • "phone": "05012312312",
  • "email": "mail@domain.fi",
  • "version_id": 4,
  • "language": "fi",
  • "email_subscription": true,
  • "einvoice_address": {
    },
  • "sms_subscription": false,
  • "customer_groups": [
    ]
}

Delete a customer account

Authorizations:
HTTP Basic Access Authentication
path Parameters
customerID
required
integer >= 1

Unique identifier for the customer

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Retrieve a customer's shipping addresses

Authorizations:
HTTP Basic Access Authentication
path Parameters
customerID
required
integer >= 1

Unique identifier for the customer

query Parameters
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
[
  • {
    }
]

Retrieve a customer designated by their email address

Authorizations:
HTTP Basic Access Authentication
path Parameters
email
required
string

The customer's email address

query Parameters
expand
string
Value: "customer_groups"

Comma-separated list of expandable sub-resources.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "first_name": "Example",
  • "last_name": "Customer",
  • "login_allowed": true,
  • "company": "Example Company Inc.",
  • "vat_code": "1234567-6",
  • "street_address": "Example street 2",
  • "postal_code": "00100",
  • "city": "Helsinki",
  • "country": "FI",
  • "phone": "05012312312",
  • "email": "mail@domain.fi",
  • "version_id": 4,
  • "language": "fi",
  • "email_subscription": true,
  • "einvoice_address": {
    },
  • "sms_subscription": false,
  • "customer_groups": [
    ]
}

Delete a customer account designated by their email address

Authorizations:
HTTP Basic Access Authentication
path Parameters
email
required
string

The customer's email address

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Retrieve a customer by their external ID

Authorizations:
HTTP Basic Access Authentication
path Parameters
externalID
required
string

The customer's ID in an external system

query Parameters
expand
string
Value: "customer_groups"

Comma-separated list of expandable sub-resources.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "first_name": "Example",
  • "last_name": "Customer",
  • "login_allowed": true,
  • "company": "Example Company Inc.",
  • "vat_code": "1234567-6",
  • "street_address": "Example street 2",
  • "postal_code": "00100",
  • "city": "Helsinki",
  • "country": "FI",
  • "phone": "05012312312",
  • "email": "mail@domain.fi",
  • "version_id": 4,
  • "language": "fi",
  • "email_subscription": true,
  • "einvoice_address": {
    },
  • "sms_subscription": false,
  • "customer_groups": [
    ]
}

Delete a customer account designated by their external ID

Authorizations:
HTTP Basic Access Authentication
path Parameters
externalID
required
string

The customer's ID in an external system

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Email Subscribers

Retrieve a list of email subscribers

Authorizations:
HTTP Basic Access Authentication
query Parameters
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": [
    ],
  • "meta": {
    }
}

Add a new subscriber to your mailing list

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
email
required
string

The subscriber's email address

Responses

Request samples

Content type
application/json
{
  • "email": "mail@example.com"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "email": "mail@example.com",
  • "version_id": 5,
  • "language": "fi",
  • "country": "fi",
  • "subscribed_at": "2016-02-25T11:31:39+02:00",
  • "unsubscribed_at": "2016-02-25T11:31:39+02:00"
}

Remove a subscriber from the store's mailing list

Authorizations:
HTTP Basic Access Authentication
query Parameters
email
required
string

The subscriber's email address

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Gift Cards

Retrieve a list of gift cards

Authorizations:
HTTP Basic Access Authentication
query Parameters
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": [
    ],
  • "meta": {
    }
}

Create a new gift card

The response will contain the automatically generated gift card code.

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
expires_at
string <date-time>

The expiry date of the gift card. The gift card will expire at 0:00 am. on the given date.

notes
string

Internal notes for the gift card

balance
number

The gift card balance in euros

Responses

Request samples

Content type
application/json
{
  • "expires_at": "2017-12-31T23:20:50.52+02:00",
  • "notes": "Tilaajalahja esimerkkiasiakkaalle",
  • "balance": 50
}

Response samples

Content type
application/json
{
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "expires_at": "2017-12-31T23:20:50.52+02:00",
  • "notes": "Tilaajalahja esimerkkiasiakkaalle",
  • "balance": 50
}

Retrieve a gift card

Authorizations:
HTTP Basic Access Authentication
path Parameters
giftCardCode
required
string

Unique gift card code The gift card code is automatically generated, when creating a gift card.

Responses

Response samples

Content type
application/json
{
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "expires_at": "2017-12-31T23:20:50.52+02:00",
  • "notes": "Tilaajalahja esimerkkiasiakkaalle",
  • "balance": 50
}

Images

Retrieve a list of images

Authorizations:
HTTP Basic Access Authentication
query Parameters
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": [
    ],
  • "meta": {
    }
}

Submit a new product image

There are 2 alternative ways of adding an image to the store's file system. See further instructions in the examples.

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
One of
filename
string

The image filename excluding the path. The image must reside in the store's /files/tuotekuvat folder.

translations
Array of any

Array of translations for the image caption. Can be included in GET responses by using the ?expand=translations parameter.

Responses

Request samples

Content type
application/json
Example
Submitting an image from the store's file server
Submitting an image from the store's file server
Submitting a remotely stored image
Submitting an image in base64 encoded format
{
  • "filename": "image.png",
  • "translations": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "filename": "image.png",
  • "caption": "Image caption text",
  • "translations": [
    ]
}

Retrieve an image using its ID

Authorizations:
HTTP Basic Access Authentication
path Parameters
imageID
required
integer >= 1

Unique identifier for the image

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "filename": "image.png",
  • "caption": "Image caption text",
  • "translations": [
    ]
}

Retrieve an image using its filename

Authorizations:
HTTP Basic Access Authentication
path Parameters
fileName
required
string

The image filename

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "filename": "image.png",
  • "caption": "Image caption text",
  • "translations": [
    ]
}

Info Pages

Retrieve a list of info pages

Authorizations:
HTTP Basic Access Authentication
query Parameters
expand
string
Enum: "translations" "visibilities"

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

Create a new info page

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
parent
integer

ID of the parent page in the info page menu.

sort
integer

The info page's sorting number.

name
required
string

The info page title.

content
string

The HTML content of the page.

image
string

The info page's banner image.

link
string

Link target for the page. When this field is set, the page is made into a redirection link in the info page menu. Visitors cannot access the page content. You can use external, absolute links (https://www.example.com) or the store's internal links (/page/3).

translations
Array of any

Array of translations for the info page's text fields. Can be included in GET responses by using the ?expand=translations parameter.

visibilities
Array of any

Array of the page's visibilities in different versions. Can be included in GET responses by using the ?expand=visibilities parameter.

Responses

Request samples

Content type
application/json
{
  • "parent": 1,
  • "sort": 4,
  • "name": "About Us",
  • "content": "<p>Information about us. Contact using the form below:</p>{ContactForm}",
  • "image": "image.png",
  • "link": "https://www.example.com",
  • "translations": [
    ],
  • "visibilities": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "parent": 1,
  • "sort": 4,
  • "name": "About Us",
  • "content": "<p>Information about us. Contact using the form below:</p>{ContactForm}",
  • "image": "image.png",
  • "link": "https://www.example.com",
  • "translations": [
    ],
  • "visibilities": [
    ]
}

Retrieve an info page

Authorizations:
HTTP Basic Access Authentication
path Parameters
infoPageID
required
integer >= 1

Unique identifier for the info page

query Parameters
expand
string
Enum: "translations" "visibilities"

Comma-separated list of expandable sub-resources.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "parent": 1,
  • "sort": 4,
  • "name": "About Us",
  • "content": "<p>Information about us. Contact using the form below:</p>{ContactForm}",
  • "image": "image.png",
  • "link": "https://www.example.com",
  • "translations": [
    ],
  • "visibilities": [
    ]
}

Modify an info page

Authorizations:
HTTP Basic Access Authentication
path Parameters
infoPageID
required
integer >= 1

Unique identifier for the info page

Request Body schema: application/json
parent
integer

ID of the parent page in the info page menu.

sort
integer

The info page's sorting number.

name
required
string

The info page title.

content
string

The HTML content of the page.

image
string

The info page's banner image.

link
string

Link target for the page. When this field is set, the page is made into a redirection link in the info page menu. Visitors cannot access the page content. You can use external, absolute links (https://www.example.com) or the store's internal links (/page/3).

translations
Array of any

Array of translations for the info page's text fields. Can be included in GET responses by using the ?expand=translations parameter.

visibilities
Array of any

Array of the page's visibilities in different versions. Can be included in GET responses by using the ?expand=visibilities parameter.

Responses

Request samples

Content type
application/json
{
  • "parent": 1,
  • "sort": 4,
  • "name": "About Us",
  • "content": "<p>Information about us. Contact using the form below:</p>{ContactForm}",
  • "image": "image.png",
  • "link": "https://www.example.com",
  • "translations": [
    ],
  • "visibilities": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "parent": 1,
  • "sort": 4,
  • "name": "About Us",
  • "content": "<p>Information about us. Contact using the form below:</p>{ContactForm}",
  • "image": "image.png",
  • "link": "https://www.example.com",
  • "translations": [
    ],
  • "visibilities": [
    ]
}

Delete an info page

Authorizations:
HTTP Basic Access Authentication
path Parameters
infoPageID
required
integer >= 1

Unique identifier for the info page

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Retrieve an info page

Authorizations:
HTTP Basic Access Authentication
path Parameters
newsPostID
required
integer >= 1

Unique identifier for the news post

query Parameters
expand
string
Enum: "translations" "visibilities"

Comma-separated list of expandable sub-resources.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "published_at": "2013-06-19T20:41:47+03:00",
  • "subject": "Summer Discount all Home Appliances -13 %",
  • "overview": "This summer all home appliances -13 %. Discount valid until end of August.",
  • "content": "<p>See our home appliances category for all of the various discounts.</p>",
  • "image": "image.jpg",
  • "image_caption": "Päivi's Boutique Summer Home Appliances Discount.",
  • "image_link": "/category/2",
  • "seo_title": "Document title",
  • "seo_page_title": "Page title",
  • "seo_meta_description": "Meta description",
  • "translations": [
    ],
  • "visibilities": [
    ]
}

News

Retrieve a list of news posts

Authorizations:
HTTP Basic Access Authentication
query Parameters
expand
string
Enum: "translations" "visibilities"

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

Create a news post

NOTE: When creating a news post, it will be hidden in all versions by default. You can make the post visible in the store's admin panel.

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
subject
required
string

The post title

overview
string

The In brief field of the post

content
string

The post content

image
string

The News image field of the posts.

image_caption
string

The image caption

image_link
string

The image link. Enter internal relative links in the format /category/2 and absolute links as https://www.example.com

seo_title
string

The SEO document title. Shown, for example, in Google search results as the title.

seo_page_title
string

The SEO page title. Shown on the page, in place of the usual page title, if set.

seo_meta_description
string

The SEO meta description. Shown, for example, in Google search results as the page description.

Responses

Request samples

Content type
application/json
{
  • "subject": "Summer Discount all Home Appliances -13 %",
  • "overview": "This summer all home appliances -13 %. Discount valid until end of August.",
  • "content": "<p>See our home appliances category for all of the various discounts.</p>",
  • "image": "image.jpg",
  • "image_caption": "Päivi's Boutique Summer Home Appliances Discount.",
  • "image_link": "/category/2",
  • "seo_title": "Document title",
  • "seo_page_title": "Page title",
  • "seo_meta_description": "Meta description"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "published_at": "2013-06-19T20:41:47+03:00",
  • "subject": "Summer Discount all Home Appliances -13 %",
  • "overview": "This summer all home appliances -13 %. Discount valid until end of August.",
  • "content": "<p>See our home appliances category for all of the various discounts.</p>",
  • "image": "image.jpg",
  • "image_caption": "Päivi's Boutique Summer Home Appliances Discount.",
  • "image_link": "/category/2",
  • "seo_title": "Document title",
  • "seo_page_title": "Page title",
  • "seo_meta_description": "Meta description",
  • "translations": [
    ],
  • "visibilities": [
    ]
}

Modify a news post

Authorizations:
HTTP Basic Access Authentication
path Parameters
newsPostID
required
integer >= 1

Unique identifier for the news post

Request Body schema: application/json
subject
required
string

The post title

overview
string

The In brief field of the post

content
string

The post content

image
string

The News image field of the posts.

image_caption
string

The image caption

image_link
string

The image link. Enter internal relative links in the format /category/2 and absolute links as https://www.example.com

seo_title
string

The SEO document title. Shown, for example, in Google search results as the title.

seo_page_title
string

The SEO page title. Shown on the page, in place of the usual page title, if set.

seo_meta_description
string

The SEO meta description. Shown, for example, in Google search results as the page description.

Responses

Request samples

Content type
application/json
{
  • "subject": "Summer Discount all Home Appliances -13 %",
  • "overview": "This summer all home appliances -13 %. Discount valid until end of August.",
  • "content": "<p>See our home appliances category for all of the various discounts.</p>",
  • "image": "image.jpg",
  • "image_caption": "Päivi's Boutique Summer Home Appliances Discount.",
  • "image_link": "/category/2",
  • "seo_title": "Document title",
  • "seo_page_title": "Page title",
  • "seo_meta_description": "Meta description"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "published_at": "2013-06-19T20:41:47+03:00",
  • "subject": "Summer Discount all Home Appliances -13 %",
  • "overview": "This summer all home appliances -13 %. Discount valid until end of August.",
  • "content": "<p>See our home appliances category for all of the various discounts.</p>",
  • "image": "image.jpg",
  • "image_caption": "Päivi's Boutique Summer Home Appliances Discount.",
  • "image_link": "/category/2",
  • "seo_title": "Document title",
  • "seo_page_title": "Page title",
  • "seo_meta_description": "Meta description",
  • "translations": [
    ],
  • "visibilities": [
    ]
}

Delete a news post

Authorizations:
HTTP Basic Access Authentication
path Parameters
newsPostID
required
integer >= 1

Unique identifier for the news post

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Orders

Retrieve a list of orders

Authorizations:
HTTP Basic Access Authentication
query Parameters
archived_at-from
string <date-time>
Example: archived_at-from=2017-06-14T20:45:52+03:00

Retrieve orders that have been archived on or after the specified date and time. You can provide the datetime value in any of these three following formats:

  • YYYY-MM-DD: 2017-06-14 - YYYY-MM-DDTHH:MM:SS: 2017-06-14T20:45:52 - YYYY-MM-DDTHH:MM:SS+HH:MM: 2017-06-14T20:45:52+03:00 NOTE! Archiving must be enabled, otherwise the request will return a 400 Bad Request error.
archived_at-to
string <date-time>
Example: archived_at-to=2017-06-14T20:45:52+03:00

Retrieve orders that have been archived on or before the specified date and time. You can provide the datetime value in any of these three following formats:

  • YYYY-MM-DD: 2017-06-14 - YYYY-MM-DDTHH:MM:SS: 2017-06-14T20:45:52 - YYYY-MM-DDTHH:MM:SS+HH:MM: 2017-06-14T20:45:52+03:00 NOTE! Archiving must be enabled, otherwise the request will return a 400 Bad Request error.
created_at-from
string <date-time>
Example: created_at-from=2017-06-14T20:45:52+03:00

Retrieve orders that have been created on or after the specified date and time. You can provide the datetime value in any of these three following formats:

  • YYYY-MM-DD: 2017-06-14 - YYYY-MM-DDTHH:MM:SS: 2017-06-14T20:45:52 - YYYY-MM-DDTHH:MM:SS+HH:MM: 2017-06-14T20:45:52+03:00
created_at-to
string <date-time>
Example: created_at-to=2017-06-14T20:45:52+03:00

Retrieve orders that have been created on or before the specified date and time. You can provide the datetime value in any of these three following formats:

  • YYYY-MM-DD: 2017-06-14 - YYYY-MM-DDTHH:MM:SS: 2017-06-14T20:45:52 - YYYY-MM-DDTHH:MM:SS+HH:MM: 2017-06-14T20:45:52+03:00
shipments_completed_at-from
string <date-time>
Example: shipments_completed_at-from=2017-06-14T20:45:52+03:00

Retrieve orders whose shipments have been marked as delivered on or after the specified date and time. You can provide the datetime value in any of these three following formats:

  • YYYY-MM-DD: 2017-06-14 - YYYY-MM-DDTHH:MM:SS: 2017-06-14T20:45:52 - YYYY-MM-DDTHH:MM:SS+HH:MM: 2017-06-14T20:45:52+03:00
shipments_completed_at-to
string <date-time>
Example: shipments_completed_at-to=2017-06-14T20:45:52+03:00

Retrieve orders whose shipments have been marked as delivered on or before the specified date and time. You can provide the datetime value in any of these three following formats:

  • YYYY-MM-DD: 2017-06-14 - YYYY-MM-DDTHH:MM:SS: 2017-06-14T20:45:52 - YYYY-MM-DDTHH:MM:SS+HH:MM: 2017-06-14T20:45:52+03:00
expand
string
Enum: "payments" "shipments" "products" "products.return_reasons" "tax_summary" "comments" "events"

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.

status
string
Enum: "OPEN" "CANCELLED" "COMPLETED" "RETURNED"

Retrieve orders with a specific processing status.

updated_at-from
string <date-time>
Example: updated_at-from=2017-06-14T20:45:52+03:00

Retrieve orders that have been updated after the specified date and time. You can provide the datetime value in any of the three following formats:

  • YYYY-MM-DD: 2017-06-14 - YYYY-MM-DDTHH:MM:SS: 2017-06-14T20:45:52 - YYYY-MM-DDTHH:MM:SS+HH:MM: 2017-06-14T20:45:52+03:00
updated_at-to
string <date-time>
Example: updated_at-to=2017-06-14T20:45:52+03:00

Retrieve orders that have been updated before the specified date and time. You can provide the datetime value in any of the three following formats:

  • YYYY-MM-DD: 2017-06-14 - YYYY-MM-DDTHH:MM:SS: 2017-06-14T20:45:52 - YYYY-MM-DDTHH:MM:SS+HH:MM: 2017-06-14T20:45:52+03:00

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a new order

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
external_id
string

The order ID in an external system

version_id
integer >= 1

ID of the version where the order was made

customer_id
integer >= 1

ID of the recipient customer. Required if the order is created for an already existing customer account. If not, customer information must be provided in the customer_information object.

referral_code
string

Referral code that was used with the order. Referral codes are available through the Affiliate Marketing extension.

shipping_method_id
required
integer

The shipping method ID

shipping_costs
number

The amount of shipping costs in EUR

payment_method_id
required
integer >= 1

NOTE! You can only use the following payment services to create orders through the API: * MyCashflow Ennakkomaksu * MyCashflow Lasku * Postiennakko * Bussiennakko

payment_costs
number

The payment costs

object

Required if customer_id is not set, i.e. the order is created for someone who does not have a customer account in the store.

object
products
required
Array of any non-empty
object
Array of objects

Responses

Request samples

Content type
application/json
{
  • "external_id": "5",
  • "version_id": 3,
  • "customer_id": 65,
  • "referral_code": "REF123",
  • "shipping_method_id": 5,
  • "shipping_costs": 5.9,
  • "payment_method_id": 6,
  • "payment_costs": 2.5,
  • "customer_information": {
    },
  • "shipping_address": {
    },
  • "products": [
    ],
  • "shipments": {},
  • "payments": []
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "archived_at": "2016-02-25T11:31:39+02:00",
  • "external_id": "5",
  • "version_id": 3,
  • "customer_id": 65,
  • "language": "fi",
  • "customer_external_id": "CUSTOMER123",
  • "different_shipping_address": true,
  • "subtotal": 14,
  • "discount": {
    },
  • "total": 49.99,
  • "status": "COMPLETED",
  • "details": "Please deliver ASAP, it is an emergency",
  • "receipt_url": "https://example.mycashflow.fi/orderstatus/1/receipt/afcc120905e10bb56e63c30d6d7653c4",
  • "return_document_url": "https://example.mycashflow.fi/orderstatus/1/returndocument/afcc120905e10bb56e63c30d6d7653c4",
  • "dispatch_note_url": "https://example.mycashflow.fi/orderstatus/1/dispatchnote/afcc120905e10bb56e63c30d6d7653c4",
  • "custom_data": { },
  • "referral_code": "REF123",
  • "shipping_method_id": 5,
  • "shipping_costs": 5.9,
  • "payment_method_id": 6,
  • "payment_costs": 2.5,
  • "customer_information": {
    },
  • "shipping_address": {
    },
  • "comments": [
    ],
  • "tax_summary": {
    },
  • "events": {
    },
  • "products": [
    ],
  • "shipments": {},
  • "payments": [
    ]
}

Retrieve an order

Authorizations:
HTTP Basic Access Authentication
path Parameters
orderID
required
integer >= 1

Unique identifier for the order

query Parameters
expand
string
Enum: "payments" "shipments" "products" "products.return_reasons" "tax_summary" "comments" "events"

Comma-separated list of expandable sub-resources.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "archived_at": "2016-02-25T11:31:39+02:00",
  • "external_id": "5",
  • "version_id": 3,
  • "customer_id": 65,
  • "language": "fi",
  • "customer_external_id": "CUSTOMER123",
  • "different_shipping_address": true,
  • "subtotal": 14,
  • "discount": {
    },
  • "total": 49.99,
  • "status": "COMPLETED",
  • "details": "Please deliver ASAP, it is an emergency",
  • "receipt_url": "https://example.mycashflow.fi/orderstatus/1/receipt/afcc120905e10bb56e63c30d6d7653c4",
  • "return_document_url": "https://example.mycashflow.fi/orderstatus/1/returndocument/afcc120905e10bb56e63c30d6d7653c4",
  • "dispatch_note_url": "https://example.mycashflow.fi/orderstatus/1/dispatchnote/afcc120905e10bb56e63c30d6d7653c4",
  • "custom_data": { },
  • "referral_code": "REF123",
  • "shipping_method_id": 5,
  • "shipping_costs": 5.9,
  • "payment_method_id": 6,
  • "payment_costs": 2.5,
  • "customer_information": {
    },
  • "shipping_address": {
    },
  • "comments": [
    ],
  • "tax_summary": {
    },
  • "events": {
    },
  • "products": [
    ],
  • "shipments": {},
  • "payments": [
    ]
}

Retrieve an order using its external ID

Authorizations:
HTTP Basic Access Authentication
path Parameters
externalID
required
string

The order ID in an external system

query Parameters
expand
string
Enum: "payments" "shipments" "products" "products.return_reasons" "tax_summary" "comments" "events"

Comma-separated list of expandable sub-resources.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "archived_at": "2016-02-25T11:31:39+02:00",
  • "external_id": "5",
  • "version_id": 3,
  • "customer_id": 65,
  • "language": "fi",
  • "customer_external_id": "CUSTOMER123",
  • "different_shipping_address": true,
  • "subtotal": 14,
  • "discount": {
    },
  • "total": 49.99,
  • "status": "COMPLETED",
  • "details": "Please deliver ASAP, it is an emergency",
  • "receipt_url": "https://example.mycashflow.fi/orderstatus/1/receipt/afcc120905e10bb56e63c30d6d7653c4",
  • "return_document_url": "https://example.mycashflow.fi/orderstatus/1/returndocument/afcc120905e10bb56e63c30d6d7653c4",
  • "dispatch_note_url": "https://example.mycashflow.fi/orderstatus/1/dispatchnote/afcc120905e10bb56e63c30d6d7653c4",
  • "custom_data": { },
  • "referral_code": "REF123",
  • "shipping_method_id": 5,
  • "shipping_costs": 5.9,
  • "payment_method_id": 6,
  • "payment_costs": 2.5,
  • "customer_information": {
    },
  • "shipping_address": {
    },
  • "comments": [
    ],
  • "tax_summary": {
    },
  • "events": {
    },
  • "products": [
    ],
  • "shipments": {},
  • "payments": [
    ]
}

Run quick processing for an order

Authorizations:
HTTP Basic Access Authentication
path Parameters
orderID
required
integer >= 1

Unique identifier for the order

Request Body schema: application/json
allow_open_cash_on_delivery_payments
boolean
Default: false

Allow use of cash-on-delivery payment type when quick processing the order. If set to false, and the payment method is cash-on-delivery, the quick processing will fail.

ignore_payment_activation_errors
boolean
Default: false

Determines whether any errors activating payments should be ignored. Use this option, if the order has a Klarna payment that has been processed in Klarna Online.

tracking_code
string

The tracking code for the order. You can obtain the tracking code with POST /orders/{orderId}/shipments/{shipmentId}/register.

send_emails
boolean
Default: true

Determines whether to automatically send the shipping confirmation email upon successful processing.

Responses

Request samples

Content type
application/json
{
  • "allow_open_cash_on_delivery_payments": true,
  • "ignore_payment_activation_errors": true,
  • "tracking_code": "JJFI65229310013494123",
  • "send_emails": false
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "archived_at": "2016-02-25T11:31:39+02:00",
  • "external_id": "5",
  • "version_id": 3,
  • "customer_id": 65,
  • "language": "fi",
  • "customer_external_id": "CUSTOMER123",
  • "different_shipping_address": true,
  • "subtotal": 14,
  • "discount": {
    },
  • "total": 49.99,
  • "status": "COMPLETED",
  • "details": "Please deliver ASAP, it is an emergency",
  • "receipt_url": "https://example.mycashflow.fi/orderstatus/1/receipt/afcc120905e10bb56e63c30d6d7653c4",
  • "return_document_url": "https://example.mycashflow.fi/orderstatus/1/returndocument/afcc120905e10bb56e63c30d6d7653c4",
  • "dispatch_note_url": "https://example.mycashflow.fi/orderstatus/1/dispatchnote/afcc120905e10bb56e63c30d6d7653c4",
  • "custom_data": { },
  • "referral_code": "REF123",
  • "shipping_method_id": 5,
  • "shipping_costs": 5.9,
  • "payment_method_id": 6,
  • "payment_costs": 2.5,
  • "customer_information": {
    },
  • "shipping_address": {
    },
  • "comments": [
    ],
  • "tax_summary": {
    },
  • "events": {
    },
  • "products": [
    ],
  • "shipments": {},
  • "payments": [
    ]
}

Cancel an order

Authorizations:
HTTP Basic Access Authentication
path Parameters
orderID
required
integer >= 1

Unique identifier for the order

Request Body schema: application/json
send_emails
boolean
Default: true

Determines whether to send a cancellation email to the customer's email address.

Responses

Request samples

Content type
application/json
{
  • "send_emails": false
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "archived_at": "2016-02-25T11:31:39+02:00",
  • "external_id": "5",
  • "version_id": 3,
  • "customer_id": 65,
  • "language": "fi",
  • "customer_external_id": "CUSTOMER123",
  • "different_shipping_address": true,
  • "subtotal": 14,
  • "discount": {
    },
  • "total": 49.99,
  • "status": "COMPLETED",
  • "details": "Please deliver ASAP, it is an emergency",
  • "receipt_url": "https://example.mycashflow.fi/orderstatus/1/receipt/afcc120905e10bb56e63c30d6d7653c4",
  • "return_document_url": "https://example.mycashflow.fi/orderstatus/1/returndocument/afcc120905e10bb56e63c30d6d7653c4",
  • "dispatch_note_url": "https://example.mycashflow.fi/orderstatus/1/dispatchnote/afcc120905e10bb56e63c30d6d7653c4",
  • "custom_data": { },
  • "referral_code": "REF123",
  • "shipping_method_id": 5,
  • "shipping_costs": 5.9,
  • "payment_method_id": 6,
  • "payment_costs": 2.5,
  • "customer_information": {
    },
  • "shipping_address": {
    },
  • "comments": [
    ],
  • "tax_summary": {
    },
  • "events": {
    },
  • "products": [
    ],
  • "shipments": {},
  • "payments": [
    ]
}

Archive an order

Archiving must be enabled in the store. Read more about archiving orders.

Authorizations:
HTTP Basic Access Authentication
path Parameters
orderID
required
integer >= 1

Unique identifier for the order

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "archived_at": "2016-02-25T11:31:39+02:00",
  • "external_id": "5",
  • "version_id": 3,
  • "customer_id": 65,
  • "language": "fi",
  • "customer_external_id": "CUSTOMER123",
  • "different_shipping_address": true,
  • "subtotal": 14,
  • "discount": {
    },
  • "total": 49.99,
  • "status": "COMPLETED",
  • "details": "Please deliver ASAP, it is an emergency",
  • "receipt_url": "https://example.mycashflow.fi/orderstatus/1/receipt/afcc120905e10bb56e63c30d6d7653c4",
  • "return_document_url": "https://example.mycashflow.fi/orderstatus/1/returndocument/afcc120905e10bb56e63c30d6d7653c4",
  • "dispatch_note_url": "https://example.mycashflow.fi/orderstatus/1/dispatchnote/afcc120905e10bb56e63c30d6d7653c4",
  • "custom_data": { },
  • "referral_code": "REF123",
  • "shipping_method_id": 5,
  • "shipping_costs": 5.9,
  • "payment_method_id": 6,
  • "payment_costs": 2.5,
  • "customer_information": {
    },
  • "shipping_address": {
    },
  • "comments": [
    ],
  • "tax_summary": {
    },
  • "events": {
    },
  • "products": [
    ],
  • "shipments": {},
  • "payments": [
    ]
}

Post a new comment (private or public) for the order

Authorizations:
HTTP Basic Access Authentication
path Parameters
orderID
required
integer >= 1

Unique identifier for the order

Request Body schema: application/json
text
required
string
visibility
string
Default: "PRIVATE"
Enum: "PUBLIC" "PRIVATE"

Determines whether the comment is shown to the customer or not. * PRIVATE: The comment will be made private, so that it is only shown in the admin panel for logged in admin users. * PUBLIC: The comment is shown to the customer, and an email notification is sent to them with the comment.

update_timestamp
boolean
Default: false

Determines whether the order's last modified date should be updated, when the comment is submitted.

Responses

Request samples

Content type
application/json
{
  • "text": "Kommentin sisältö",
  • "visibility": "PUBLIC",
  • "update_timestamp": true
}

Response samples

Content type
application/json
{
  • "text": "Kommentin sisältö",
  • "visibility": "PUBLIC",
  • "update_timestamp": true
}

Retrieve a payment transaction

You can fetch a list of an order's payments by using GET /api/v0/orders/{orderId}?expand=payments

Authorizations:
HTTP Basic Access Authentication
path Parameters
orderID
required
integer >= 1

Unique identifier for the order

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Activate the payment

Used only with Klarna Checkout payments, when the payment transaction status is PENDING_ACTIVATION. The payment status after marking unpaid is PAID.

Authorizations:
HTTP Basic Access Authentication
path Parameters
orderID
required
integer >= 1

Unique identifier for the order

paymentID
required
integer >= 1

Unique identifier for the payment

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "order_id": 56,
  • "payment_method_id": 5,
  • "reference": "201306250036",
  • "external_id": "f9addd21d393e9d5aab2a577a89e029a86dc5071",
  • "amount": 15.99,
  • "currency": "EUR",
  • "exchange_rate": 1.23,
  • "is_confirmed": true,
  • "is_paid": true,
  • "status": "PAID",
  • "invoice_url": "https://example.mycashflow.fi/orderstatus/92/invoice/24b4183524d8c88761444633444443dd"
}

Cancel a payment

The payment status after marking unpaid is CANCELLED.

Authorizations:
HTTP Basic Access Authentication
path Parameters
orderID
required
integer >= 1

Unique identifier for the order

paymentID
required
integer >= 1

Unique identifier for the payment

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "order_id": 56,
  • "payment_method_id": 5,
  • "reference": "201306250036",
  • "external_id": "f9addd21d393e9d5aab2a577a89e029a86dc5071",
  • "amount": 15.99,
  • "currency": "EUR",
  • "exchange_rate": 1.23,
  • "is_confirmed": true,
  • "is_paid": true,
  • "status": "PAID",
  • "invoice_url": "https://example.mycashflow.fi/orderstatus/92/invoice/24b4183524d8c88761444633444443dd"
}

Mark the payment as paid

The payment status after marking unpaid is PAID.

Authorizations:
HTTP Basic Access Authentication
path Parameters
orderID
required
integer >= 1

Unique identifier for the order

paymentID
required
integer >= 1

Unique identifier for the payment

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "order_id": 56,
  • "payment_method_id": 5,
  • "reference": "201306250036",
  • "external_id": "f9addd21d393e9d5aab2a577a89e029a86dc5071",
  • "amount": 15.99,
  • "currency": "EUR",
  • "exchange_rate": 1.23,
  • "is_confirmed": true,
  • "is_paid": true,
  • "status": "PAID",
  • "invoice_url": "https://example.mycashflow.fi/orderstatus/92/invoice/24b4183524d8c88761444633444443dd"
}

Mark the payment as unpaid

The payment status after marking unpaid is OPEN.

Authorizations:
HTTP Basic Access Authentication
path Parameters
orderID
required
integer >= 1

Unique identifier for the order

paymentID
required
integer >= 1

Unique identifier for the payment

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "order_id": 56,
  • "payment_method_id": 5,
  • "reference": "201306250036",
  • "external_id": "f9addd21d393e9d5aab2a577a89e029a86dc5071",
  • "amount": 15.99,
  • "currency": "EUR",
  • "exchange_rate": 1.23,
  • "is_confirmed": true,
  • "is_paid": true,
  • "status": "PAID",
  • "invoice_url": "https://example.mycashflow.fi/orderstatus/92/invoice/24b4183524d8c88761444633444443dd"
}

Retrieve a list shipments

Authorizations:
HTTP Basic Access Authentication
path Parameters
orderID
required
integer >= 1

Unique identifier for the order

query Parameters
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
{}

Retrieve a shipment

Authorizations:
HTTP Basic Access Authentication
path Parameters
orderID
required
integer >= 1

Unique identifier for the order

shipmentID
required
integer >= 1

Unique identifier for the shipment

Responses

Response samples

Content type
application/json
{}

Mark shipment as delivered

Upon completion the shipment status will be changed to COMPLETED. Once all the shipments have been marked as delivered, the entire order's status will also be changed to COMPLETED.

Authorizations:
HTTP Basic Access Authentication
path Parameters
orderID
required
integer >= 1

Unique identifier for the order

shipmentID
required
integer >= 1

Unique identifier for the shipment

Request Body schema: application/json
send_emails
boolean
Default: true

Determines whether to send shipping confirmation to customer upon completion.

register_if_not_registered
boolean
Default: true

Determines whether to register the shipment, if it has not been registered. You can also register a shipment before completing it via POST /api/v0/orders/{orderId}/shipments/{shipmentId}/register

tracking_code
string

The shipment tracking code. Can be obtained via POST /api/v0/orders/{orderId}/shipments/{shipmentId}/register

Responses

Request samples

Content type
application/json
{
  • "send_emails": false,
  • "register_if_not_registered": false,
  • "tracking_code": "JJFI00000450001980299"
}

Response samples

Content type
application/json
{}

Register shipment to access its shipping label and tracking code (if available)

The body of the POST request can be empty. Once the shipment has been registered, you can access its shipping documents. Read more about downloading shipping documents via the API.

Authorizations:
HTTP Basic Access Authentication
path Parameters
orderID
required
integer >= 1

Unique identifier for the order

shipmentID
required
integer >= 1

Unique identifier for the shipment

Responses

Response samples

Content type
application/json
{}

Retrieve a shipment's shipping label

In order to download the shipping label, you first need to register the shipment with POST /api/v0/orders/{orderId}/shipments/{shipmentId}/register

Authorizations:
HTTP Basic Access Authentication
path Parameters
orderID
required
integer >= 1

Unique identifier for the order

shipmentID
required
integer >= 1

Unique identifier for the shipment

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Retrieve a shipment's dispatch note

Authorizations:
HTTP Basic Access Authentication
path Parameters
orderID
required
integer >= 1

Unique identifier for the order

shipmentID
required
integer >= 1

Unique identifier for the shipment

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Payment Methods

Retrieve a list of payment methods.

Authorizations:
HTTP Basic Access Authentication
query Parameters
expand
string
Enum: "translations" "visibilities"

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

Retrieve a payment method

Authorizations:
HTTP Basic Access Authentication
path Parameters
paymentMethodID
required
integer >= 1

Unique identifier for the payment method

query Parameters
expand
string
Enum: "translations" "visibilities"

Comma-separated list of expandable sub-resources.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "name": "Invoice",
  • "description": "Maksa laskulla, 14 päivää maksuaikaa.",
  • "username": "",
  • "product_code": "INVOICE",
  • "sort": "3",
  • "provider": "MCF_INVOICE",
  • "help": "We will email you a PDF invoice that contains further payment details.",
  • "translations": [
    ],
  • "visibilities": [
    ]
}

Modify a payment method

Authorizations:
HTTP Basic Access Authentication
path Parameters
paymentMethodID
required
integer >= 1

Unique identifier for the payment method

Request Body schema: application/json
name
required
string

The payment method name

description
string

The payment method description

product_code
string

Product code assigned to the payment method

sort
integer

Sorting number for the payment method

help
string

The payment instructions

translations
Array of any

Array of translations for the payment method's multilingual fields. Can be included in GET responses by using the ?expand=translations GET parameter.

Responses

Request samples

Content type
application/json
{
  • "name": "Invoice",
  • "description": "Maksa laskulla, 14 päivää maksuaikaa.",
  • "product_code": "INVOICE",
  • "sort": "3",
  • "help": "We will email you a PDF invoice that contains further payment details.",
  • "translations": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "name": "Invoice",
  • "description": "Maksa laskulla, 14 päivää maksuaikaa.",
  • "username": "",
  • "product_code": "INVOICE",
  • "sort": "3",
  • "provider": "MCF_INVOICE",
  • "help": "We will email you a PDF invoice that contains further payment details.",
  • "translations": [
    ],
  • "visibilities": [
    ]
}

Processing Lists

Retrieve a list of processing lists

Authorizations:
HTTP Basic Access Authentication
query Parameters
expand
string
Enum: "orders" "orders.shipments" "orders.shipments.products" "orders.shipments.products.stock_item"

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

Delete a processing list

Authorizations:
HTTP Basic Access Authentication
path Parameters
processingListID
required
integer >= 1

Unique identifier for the processing list

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Complete a processing list

The orders of the processing list need to have been processed (have the COMPLETED status) before completing the processing list.

Authorizations:
HTTP Basic Access Authentication
path Parameters
processingListID
required
integer >= 1

Unique identifier for the processing list

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "completed_at": "2013-06-19T20:41:47+03:00",
  • "user_id": 13,
  • "name": "Monday's orders",
  • "comment": "These should get done ASAP",
  • "orders": [
    ]
}

Product Attributes

Retrieve a list of product attributes

Authorizations:
HTTP Basic Access Authentication
query Parameters
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": [
    ],
  • "meta": {
    }
}

Create a new product attribute

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
code
required
string

The individual code used to identify of the product attribute.

sort
integer

The position of the product attribute on lists (filters and product page).

filterable
boolean
Default: false

Determines whether the product attribute is used as a product list filter in the store.

listable
boolean
Default: false

Determines whether the product attribute is shown on attribute lists on the product page.

labels
required
object

JSON object of translations for the product attribute's label texts which are displayed on filter lits and on the product page.

Responses

Request samples

Content type
application/json
{
  • "code": "material",
  • "sort": 3,
  • "filterable": false,
  • "listable": true,
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "code": "material",
  • "sort": 3,
  • "filterable": false,
  • "listable": true,
  • "labels": {
    }
}

Retrieve a product attribute

Authorizations:
HTTP Basic Access Authentication
path Parameters
productAttributeCode
required
integer >= 1

Unique code of the product attribute

Responses

Response samples

Content type
application/json
{
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "code": "material",
  • "sort": 3,
  • "filterable": false,
  • "listable": true,
  • "labels": {
    }
}

Modify a product attribute

Authorizations:
HTTP Basic Access Authentication
path Parameters
productAttributeCode
required
integer >= 1

Unique code of the product attribute

Request Body schema: application/json
code
required
string

The individual code used to identify of the product attribute.

sort
integer

The position of the product attribute on lists (filters and product page).

filterable
boolean
Default: false

Determines whether the product attribute is used as a product list filter in the store.

listable
boolean
Default: false

Determines whether the product attribute is shown on attribute lists on the product page.

labels
required
object

JSON object of translations for the product attribute's label texts which are displayed on filter lits and on the product page.

Responses

Request samples

Content type
application/json
{
  • "code": "material",
  • "sort": 3,
  • "filterable": false,
  • "listable": true,
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "code": "material",
  • "sort": 3,
  • "filterable": false,
  • "listable": true,
  • "labels": {
    }
}

Delete a product attribute

You cannot delete the internal, pre-defined product attributes (color, size, brand, category).

Authorizations:
HTTP Basic Access Authentication
path Parameters
productAttributeCode
required
integer >= 1

Unique code of the product attribute

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Add a new value to a product attribute

You cannot add values to the internal _category and _brand attributes. These attributes are automatically populated by the store's categories and brands.

Authorizations:
HTTP Basic Access Authentication
path Parameters
productAttributeCode
required
integer >= 1

Unique code of the product attribute

Request Body schema: application/json
code
required
string

The unique code of the attribute value. Entered upon creating a product attribute. May contain the characters a-z0-9_.

sort
integer

Integer that determines the position of the value among the value list.

Responses

Request samples

Content type
application/json
{
  • "code": "red",
  • "sort": 1
}

Response samples

Content type
application/json
{
  • "code": "red",
  • "sort": 1
}

Modify a product attribute value

description: >- You cannot modify the values of the internal _category and _brand attributes. These attributes are automatically populated by the store's categories and brands.

Authorizations:
HTTP Basic Access Authentication
path Parameters
productAttributeCode
required
integer >= 1

Unique code of the product attribute

productAttributeValueCode
required
integer >= 1

Unique code of the product attribute value

Request Body schema: application/json
code
required
string

The unique code of the attribute value. Entered upon creating a product attribute. May contain the characters a-z0-9_.

sort
integer

Integer that determines the position of the value among the value list.

Responses

Request samples

Content type
application/json
{
  • "code": "red",
  • "sort": 1
}

Response samples

Content type
application/json
{
  • "code": "red",
  • "sort": 1
}

Delete a product attribute's value

Authorizations:
HTTP Basic Access Authentication
path Parameters
productAttributeCode
required
integer >= 1

Unique code of the product attribute

productAttributeValueCode
required
integer >= 1

Unique code of the product attribute value

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Products

Retrieve a list of products

Authorizations:
HTTP Basic Access Authentication
query Parameters
expand
string
Enum: "translations" "visibilities" "category_links" "image_links" "features" "variations" "variations.features" "variations.stock_item" "brand" "stock_item"

Comma-separated list of expandable sub-resources.

id
integer >= 1
Example: id=1,2,3

List of ID's of products to fetch.

created_at-from
string <date-time>
Example: created_at-from=2017-06-14T20:45:52+03:00

Retrieve products that have been created on or after the specified date and time. You can provide the datetime value in any of these three following formats:

  • YYYY-MM-DD: 2017-06-14 - YYYY-MM-DDTHH:MM:SS: 2017-06-14T20:45:52 - YYYY-MM-DDTHH:MM:SS+HH:MM: 2017-06-14T20:45:52+03:00
created_at-to
string <date-time>
Example: created_at-to=2017-06-14T20:45:52+03:00

Retrieve products that have been created on or before the specified date and time. You can provide the datetime value in any of these three following formats:

  • YYYY-MM-DD: 2017-06-14 - YYYY-MM-DDTHH:MM:SS: 2017-06-14T20:45:52 - YYYY-MM-DDTHH:MM:SS+HH:MM: 2017-06-14T20:45:52+03:00
updated_at-from
string <date-time>
Example: updated_at-from=2017-06-14T20:45:52+03:00

Retrieve products that have been created on or after the specified date and time. You can provide the datetime value in any of these three following formats:

  • YYYY-MM-DD: 2017-06-14 - YYYY-MM-DDTHH:MM:SS: 2017-06-14T20:45:52 - YYYY-MM-DDTHH:MM:SS+HH:MM: 2017-06-14T20:45:52+03:00
updated_at-to
string <date-time>
Example: updated_at-to=2017-06-14T20:45:52+03:00

Retrieve products that have been created on or before the specified date and time. You can provide the datetime value in any of these three following formats:

  • YYYY-MM-DD: 2017-06-14 - YYYY-MM-DDTHH:MM:SS: 2017-06-14T20:45:52 - YYYY-MM-DDTHH:MM:SS+HH:MM: 2017-06-14T20:45:52+03:00
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": [
    ],
  • "meta": {
    }
}

Create a new product

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
product_code
string

The product code

supplier_code
string

The supplier's product code

name
required
string

The product name. Required in either the POST / PATCH body or in the translations array, when managing multilingual content.

description
string

The short product description. Can be included in either the POST / PATCH body or in the translations array, when managing multilingual content.

information
string

The long product description. Can be included in either the POST / PATCH body or in the translations array, when managing multilingual content.

keywords
string

Comma-separated list of keywords. Used by the internal search engine.

price
number

The product price including VAT. The tax free price is calculated based on the vat_rate field.

purchase_price
number

The product's purchase price. Always exclude VAT.

vat_rate
integer

The product's VAT rate. If not included when creating a product, the product will have VAT 0 %.

weight
number

The weight of the product in kilograms

warranty
integer

The warranty period in months

brand_id
integer >= 1

ID of the product's brand

supplier_id
integer >= 1

ID of the product's supplier

available_from
string <date>

Defines the date, when the product becomes available. If visible_from and/or purchasable_from are not set, the product is visible and purchasable by default. The product will become available at 12:00 AM on the set date.

available_to
string <date>

Defines the date, when the product is no longer available. It will remain visible, but can no longer be added to cart. The product will become unavailable at 12:00 AM on the set date.

order_limit
integer

The maximum order limit for the product. Must be more than order_limit_min and greater than 0.

order_limit_min
integer

The minimum order limit for the product. Must be less than order_limit and greater than 0.

visible_from
string <date-time>

Defines the date and time, when the product becomes visible (not available for buying, see purchasable_from.) See list of accepted values here: https://secure.php.net/manual/en/function.date.php

purchasable_from
string <date-time>

Defines the date and time, when the product can be added to the cart. If available_to is set, the product can no longer be bought after the date set there. See list of accepted values here: https://secure.php.net/manual/en/function.date.php

seo_title
string

The SEO document title. Shown, for example, in Google search results as the title.

seo_page_title
string

The SEO page title. Shown on the page, in place of the usual page title, if set.

seo_meta_description
string

The SEO meta description. Shown, for example, in Google search results as the page description.

translations
Array of any

Array of translations for the product's multilingual fields.

object

Responses

Request samples

Content type
application/json
{
  • "product_code": "AE-12345-89",
  • "supplier_code": "876567890",
  • "name": "Dress",
  • "description": "<p>Spectacular and stylish gem of the dinner party!</p>",
  • "information": "<p><strong>length</strong>: long<br />\\n<strong>color</strong>: unicolor<br />\\n<strong>total length</strong>: 160 cm in size M<br />\\n<strong>outer material</strong>: 50 % cottom, 50 % flax<br />\\n<strong>care and maintenance</strong>: no drum drying, machine wash in 30°C</p>",
  • "keywords": "mekot, juhlamekot, puuvilla, pellava",
  • "price": 159.95,
  • "purchase_price": 120,
  • "vat_rate": 24,
  • "weight": 1.25,
  • "warranty": 12,
  • "brand_id": 5,
  • "supplier_id": 3,
  • "available_from": "2021-03-01",
  • "available_to": "2021-05-01",
  • "order_limit": 10,
  • "order_limit_min": 1,
  • "visible_from": "2017-12-31T23:20:50.52+02:00",
  • "purchasable_from": "2017-12-31T23:20:50.52+02:00",
  • "seo_title": "Document title",
  • "seo_page_title": "Page title",
  • "seo_meta_description": "Meta description",
  • "translations": [
    ],
  • "category_links": {
    }
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "product_code": "AE-12345-89",
  • "supplier_code": "876567890",
  • "name": "Dress",
  • "description": "<p>Spectacular and stylish gem of the dinner party!</p>",
  • "information": "<p><strong>length</strong>: long<br />\\n<strong>color</strong>: unicolor<br />\\n<strong>total length</strong>: 160 cm in size M<br />\\n<strong>outer material</strong>: 50 % cottom, 50 % flax<br />\\n<strong>care and maintenance</strong>: no drum drying, machine wash in 30°C</p>",
  • "keywords": "mekot, juhlamekot, puuvilla, pellava",
  • "price": 159.95,
  • "purchase_price": 120,
  • "vat_rate": 24,
  • "weight": 1.25,
  • "warranty": 12,
  • "brand_id": 5,
  • "supplier_id": 3,
  • "available_from": "2021-03-01",
  • "available_to": "2021-05-01",
  • "order_limit": 10,
  • "order_limit_min": 1,
  • "visible_from": "2017-12-31T23:20:50.52+02:00",
  • "purchasable_from": "2017-12-31T23:20:50.52+02:00",
  • "seo_title": "Document title",
  • "seo_page_title": "Page title",
  • "seo_meta_description": "Meta description",
  • "translations": [
    ],
  • "visibilities": [
    ],
  • "category_links": {
    },
  • "image_links": [
    ],
  • "features": {
    },
  • "variations": {
    },
  • "brand": {
    },
  • "stock_item": {
    }
}

Retrieve a product

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

query Parameters
expand
string
Enum: "translations" "visibilities" "category_links" "image_links" "features" "variations" "variations.features" "variations.stock_item" "brand" "stock_item"

Comma-separated list of expandable sub-resources.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "product_code": "AE-12345-89",
  • "supplier_code": "876567890",
  • "name": "Dress",
  • "description": "<p>Spectacular and stylish gem of the dinner party!</p>",
  • "information": "<p><strong>length</strong>: long<br />\\n<strong>color</strong>: unicolor<br />\\n<strong>total length</strong>: 160 cm in size M<br />\\n<strong>outer material</strong>: 50 % cottom, 50 % flax<br />\\n<strong>care and maintenance</strong>: no drum drying, machine wash in 30°C</p>",
  • "keywords": "mekot, juhlamekot, puuvilla, pellava",
  • "price": 159.95,
  • "purchase_price": 120,
  • "vat_rate": 24,
  • "weight": 1.25,
  • "warranty": 12,
  • "brand_id": 5,
  • "supplier_id": 3,
  • "available_from": "2021-03-01",
  • "available_to": "2021-05-01",
  • "order_limit": 10,
  • "order_limit_min": 1,
  • "visible_from": "2017-12-31T23:20:50.52+02:00",
  • "purchasable_from": "2017-12-31T23:20:50.52+02:00",
  • "seo_title": "Document title",
  • "seo_page_title": "Page title",
  • "seo_meta_description": "Meta description",
  • "translations": [
    ],
  • "visibilities": [
    ],
  • "category_links": {
    },
  • "image_links": [
    ],
  • "features": {
    },
  • "variations": {
    },
  • "brand": {
    },
  • "stock_item": {
    }
}

Modify a product

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

Request Body schema: application/json
product_code
string

The product code

supplier_code
string

The supplier's product code

name
required
string

The product name. Required in either the POST / PATCH body or in the translations array, when managing multilingual content.

description
string

The short product description. Can be included in either the POST / PATCH body or in the translations array, when managing multilingual content.

information
string

The long product description. Can be included in either the POST / PATCH body or in the translations array, when managing multilingual content.

keywords
string

Comma-separated list of keywords. Used by the internal search engine.

price
number

The product price including VAT. The tax free price is calculated based on the vat_rate field.

purchase_price
number

The product's purchase price. Always exclude VAT.

vat_rate
integer

The product's VAT rate. If not included when creating a product, the product will have VAT 0 %.

weight
number

The weight of the product in kilograms

warranty
integer

The warranty period in months

brand_id
integer >= 1

ID of the product's brand

supplier_id
integer >= 1

ID of the product's supplier

available_from
string <date>

Defines the date, when the product becomes available. If visible_from and/or purchasable_from are not set, the product is visible and purchasable by default. The product will become available at 12:00 AM on the set date.

available_to
string <date>

Defines the date, when the product is no longer available. It will remain visible, but can no longer be added to cart. The product will become unavailable at 12:00 AM on the set date.

order_limit
integer

The maximum order limit for the product. Must be more than order_limit_min and greater than 0.

order_limit_min
integer

The minimum order limit for the product. Must be less than order_limit and greater than 0.

visible_from
string <date-time>

Defines the date and time, when the product becomes visible (not available for buying, see purchasable_from.) See list of accepted values here: https://secure.php.net/manual/en/function.date.php

purchasable_from
string <date-time>

Defines the date and time, when the product can be added to the cart. If available_to is set, the product can no longer be bought after the date set there. See list of accepted values here: https://secure.php.net/manual/en/function.date.php

seo_title
string

The SEO document title. Shown, for example, in Google search results as the title.

seo_page_title
string

The SEO page title. Shown on the page, in place of the usual page title, if set.

seo_meta_description
string

The SEO meta description. Shown, for example, in Google search results as the page description.

translations
Array of any

Array of translations for the product's multilingual fields.

object

Responses

Request samples

Content type
application/json
{
  • "product_code": "AE-12345-89",
  • "supplier_code": "876567890",
  • "name": "Dress",
  • "description": "<p>Spectacular and stylish gem of the dinner party!</p>",
  • "information": "<p><strong>length</strong>: long<br />\\n<strong>color</strong>: unicolor<br />\\n<strong>total length</strong>: 160 cm in size M<br />\\n<strong>outer material</strong>: 50 % cottom, 50 % flax<br />\\n<strong>care and maintenance</strong>: no drum drying, machine wash in 30°C</p>",
  • "keywords": "mekot, juhlamekot, puuvilla, pellava",
  • "price": 159.95,
  • "purchase_price": 120,
  • "vat_rate": 24,
  • "weight": 1.25,
  • "warranty": 12,
  • "brand_id": 5,
  • "supplier_id": 3,
  • "available_from": "2021-03-01",
  • "available_to": "2021-05-01",
  • "order_limit": 10,
  • "order_limit_min": 1,
  • "visible_from": "2017-12-31T23:20:50.52+02:00",
  • "purchasable_from": "2017-12-31T23:20:50.52+02:00",
  • "seo_title": "Document title",
  • "seo_page_title": "Page title",
  • "seo_meta_description": "Meta description",
  • "translations": [
    ],
  • "category_links": {
    }
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "product_code": "AE-12345-89",
  • "supplier_code": "876567890",
  • "name": "Dress",
  • "description": "<p>Spectacular and stylish gem of the dinner party!</p>",
  • "information": "<p><strong>length</strong>: long<br />\\n<strong>color</strong>: unicolor<br />\\n<strong>total length</strong>: 160 cm in size M<br />\\n<strong>outer material</strong>: 50 % cottom, 50 % flax<br />\\n<strong>care and maintenance</strong>: no drum drying, machine wash in 30°C</p>",
  • "keywords": "mekot, juhlamekot, puuvilla, pellava",
  • "price": 159.95,
  • "purchase_price": 120,
  • "vat_rate": 24,
  • "weight": 1.25,
  • "warranty": 12,
  • "brand_id": 5,
  • "supplier_id": 3,
  • "available_from": "2021-03-01",
  • "available_to": "2021-05-01",
  • "order_limit": 10,
  • "order_limit_min": 1,
  • "visible_from": "2017-12-31T23:20:50.52+02:00",
  • "purchasable_from": "2017-12-31T23:20:50.52+02:00",
  • "seo_title": "Document title",
  • "seo_page_title": "Page title",
  • "seo_meta_description": "Meta description",
  • "translations": [
    ],
  • "visibilities": [
    ],
  • "category_links": {
    },
  • "image_links": [
    ],
  • "features": {
    },
  • "variations": {
    },
  • "brand": {
    },
  • "stock_item": {
    }
}

Delete a product

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Retrieve a list of a product's variations

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

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

Create a new variation for a product

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

Request Body schema: application/json
product_id
integer >= 1

The main product's ID. Used to attach the variation to a product.

sort
integer

An integer that determines the variation's location on the main product's variation list.

name
string

The variation name

product_code
string

The variation product code

price
number

The variation price including VAT. The tax free price is calculated based on the main product's VAT rate.

purchase_price
number

The variation purchase price excluding VAT.

weight
number

The variation's weight in kilograms

image_id
integer

The image ID of a product image that will be attached to the variation. You can find out the IDs of product images with GET /api/v1/images

translations
Array of any

An array of translation objects that contain content for any multilingual fields of the variation.

Responses

Request samples

Content type
application/json
{
  • "product_id": 65,
  • "sort": 2,
  • "name": "S",
  • "product_code": "S330",
  • "price": 35.99,
  • "purchase_price": 15.5,
  • "weight": 1.25,
  • "image_id": 5,
  • "translations": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "product_id": 65,
  • "sort": 2,
  • "name": "S",
  • "product_code": "S330",
  • "price": 35.99,
  • "purchase_price": 15.5,
  • "weight": 1.25,
  • "image_id": 5,
  • "translations": [
    ]
}

Retrieve a product variation

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

variationID
required
integer >= 1

Unique identifier for the variation

query Parameters
expand
string
Value: "translations"

Comma-separated list of expandable sub-resources.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "product_id": 65,
  • "sort": 2,
  • "name": "S",
  • "product_code": "S330",
  • "price": 35.99,
  • "purchase_price": 15.5,
  • "weight": 1.25,
  • "image_id": 5,
  • "translations": [
    ]
}

Modify a product variation

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

variationID
required
integer >= 1

Unique identifier for the variation

Request Body schema: application/json
product_id
integer >= 1

The main product's ID. Used to attach the variation to a product.

sort
integer

An integer that determines the variation's location on the main product's variation list.

name
string

The variation name

product_code
string

The variation product code

price
number

The variation price including VAT. The tax free price is calculated based on the main product's VAT rate.

purchase_price
number

The variation purchase price excluding VAT.

weight
number

The variation's weight in kilograms

image_id
integer

The image ID of a product image that will be attached to the variation. You can find out the IDs of product images with GET /api/v1/images

translations
Array of any

An array of translation objects that contain content for any multilingual fields of the variation.

Responses

Request samples

Content type
application/json
{
  • "product_id": 65,
  • "sort": 2,
  • "name": "S",
  • "product_code": "S330",
  • "price": 35.99,
  • "purchase_price": 15.5,
  • "weight": 1.25,
  • "image_id": 5,
  • "translations": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "product_id": 65,
  • "sort": 2,
  • "name": "S",
  • "product_code": "S330",
  • "price": 35.99,
  • "purchase_price": 15.5,
  • "weight": 1.25,
  • "image_id": 5,
  • "translations": [
    ]
}

Delete a product's variation

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

variationID
required
integer >= 1

Unique identifier for the variation

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Modify a product variation's features

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

variationID
required
integer >= 1

Unique identifier for the variation

Request Body schema: application/json
property name*
any

Responses

Request samples

Content type
application/json
{
  • "_color": [
    ],
  • "material": [
    ]
}

Response samples

Content type
application/json
{
  • "_color": [
    ],
  • "material": [
    ]
}

Retrieve a list of a product's customization options

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

query Parameters
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": [
    ]
}

Create a new customization option for a product

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

Request Body schema: application/json
product_id
integer

ID of the product this option belongs to

sort
integer

An integer that determines the product option's location on the option list both in the store's back and front end

type
required
string
Enum: "H3" "TEXT" "TEXTAREA" "SELECT" "RADIO" "CHECKBOX" "FILE"

The HTML element that is displayed to the visitors and used to input data to the product option.

name
required
string

The name of the option field. Will be displayed in the store on the customization form.

help
string

Help text for the option field. Will be displayed in the store on the customization form.

Responses

Request samples

Content type
application/json
{
  • "product_id": 8,
  • "sort": 1,
  • "type": "TEXT",
  • "name": "Painatettava teksti",
  • "help": "Kirjoita tähän teksti, jonka haluat painatettavaksi paitaan."
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "product_id": 8,
  • "sort": 1,
  • "type": "TEXT",
  • "name": "Painatettava teksti",
  • "help": "Kirjoita tähän teksti, jonka haluat painatettavaksi paitaan."
}

Retrieve a specific customization option of a product

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

optionID
required
integer >= 1

Unique identifier for the product option

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "product_id": 8,
  • "sort": 1,
  • "type": "TEXT",
  • "name": "Painatettava teksti",
  • "help": "Kirjoita tähän teksti, jonka haluat painatettavaksi paitaan."
}

Modify a product option

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

optionID
required
integer >= 1

Unique identifier for the product option

Request Body schema: application/json
product_id
integer

ID of the product this option belongs to

sort
integer

An integer that determines the product option's location on the option list both in the store's back and front end

type
required
string
Enum: "H3" "TEXT" "TEXTAREA" "SELECT" "RADIO" "CHECKBOX" "FILE"

The HTML element that is displayed to the visitors and used to input data to the product option.

name
required
string

The name of the option field. Will be displayed in the store on the customization form.

help
string

Help text for the option field. Will be displayed in the store on the customization form.

Responses

Request samples

Content type
application/json
{
  • "product_id": 8,
  • "sort": 1,
  • "type": "TEXT",
  • "name": "Painatettava teksti",
  • "help": "Kirjoita tähän teksti, jonka haluat painatettavaksi paitaan."
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "product_id": 8,
  • "sort": 1,
  • "type": "TEXT",
  • "name": "Painatettava teksti",
  • "help": "Kirjoita tähän teksti, jonka haluat painatettavaksi paitaan."
}

Delete a product's customization option

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

optionID
required
integer >= 1

Unique identifier for the product option

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Retrieve a list of gift cards

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

optionID
required
integer >= 1

Unique identifier for the product option

query Parameters
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": [
    ]
}

Add a new choice to a product's customization option

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

optionID
required
integer >= 1

Unique identifier for the product option

Request Body schema: application/json
product_id
integer

The ID of the product option's main product

option_id
integer

The ID of the option this choice belongs to

sort
integer

An integer that determines the choice's location of the option list both in the store's back and front end

name
string

The name of the choice

price
number

Product option choices may have their own price, which is added to the sales price of the product, when a customer selects the choice.

Responses

Request samples

Content type
application/json
{
  • "product_id": 9,
  • "option_id": 2,
  • "sort": 1,
  • "name": "Spots",
  • "price": 15.99
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "product_id": 9,
  • "option_id": 2,
  • "sort": 1,
  • "name": "Spots",
  • "price": 15.99
}

Retrieve a choice of a product customization option

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

optionID
required
integer >= 1

Unique identifier for the product option

choiceID
required
integer >= 1

Unique identifier for the product option choice

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "product_id": 9,
  • "option_id": 2,
  • "sort": 1,
  • "name": "Spots",
  • "price": 15.99
}

Modify a product option choice

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

optionID
required
integer >= 1

Unique identifier for the product option

choiceID
required
integer >= 1

Unique identifier for the product option choice

Request Body schema: application/json
product_id
integer

The ID of the product option's main product

option_id
integer

The ID of the option this choice belongs to

sort
integer

An integer that determines the choice's location of the option list both in the store's back and front end

name
string

The name of the choice

price
number

Product option choices may have their own price, which is added to the sales price of the product, when a customer selects the choice.

Responses

Request samples

Content type
application/json
{
  • "product_id": 9,
  • "option_id": 2,
  • "sort": 1,
  • "name": "Spots",
  • "price": 15.99
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "product_id": 9,
  • "option_id": 2,
  • "sort": 1,
  • "name": "Spots",
  • "price": 15.99
}

Delete a choice of a product's customization option

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

optionID
required
integer >= 1

Unique identifier for the product option

choiceID
required
integer >= 1

Unique identifier for the product option choice

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Modify a product's features or attach new features to the product

You can create product features by using POST /api/v1/product-attributes

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

Request Body schema: application/json
property name*
any

Responses

Request samples

Content type
application/json
{
  • "_color": [
    ],
  • "material": [
    ]
}

Response samples

Content type
application/json
{
  • "_color": [
    ],
  • "material": [
    ]
}

Retrieve a product's image links

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

query Parameters
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
[
  • {
    }
]

Add a new image for a product

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

Request Body schema: application/json
product_id
integer
image_id
required
integer

Provide either the image ID or the filename, when creating an image link.

sort
integer

An integer that determines the image's position on the list of a product's images

filename
required
string

Provide either the filename or the image ID, when creating an image link.

caption
string

Responses

Request samples

Content type
application/json
{
  • "product_id": 1,
  • "image_id": 2,
  • "sort": 3,
  • "filename": "image.png",
  • "caption": "Product image caption"
}

Response samples

Content type
application/json
{
  • "product_id": 1,
  • "image_id": 2,
  • "sort": 3,
  • "filename": "image.png",
  • "caption": "Product image caption"
}

Detach an image designated by the filename from a product

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

fileName
required
string

The image filename

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Detach an image designated by its ID from a product

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

imageID
required
integer >= 1

Unique identifier for the image

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Retrieve a list of a product's visibilities in different store versions

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

query Parameters
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
[
  • {
    },
  • {
    }
]

Modify a product's visibilities in different store versions

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

Request Body schema: application/json
version_id
integer >= 1

ID of the version, where the item's visibility is toggled.

is_visible
boolean

true = visible in the designated version, false = not visible.

Responses

Request samples

Content type
application/json
{
  • "version_id": 1,
  • "is_visible": false
}

Response samples

Content type
application/json
{
  • "version_id": 1,
  • "is_visible": false
}

Retrieve a list of a product's translations

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

query Parameters
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
{
  • "language": "fi",
  • "name": "Dress",
  • "description": "<p>Spectacular and stylish gem of the dinner party!</p>",
  • "information": "<p><strong>length</strong>: long<br />\\n<strong>color</strong>: unicolor<br />\\n<strong>total length</strong>: 160 cm in size M<br />\\n<strong>outer material</strong>: 50 % cottom, 50 % flax<br />\\n<strong>care and maintenance</strong>: no drum drying, machine wash in 30°C</p>"
}

Modify a product's translations

Authorizations:
HTTP Basic Access Authentication
path Parameters
productID
required
integer >= 1

Unique identifier for the product

Request Body schema: application/json
language
string
Enum: "fi" "en" "de" "ru" "se" "ee" "cn" "es" "jp" "it" "fr" "pt" "ee" "is" "no" "da" "nl"
name
string

The product name. Required in either the POST / PATCH body or in the translations array, when managing multilingual content.

description
string

The short product description. Can be included in either the POST / PATCH body or in the translations array, when managing multilingual content.

information
string

The long product description. Can be included in either the POST / PATCH body or in the translations array, when managing multilingual content.

Responses

Request samples

Content type
application/json
{
  • "language": "fi",
  • "name": "Dress",
  • "description": "<p>Spectacular and stylish gem of the dinner party!</p>",
  • "information": "<p><strong>length</strong>: long<br />\\n<strong>color</strong>: unicolor<br />\\n<strong>total length</strong>: 160 cm in size M<br />\\n<strong>outer material</strong>: 50 % cottom, 50 % flax<br />\\n<strong>care and maintenance</strong>: no drum drying, machine wash in 30°C</p>"
}

Response samples

Content type
application/json
{
  • "language": "fi",
  • "name": "Dress",
  • "description": "<p>Spectacular and stylish gem of the dinner party!</p>",
  • "information": "<p><strong>length</strong>: long<br />\\n<strong>color</strong>: unicolor<br />\\n<strong>total length</strong>: 160 cm in size M<br />\\n<strong>outer material</strong>: 50 % cottom, 50 % flax<br />\\n<strong>care and maintenance</strong>: no drum drying, machine wash in 30°C</p>"
}

Retrieve a product using its product code

Authorizations:
HTTP Basic Access Authentication
path Parameters
productCode
required
string

The unique product code assigned to the product

query Parameters
expand
string
Enum: "translations" "visibilities" "category_links" "image_links" "features" "variations" "variations.features" "variations.stock_item" "brand" "stock_item"

Comma-separated list of expandable sub-resources.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "product_code": "AE-12345-89",
  • "supplier_code": "876567890",
  • "name": "Dress",
  • "description": "<p>Spectacular and stylish gem of the dinner party!</p>",
  • "information": "<p><strong>length</strong>: long<br />\\n<strong>color</strong>: unicolor<br />\\n<strong>total length</strong>: 160 cm in size M<br />\\n<strong>outer material</strong>: 50 % cottom, 50 % flax<br />\\n<strong>care and maintenance</strong>: no drum drying, machine wash in 30°C</p>",
  • "keywords": "mekot, juhlamekot, puuvilla, pellava",
  • "price": 159.95,
  • "purchase_price": 120,
  • "vat_rate": 24,
  • "weight": 1.25,
  • "warranty": 12,
  • "brand_id": 5,
  • "supplier_id": 3,
  • "available_from": "2021-03-01",
  • "available_to": "2021-05-01",
  • "order_limit": 10,
  • "order_limit_min": 1,
  • "visible_from": "2017-12-31T23:20:50.52+02:00",
  • "purchasable_from": "2017-12-31T23:20:50.52+02:00",
  • "seo_title": "Document title",
  • "seo_page_title": "Page title",
  • "seo_meta_description": "Meta description",
  • "translations": [
    ],
  • "visibilities": [
    ],
  • "category_links": {
    },
  • "image_links": [
    ],
  • "features": {
    },
  • "variations": {
    },
  • "brand": {
    },
  • "stock_item": {
    }
}

Retrieve a product using its supplier code

Authorizations:
HTTP Basic Access Authentication
path Parameters
supplierCode
required
string

The supplier's product code

query Parameters
expand
string
Enum: "translations" "visibilities" "category_links" "image_links" "features" "variations" "variations.features" "variations.stock_item" "brand" "stock_item"

Comma-separated list of expandable sub-resources.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "product_code": "AE-12345-89",
  • "supplier_code": "876567890",
  • "name": "Dress",
  • "description": "<p>Spectacular and stylish gem of the dinner party!</p>",
  • "information": "<p><strong>length</strong>: long<br />\\n<strong>color</strong>: unicolor<br />\\n<strong>total length</strong>: 160 cm in size M<br />\\n<strong>outer material</strong>: 50 % cottom, 50 % flax<br />\\n<strong>care and maintenance</strong>: no drum drying, machine wash in 30°C</p>",
  • "keywords": "mekot, juhlamekot, puuvilla, pellava",
  • "price": 159.95,
  • "purchase_price": 120,
  • "vat_rate": 24,
  • "weight": 1.25,
  • "warranty": 12,
  • "brand_id": 5,
  • "supplier_id": 3,
  • "available_from": "2021-03-01",
  • "available_to": "2021-05-01",
  • "order_limit": 10,
  • "order_limit_min": 1,
  • "visible_from": "2017-12-31T23:20:50.52+02:00",
  • "purchasable_from": "2017-12-31T23:20:50.52+02:00",
  • "seo_title": "Document title",
  • "seo_page_title": "Page title",
  • "seo_meta_description": "Meta description",
  • "translations": [
    ],
  • "visibilities": [
    ],
  • "category_links": {
    },
  • "image_links": [
    ],
  • "features": {
    },
  • "variations": {
    },
  • "brand": {
    },
  • "stock_item": {
    }
}

Shipping Methods

Retrieve a list of shipping methods

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

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Retrieve a shipping method

Authorizations:
HTTP Basic Access Authentication
path Parameters
shippingMethodID
required
integer >= 1

Unique identifier for the shipping method

query Parameters
expand
string
Value: "translations"

Comma-separated list of expandable sub-resources.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "name": "Posti Postipaketti",
  • "type": "DISPATCH",
  • "service_provider": "SHIPIT",
  • "service_code": "plscm.p19fi",
  • "product_code": "POSTI123",
  • "description": "Delivery to a package locker in 1–3 days.",
  • "tracking_info": "Tracking code is included in the order confirmation email.",
  • "free_shipping_threshold": 50,
  • "sort": 2,
  • "translations": [
    ],
  • "visibilities": [
    ]
}

Modify a shipping method

Authorizations:
HTTP Basic Access Authentication
path Parameters
shippingMethodID
required
integer >= 1

Unique identifier for the shipping method

Request Body schema: application/json
name
string

Name of the shipping method

product_code
string

Product code assigned to the shipping method

description
string

The shipping method description.

tracking_info
string

The tracking info for the shipping method. Accepts HTML content.

free_shipping_threshold
integer

The order total in EUR that enables free shipping with the shipping method.

sort
integer

The sorting number for the shipping method

translations
Array of any

Array of translations for multilingual fields of the shipping method

Responses

Request samples

Content type
application/json
{
  • "name": "Posti Postipaketti",
  • "product_code": "POSTI123",
  • "description": "Delivery to a package locker in 1–3 days.",
  • "tracking_info": "Tracking code is included in the order confirmation email.",
  • "free_shipping_threshold": 50,
  • "sort": 2,
  • "translations": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "name": "Posti Postipaketti",
  • "type": "DISPATCH",
  • "service_provider": "SHIPIT",
  • "service_code": "plscm.p19fi",
  • "product_code": "POSTI123",
  • "description": "Delivery to a package locker in 1–3 days.",
  • "tracking_info": "Tracking code is included in the order confirmation email.",
  • "free_shipping_threshold": 50,
  • "sort": 2,
  • "translations": [
    ],
  • "visibilities": [
    ]
}

Retrieve a shipping method's costs

Authorizations:
HTTP Basic Access Authentication
path Parameters
shippingMethodID
required
integer >= 1

Unique identifier for the shipping method

query Parameters
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": [
    ]
}

SMS Subscribers

Retrieve a list of SMS marketing subscribers

Authorizations:
HTTP Basic Access Authentication
query Parameters
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" "subscribed_at-asc" "subscribed_at-desc" "unsubscribed_at-asc" "unsubscribed_at-desc"
Example: sort=id-asc

Determines the sorting of the response list.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Add new SMS subsciber

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
phone
required
string

The subscriber's phone number

version_id
integer >= 1

The subscriber's default version.

Responses

Request samples

Content type
application/json
{
  • "phone": "+358453613825",
  • "version_id": 1
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "phone": "+358453613825",
  • "country": "fi",
  • "language": "fi",
  • "version_id": 1,
  • "subscribed_at": "2013-06-23T12:27:51+03:00",
  • "unsubscribed_at": "2013-06-23T12:27:51+03:00"
}

Retrieve an SMS subscriber

Authorizations:
HTTP Basic Access Authentication
query Parameters
subscriberPhone
string
Example: subscriberPhone=+358452623825

The subscriber's phone number.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "phone": "+358453613825",
  • "country": "fi",
  • "language": "fi",
  • "version_id": 1,
  • "subscribed_at": "2013-06-23T12:27:51+03:00",
  • "unsubscribed_at": "2013-06-23T12:27:51+03:00"
}

Unsubscribe an SMS subscriber

Authorizations:
HTTP Basic Access Authentication
query Parameters
subscriberPhone
string
Example: subscriberPhone=+358452623825

The subscriber's phone number.

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Stock

Retrieve a list of stock items

Authorizations:
HTTP Basic Access Authentication
query Parameters
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
[
  • {
    }
]

Retrieve a product's stock item using the product code

Authorizations:
HTTP Basic Access Authentication
path Parameters
productCode
required
string

The unique product code assigned to the product

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "barcode": "5678987654",
  • "location": "Hylly 6, paikka 8",
  • "enabled": true,
  • "quantity": 28,
  • "reserved": 3,
  • "balance": 25,
  • "balance_alert": false,
  • "balance_limit": 5,
  • "backorder_enabled": false,
  • "backorder_estimate": "14",
  • "code": "98765456AF",
  • "product_id": 5,
  • "variation_id": 78
}

Modify a stock item

Authorizations:
HTTP Basic Access Authentication
path Parameters
productCode
required
string

The unique product code assigned to the product

Request Body schema: application/json
barcode
string
location
string
enabled
boolean

Determines, whether stock management is enabled for the stock item.

quantity
integer

The current amount of items in stock. Used to calculate the balance.

reserved
integer

Amount of reservations. Read-only. Reservations are calculated from pending orders that contain products or variations this stock item is attached to.

balance
integer

The current amount of items in storage. When retrieving the balance it is automatically calculated followingly: (quantity) - (reserved)

balance_alert
boolean
Default: false

Determines whether to use stock alert with this sotck item.

balance_limit
integer

The number of items that will trigger the stock alarm, if balance_alert is set to true.

backorder_enabled
boolean

Determines whether the item will be kept on sale, after its stock has run out.

backorder_estimate
string

The alternative delivery time estimate, when the stock item has run out, and backorders are enabled.

code
string

The product code of the product the stock item is attached to. Used to retrieve individual stock items.

product_id
integer >= 1

ID of the product this stock item is attached to

variation_id
integer >= 1

ID of the product variation this stock item is attached to

Responses

Request samples

Content type
application/json
{
  • "barcode": "5678987654",
  • "location": "Hylly 6, paikka 8",
  • "enabled": true,
  • "quantity": 28,
  • "reserved": 3,
  • "balance": 25,
  • "balance_alert": false,
  • "balance_limit": 5,
  • "backorder_enabled": false,
  • "backorder_estimate": "14",
  • "code": "98765456AF",
  • "product_id": 5,
  • "variation_id": 78
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "barcode": "5678987654",
  • "location": "Hylly 6, paikka 8",
  • "enabled": true,
  • "quantity": 28,
  • "reserved": 3,
  • "balance": 25,
  • "balance_alert": false,
  • "balance_limit": 5,
  • "backorder_enabled": false,
  • "backorder_estimate": "14",
  • "code": "98765456AF",
  • "product_id": 5,
  • "variation_id": 78
}

Update the balance of the stock item

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
balance_update
required
integer

The amount added to or subtracted from the stock balance.

Responses

Request samples

Content type
application/json
{
  • "balance_update": -4
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "barcode": "5678987654",
  • "location": "Hylly 6, paikka 8",
  • "enabled": true,
  • "quantity": 28,
  • "reserved": 3,
  • "balance": 25,
  • "balance_alert": false,
  • "balance_limit": 5,
  • "backorder_enabled": false,
  • "backorder_estimate": "14",
  • "code": "98765456AF",
  • "product_id": 5,
  • "variation_id": 78
}

Retrieve a list of stock changes

Authorizations:
HTTP Basic Access Authentication
query Parameters
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
[
  • {
    }
]

Retrieve a list of stock locations

Authorizations:
HTTP Basic Access Authentication

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get stock location

Authorizations:
HTTP Basic Access Authentication
path Parameters
locationCode
required
string

Responses

Response samples

Content type
application/json
{
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "name": "London warehouse",
  • "code": "london-1"
}

Create stock location

The code designated in the path of the PUT request will be assigned to the newly created stock location.

Authorizations:
HTTP Basic Access Authentication
path Parameters
locationCode
required
string
Request Body schema: application/json
name
required
string

Name of the stock location

Responses

Request samples

Content type
application/json
{
  • "name": "London warehouse"
}

Response samples

Content type
application/json
{
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "name": "London warehouse",
  • "code": "london-1"
}

Delete stock location

Authorizations:
HTTP Basic Access Authentication
path Parameters
locationCode
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

List stock quantities by product code

Authorizations:
HTTP Basic Access Authentication
path Parameters
productCode
required
string

Unique product code of the product whose quantities you wish to handle

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Update stock quantities by product code

Authorizations:
HTTP Basic Access Authentication
path Parameters
productCode
required
string

Unique product code of the product whose quantities you wish to handle

Request Body schema: application/json
Array of objects

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Delete the entire stock quantity of a product in the specified stock location

Authorizations:
HTTP Basic Access Authentication
path Parameters
productCode
required
string

Unique product code of the product whose stock quantities you want to handle

locationCode
required
string

The stock location code

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Suppliers

Retrieve a list of suppliers

Authorizations:
HTTP Basic Access Authentication
query Parameters
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": [
    ],
  • "meta": {
    }
}

Create a new supplier

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
name
required
string

The supplier's name

phone
string

The supplier's phone number

email
string

The supplier's email address

url
string

The supplier's website address

Responses

Request samples

Content type
application/json
{
  • "name": "Hyvien tuotteiden maahantuonti Oy",
  • "phone": "0504141421",
  • "email": "mail@example.com",
  • "url": "www.maahantuonti.fi"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "name": "Hyvien tuotteiden maahantuonti Oy",
  • "phone": "0504141421",
  • "email": "mail@example.com",
  • "url": "www.maahantuonti.fi"
}

Retrieve a supplier

Authorizations:
HTTP Basic Access Authentication
path Parameters
supplierID
required
integer >= 1

Unique identifier for the supplier

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "name": "Hyvien tuotteiden maahantuonti Oy",
  • "phone": "0504141421",
  • "email": "mail@example.com",
  • "url": "www.maahantuonti.fi"
}

Modify a supplier

Authorizations:
HTTP Basic Access Authentication
path Parameters
supplierID
required
integer >= 1

Unique identifier for the supplier

Request Body schema: application/json
name
required
string

The supplier's name

phone
string

The supplier's phone number

email
string

The supplier's email address

url
string

The supplier's website address

Responses

Request samples

Content type
application/json
{
  • "name": "Hyvien tuotteiden maahantuonti Oy",
  • "phone": "0504141421",
  • "email": "mail@example.com",
  • "url": "www.maahantuonti.fi"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "name": "Hyvien tuotteiden maahantuonti Oy",
  • "phone": "0504141421",
  • "email": "mail@example.com",
  • "url": "www.maahantuonti.fi"
}

Delete a supplier

Authorizations:
HTTP Basic Access Authentication
path Parameters
supplierID
required
integer >= 1

Unique identifier for the supplier

Responses

Response samples

Content type
application/json
{
  • "error": "<error message>",
  • "description": "<error description>"
}

Versions

Retrieve a list of store versions

Authorizations:
HTTP Basic Access Authentication
query Parameters
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": [
    ],
  • "meta": {
    }
}

Retrieve a store version

Authorizations:
HTTP Basic Access Authentication
path Parameters
versionID
required
integer >= 1

Unique identifier for the version

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "created_at": "2013-06-19T20:41:47+03:00",
  • "updated_at": "2013-06-19T20:41:47+03:00",
  • "name": "Suomi",
  • "language": "fi",
  • "url": "en.store.fi",
  • "ssl_enabled": true,
  • "shop_name": "Päivin putiikki",
  • "shop_email": "mail@example.com",
  • "default_country": "de",
  • "default_currency": "EUR",
  • "theme": "barebones",
  • "minimum_order": 100,
  • "sort": 1
}