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.

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:

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": [
    • {
      • "id": 1,
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "updated_at": "2013-06-19T20:41:47+03:00",
      • "code": "group-code",
      • "title": "My banner group",
      • "translations": [
        ]
      }
    ],
  • "meta": {
    • "page": 1,
    • "page_size": 100,
    • "page_count": 3,
    • "item_count": 300
    }
}

Create a banner group

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
required
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": [
    • {
      • "language": "en",
      • "title": "My banner group"
      },
    • {
      • "language": "fi",
      • "title": "Banneriryhmä"
      }
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "code": "group-code",
    • "title": "My banner group",
    • "translations": [
      • {
        },
      • {
        }
      ]
    }
}

Retrieve a banner group

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
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "code": "group-code",
    • "title": "My banner group",
    • "translations": [
      • {
        },
      • {
        }
      ]
    }
}

Modify a banner group

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

Unique identifier for the banner group

Request Body schema: application/json
required
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": [
    • {
      • "language": "en",
      • "title": "My banner group"
      },
    • {
      • "language": "fi",
      • "title": "Banneriryhmä"
      }
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "code": "group-code",
    • "title": "My banner group",
    • "translations": [
      • {
        },
      • {
        }
      ]
    }
}

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": [
    • {
      • "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": "2013-06-19T20:41:47+03:00",
      • "visible_to": "2014-06-19T20:41:47+03:00",
      • "file": "discounts.jpg",
      • "link": "/campaigns/43",
      • "translations": [
        ]
      }
    ],
  • "meta": {
    • "page": 1,
    • "page_size": 100,
    • "page_count": 3,
    • "item_count": 300
    }
}

Create a banner

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
required
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-time>

The date when the banner becomes visible in the store.

visible_to
string <date-time>

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": "2013-06-19T20:41:47+03:00",
  • "visible_to": "2014-06-19T20:41:47+03:00",
  • "file": "discounts.jpg",
  • "link": "/campaigns/43",
  • "translations": [
    • {
      • "language": "en",
      • "title": "Fresh discounts just for this week",
      • "content": "<p>We publish new discounts every week.</p>",
      • "link": "/campaign/42"
      },
    • {
      • "language": "fi",
      • "title": "Uusia tarjouksia vain tälle viikolle.",
      • "content": "<p>Julkaisemme uusia tarjouksia joka viikko.</p>",
      • "link": "/campaign/43"
      }
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "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": "2013-06-19T20:41:47+03:00",
    • "visible_to": "2014-06-19T20:41:47+03:00",
    • "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
{
  • "data": {
    • "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": "2013-06-19T20:41:47+03:00",
    • "visible_to": "2014-06-19T20:41:47+03:00",
    • "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
required
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-time>

The date when the banner becomes visible in the store.

visible_to
string <date-time>

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": "2013-06-19T20:41:47+03:00",
  • "visible_to": "2014-06-19T20:41:47+03:00",
  • "file": "discounts.jpg",
  • "link": "/campaigns/43",
  • "translations": [
    • {
      • "language": "en",
      • "title": "Fresh discounts just for this week",
      • "content": "<p>We publish new discounts every week.</p>",
      • "link": "/campaign/42"
      },
    • {
      • "language": "fi",
      • "title": "Uusia tarjouksia vain tälle viikolle.",
      • "content": "<p>Julkaisemme uusia tarjouksia joka viikko.</p>",
      • "link": "/campaign/43"
      }
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "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": "2013-06-19T20:41:47+03:00",
    • "visible_to": "2014-06-19T20:41:47+03:00",
    • "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
{
  • "data": {
    • "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": "2013-06-19T20:41:47+03:00",
    • "visible_to": "2014-06-19T20:41:47+03:00",
    • "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
required
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-time>

The date when the banner becomes visible in the store.

visible_to
string <date-time>

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": "2013-06-19T20:41:47+03:00",
  • "visible_to": "2014-06-19T20:41:47+03:00",
  • "file": "discounts.jpg",
  • "link": "/campaigns/43",
  • "translations": [
    • {
      • "language": "en",
      • "title": "Fresh discounts just for this week",
      • "content": "<p>We publish new discounts every week.</p>",
      • "link": "/campaign/42"
      },
    • {
      • "language": "fi",
      • "title": "Uusia tarjouksia vain tälle viikolle.",
      • "content": "<p>Julkaisemme uusia tarjouksia joka viikko.</p>",
      • "link": "/campaign/43"
      }
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "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": "2013-06-19T20:41:47+03:00",
    • "visible_to": "2014-06-19T20:41:47+03:00",
    • "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": [
    • {
      • "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": [
        ]
      }
    ],
  • "meta": {
    • "page": 1,
    • "page_size": 100,
    • "page_count": 3,
    • "item_count": 300
    }
}

Create a brand

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

The brand name

description
string

The brand description. Accepts HTML content.

seo_title
string (seo_title)

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

seo_page_title
string (seo_page_title)

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

seo_meta_description
string (seo_meta_description)

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": [
    • {
      • "language": "en",
      • "description": "<p>We publish new discounts every week.</p>",
      • "seo_title": "Bernard's products",
      • "seo_page_title": "Bernard's",
      • "seo_meta_description": "Finest Bernard's products"
      },
    • {
      • "language": "fi",
      • "description": "<p>Julkaisemme uusia tarjouksia joka viikko.</p>",
      • "seo_title": "Bernard's-tuotteet",
      • "seo_page_title": "Bernard's",
      • "seo_meta_description": "Hienoimmat Bernard's-tuotteet"
      }
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "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": [
      • {
        },
      • {
        }
      ]
    }
}

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
{
  • "data": {
    • "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
required
Object (Brand PATCH)

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "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": [
    • {
      • "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": [
        ]
      }
    ],
  • "meta": {
    • "page": 1,
    • "page_size": 100,
    • "page_count": 3,
    • "item_count": 300
    }
}

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
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "published": true,
    • "conditions": {
      • "time": {
        },
      • "code": "ALE123",
      • "customers": {
        }
      },
    • "discounts": {
      • "products": {
        },
      • "free_shipping": {
        },
      • "discount_row": {
        }
      },
    • "page": {
      • "description": "<p>All product -25 % for the summer. Act now, don't miss out!</p>",
      • "enabled": true,
      • "image": "image.png",
      • "link": "/category/6",
      • "pinned": false,
      • "template": "campaign/campaign-alternative"
      },
    • "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
required
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": [
    • {
      • "language": "fi",
      • "name": "Macbook-ale",
      • "description": "Kaikki Macbookit nyt -50 %",
      • "seo_title": "Päivin putiikin Macbook-ale",
      • "seo_page_title": "Kaikki Macbookit nyt -50 %",
      • "seo_meta_description": "Osta Macbook puoleen hintaan"
      },
    • {
      • "language": "en",
      • "name": "Macbook sale!",
      • "description": "All Macbooks now at -50 %",
      • "seo_title": "Macbook sale at Päivi's boutique",
      • "seo_page_title": "All Macbooks now -50 %",
      • "seo_meta_description": "Get your Macbook at half the price."
      }
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "published": true,
    • "conditions": {
      • "time": {
        },
      • "code": "ALE123",
      • "customers": {
        }
      },
    • "discounts": {
      • "products": {
        },
      • "free_shipping": {
        },
      • "discount_row": {
        }
      },
    • "page": {
      • "description": "<p>All product -25 % for the summer. Act now, don't miss out!</p>",
      • "enabled": true,
      • "image": "image.png",
      • "link": "/category/6",
      • "pinned": false,
      • "template": "campaign/campaign-alternative"
      },
    • "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
required
Array
any

Responses

Request samples

Content type
application/json
[
  • {
    • "product_id": 4,
    • "price": 39.99
    },
  • {
    • "product_id": 5,
    • "variation_id": 3,
    • "price": 39.99,
    • "order_limit": 3
    },
  • {
    • "product_id": 4,
    • "download_id": 2,
    • "quantity": 3,
    • "price": 39.99
    }
]

Response samples

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

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

Create a product category

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
required
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": [
    • {
      • "language": "fi",
      • "name": "Kengät",
      • "description": "Hyviä kenkiä"
      },
    • {
      • "language": "en",
      • "name": "Shoes",
      • "description": "Nice shoes"
      }
    ]
}

Response samples

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

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
{
  • "data": {
    • "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
required
parent_id
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
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": [
    • {
      • "language": "fi",
      • "name": "Kengät",
      • "description": "Hyviä kenkiä"
      },
    • {
      • "language": "en",
      • "name": "Shoes",
      • "description": "Nice shoes"
      }
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "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
{
  • "data": {
    • "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
required
parent_id
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
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": [
    • {
      • "language": "fi",
      • "name": "Kengät",
      • "description": "Hyviä kenkiä"
      },
    • {
      • "language": "en",
      • "name": "Shoes",
      • "description": "Nice shoes"
      }
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "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": [
    • {
      • "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": [
        ]
      }
    ],
  • "meta": {
    • "page": 1,
    • "page_size": 100,
    • "page_count": 3,
    • "item_count": 300
    }
}

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
{
  • "data": [
    • {
      • "version_id": 1,
      • "is_visible": false
      }
    ]
}

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
required
Array
version_id
integer >= 1

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

is_visible
boolean

Determines whether the item is visible in the designated version.

Responses

Request samples

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

Response samples

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

Create a customer group

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
required
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
{
  • "data": {
    • "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
{
  • "data": {
    • "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
required
name
string

Name of the customer group

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "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 - 1703044631 (Unix timestamp)
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 - 1703044631 (Unix timestamp)
updated_at-from
string <date-time>
Example: updated_at-from=2017-06-14T20:45:52

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 - 1703044631 (Unix timestamp)
updated_at-to
string <date-time>
Example: updated_at-to=2017-06-14T20:45:52

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 - 1703044631 (Unix timestamp)
last_login_at-from
string <date-time>
Example: last_login_at-from=2017-06-14T20:45:52

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 - 1703044631 (Unix timestamp)
last_login_at-to
string <date-time>
Example: last_login_at-to=2017-06-14T20:45:52

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 - 1703044631 (Unix timestamp)
page_size
integer
Default: 50
Example: page_size=50

Determines the number of items included on a page of the response list.

page
integer
Default: 0
Example: page=2

Determines the page that is retrieved (used only in conjunction with page_size).

sort
string
Default: "id-asc"
Enum: "id-asc" "id-desc"
Example: sort=id-asc

Determines the sorting of the response list.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": 1,
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "updated_at": "2013-06-19T20:41:47+03:00",
      • "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": [
        ]
      }
    ],
  • "meta": {
    • "page": 1,
    • "page_size": 100,
    • "page_count": 3,
    • "item_count": 300
    }
}

Create a new customer account

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
required
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

language
string

The customer's language code

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",
  • "language": "fi"
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "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": {
      • "edi_code": "003721315706",
      • "operator_code": "E204503"
      },
    • "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
{
  • "data": {
    • "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": {
      • "edi_code": "003721315706",
      • "operator_code": "E204503"
      },
    • "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
required
first_name
string

The customer's first name

last_name
string

The customer's last name

login_allowed
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
string

Street address

postal_code
string

Postal code

city
string

City

country
string

Country code

phone
string

Phone number

email
string

Email address

language
string

The customer's language code

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",
  • "language": "fi"
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "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": {
      • "edi_code": "003721315706",
      • "operator_code": "E204503"
      },
    • "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
{
  • "data": [
    • {
      • "id": 1,
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "updated_at": "2013-06-19T20:41:47+03:00",
      • "customer_id": 2,
      • "primary": false,
      • "email": "mail@example.com",
      • "company": "Pulse247 Oy",
      • "first_name": "Example",
      • "last_name": "Customer",
      • "street_address": "Kaivokatu 12",
      • "street_name": "Moussaouistraat",
      • "street_number": "22",
      • "house_extension": "b",
      • "postal_code": "00100",
      • "city": "Helsinki",
      • "country": "fi",
      • "phone": "+3585012312312"
      }
    ]
}

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
{
  • "data": {
    • "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": {
      • "edi_code": "003721315706",
      • "operator_code": "E204503"
      },
    • "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
{
  • "data": {
    • "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": {
      • "edi_code": "003721315706",
      • "operator_code": "E204503"
      },
    • "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.

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

Filters subscribers whose details have been updated at 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 - 1703044631 (Unix timestamp)
updated_at-to
string <date-time>
Example: updated_at-to=2017-06-14T20:45:52

Filters subscribers whose details have been updated at 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 - 1703044631 (Unix timestamp)

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": 1,
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "updated_at": "2013-06-19T20:41:47+03:00",
      • "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"
      }
    ],
  • "meta": {
    • "page": 1,
    • "page_size": 100,
    • "page_count": 3,
    • "item_count": 300
    }
}

Add a new subscriber to your mailing list

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
required
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
{
  • "data": {
    • "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": [
    • {
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "updated_at": "2013-06-19T20:41:47+03:00",
      • "expires_at": "2021-10-20",
      • "code": "DTGZRVGGYPS2YMNC",
      • "notes": "Example content",
      • "balance": 50
      }
    ],
  • "meta": {
    • "page": 1,
    • "page_size": 100,
    • "page_count": 3,
    • "item_count": 300
    }
}

Create a new gift card

If the gift card code is not provided in the POST body, a code will be automatically generated and included in the response.

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

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

code
string

The gift card code

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": "2021-10-20",
  • "code": "DTGZRVGGYPS2YMNC",
  • "notes": "Example content",
  • "balance": 50
}

Response samples

Content type
application/json
{
  • "data": {
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "expires_at": "2021-10-20",
    • "code": "DTGZRVGGYPS2YMNC",
    • "notes": "Example content",
    • "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
{
  • "data": {
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "expires_at": "2021-10-20",
    • "code": "DTGZRVGGYPS2YMNC",
    • "notes": "Example content",
    • "balance": 50
    }
}

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

Request Body schema: application/json
required
expires_at
string <date>

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

code
string

The gift card code

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": "2021-10-20",
  • "code": "DTGZRVGGYPS2YMNC",
  • "notes": "Example content",
  • "balance": 50
}

Response samples

Content type
application/json
{
  • "data": {
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "expires_at": "2021-10-20",
    • "code": "DTGZRVGGYPS2YMNC",
    • "notes": "Example content",
    • "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": [
    • {
      • "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": [
        ]
      }
    ],
  • "meta": {
    • "page": 1,
    • "page_size": 100,
    • "page_count": 3,
    • "item_count": 300
    }
}

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
required
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 (translations)

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
{
  • "filename": "image.png",
  • "translations": [
    • {
      • "language": "fi",
      • "caption": "Esimerkkikuvateksti"
      },
    • {
      • "language": "en",
      • "caption": "Example image caption"
      }
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "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
{
  • "data": {
    • "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
{
  • "data": {
    • "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": [
    • {
      • "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",
      • "translations": [
        ],
      • "visibilities": [
        ]
      }
    ],
  • "meta": {
    • "page": 1,
    • "page_size": 100,
    • "page_count": 3,
    • "item_count": 300
    }
}

Create a new info page

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
required
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",
  • "translations": [
    • {
      • "language": "fi",
      • "name": "Ota yhteyttä",
      • "content": "<p>Alta löydät yhteystietomme</p>{ContactInformation}",
      • "link": "",
      • "seo_title": "Yhteystiedot",
      • "seo_page_title": "Päivin putiikin yhteystiedot",
      • "seo_meta_description": "Ota rohkeasti yhteyttä"
      },
    • {
      • "language": "en",
      • "name": "Contact Us",
      • "content": "<p>Contact info below</p>{ContactInformation}",
      • "link": null,
      • "seo_title": "Contact Information",
      • "seo_page_title": "Contact information for Päivi's boutique",
      • "seo_meta_description": "Don't hesitate to contact us"
      }
    ],
  • "visibilities": [
    • {
      • "version_id": 4,
      • "is_visible": false
      },
    • {
      • "version_id": 3,
      • "is_visible": true
      }
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "parent": 1,
    • "sort": 4,
    • "name": "About Us",
    • "content": "<p>Information about us. Contact using the form below:</p>{ContactForm}",
    • "image": "image.png",
    • "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
{
  • "data": {
    • "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",
    • "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
required
parent
integer

ID of the parent page in the info page menu.

sort
integer

The info page's sorting number.

name
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",
  • "translations": [
    • {
      • "language": "fi",
      • "name": "Ota yhteyttä",
      • "content": "<p>Alta löydät yhteystietomme</p>{ContactInformation}",
      • "link": "",
      • "seo_title": "Yhteystiedot",
      • "seo_page_title": "Päivin putiikin yhteystiedot",
      • "seo_meta_description": "Ota rohkeasti yhteyttä"
      },
    • {
      • "language": "en",
      • "name": "Contact Us",
      • "content": "<p>Contact info below</p>{ContactInformation}",
      • "link": null,
      • "seo_title": "Contact Information",
      • "seo_page_title": "Contact information for Päivi's boutique",
      • "seo_meta_description": "Don't hesitate to contact us"
      }
    ],
  • "visibilities": [
    • {
      • "version_id": 4,
      • "is_visible": false
      },
    • {
      • "version_id": 3,
      • "is_visible": true
      }
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "parent": 1,
    • "sort": 4,
    • "name": "About Us",
    • "content": "<p>Information about us. Contact using the form below:</p>{ContactForm}",
    • "image": "image.png",
    • "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
{
  • "data": {
    • "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": [
    • {
      • "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": [
        ]
      }
    ],
  • "meta": {
    • "page": 1,
    • "page_size": 100,
    • "page_count": 3,
    • "item_count": 300
    }
}

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
required
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 (seo_title)

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

seo_page_title
string (seo_page_title)

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

seo_meta_description
string (seo_meta_description)

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
{
  • "data": {
    • "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
required
subject
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 (seo_title)

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

seo_page_title
string (seo_page_title)

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

seo_meta_description
string (seo_meta_description)

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
{
  • "data": {
    • "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
  • 1703044631 (Unix timestamp)

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
  • 1703044631 (Unix timestamp)

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
  • 1703044631 (Unix timestamp)
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
  • 1703044631 (Unix timestamp)
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
  • 1703044631 (Unix timestamp)
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
  • 1703044631 (Unix timestamp)
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

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
  • 1703044631 (Unix timestamp)
updated_at-to
string <date-time>
Example: updated_at-to=2017-06-14T20:45:52

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
  • 1703044631 (Unix timestamp)

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": 1,
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "updated_at": "2013-06-19T20:41:47+03:00",
      • "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",
      • "custom_data": { },
      • "source": "WEB",
      • "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": [
        ]
      }
    ],
  • "meta": {
    • "page": 1,
    • "page_size": 100,
    • "page_count": 3,
    • "item_count": 300
    }
}

Create a new order

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
required
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 (Customer Information)

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 (Shipping Address)
products
required
Array of any (Order Products) non-empty
Array of objects (Shipments Expand)
Array of objects (Payments)

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": {
    • "email": "mail@example.com",
    • "company": "Pulse247 Oy",
    • "first_name": "Example",
    • "last_name": "Customer",
    • "street_address": "Kaivokatu 12",
    • "street_name": "Moussaouistraat",
    • "street_number": "22",
    • "house_extension": "b",
    • "postal_code": "00100",
    • "city": "Helsinki",
    • "country": "fi",
    • "phone": "+3585012312312"
    },
  • "shipping_address": {
    • "primary": false,
    • "email": "mail@example.com",
    • "company": "Pulse247 Oy",
    • "first_name": "Example",
    • "last_name": "Customer",
    • "street_address": "Kaivokatu 12",
    • "street_name": "Moussaouistraat",
    • "street_number": "22",
    • "house_extension": "b",
    • "postal_code": "00100",
    • "city": "Helsinki",
    • "country": "fi",
    • "phone": "+3585012312312"
    },
  • "products": [
    • {
      • "product_id": 3,
      • "variation_id": 15,
      • "quantity": 1
      },
    • {
      • "product_id": 4,
      • "quantity": 1,
      • "unit_price": 12.95
      }
    ],
  • "shipments": [],
  • "payments": []
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "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": {
      • "type": "CAMPAIGN",
      • "coupon_id": 6,
      • "campaign_id": 4,
      • "code": "ALE25",
      • "value": 12
      },
    • "total": 49.99,
    • "status": "COMPLETED",
    • "details": "Please deliver ASAP, it is an emergency",
    • "custom_data": { },
    • "source": "WEB",
    • "referral_code": "REF123",
    • "shipping_method_id": 5,
    • "shipping_costs": 5.9,
    • "payment_method_id": 6,
    • "payment_costs": 2.5,
    • "customer_information": {
      • "email": "mail@example.com",
      • "company": "Pulse247 Oy",
      • "first_name": "Example",
      • "last_name": "Customer",
      • "street_address": "Kaivokatu 12",
      • "street_name": "Moussaouistraat",
      • "street_number": "22",
      • "house_extension": "b",
      • "postal_code": "00100",
      • "city": "Helsinki",
      • "country": "fi",
      • "phone": "+3585012312312"
      },
    • "shipping_address": {
      • "id": 1,
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "updated_at": "2013-06-19T20:41:47+03:00",
      • "customer_id": 2,
      • "primary": false,
      • "email": "mail@example.com",
      • "company": "Pulse247 Oy",
      • "first_name": "Example",
      • "last_name": "Customer",
      • "street_address": "Kaivokatu 12",
      • "street_name": "Moussaouistraat",
      • "street_number": "22",
      • "house_extension": "b",
      • "postal_code": "00100",
      • "city": "Helsinki",
      • "country": "fi",
      • "phone": "+3585012312312"
      },
    • "comments": [
      • {
        },
      • {
        }
      ],
    • "tax_summary": {
      • "subtotal": {
        },
      • "discount": {
        },
      • "shipping_costs": {
        },
      • "payment_costs": {
        },
      • "total": {
        }
      },
    • "events": {
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "code": "PAYMENT_CHANGED_TO_PAID",
      • "message": "Payment transaction 144 (9,60€) status was changed as paid.",
      • "data": {
        }
      },
    • "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
{
  • "data": {
    • "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": {
      • "type": "CAMPAIGN",
      • "coupon_id": 6,
      • "campaign_id": 4,
      • "code": "ALE25",
      • "value": 12
      },
    • "total": 49.99,
    • "status": "COMPLETED",
    • "details": "Please deliver ASAP, it is an emergency",
    • "custom_data": { },
    • "source": "WEB",
    • "referral_code": "REF123",
    • "shipping_method_id": 5,
    • "shipping_costs": 5.9,
    • "payment_method_id": 6,
    • "payment_costs": 2.5,
    • "customer_information": {
      • "email": "mail@example.com",
      • "company": "Pulse247 Oy",
      • "first_name": "Example",
      • "last_name": "Customer",
      • "street_address": "Kaivokatu 12",
      • "street_name": "Moussaouistraat",
      • "street_number": "22",
      • "house_extension": "b",
      • "postal_code": "00100",
      • "city": "Helsinki",
      • "country": "fi",
      • "phone": "+3585012312312"
      },
    • "shipping_address": {
      • "id": 1,
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "updated_at": "2013-06-19T20:41:47+03:00",
      • "customer_id": 2,
      • "primary": false,
      • "email": "mail@example.com",
      • "company": "Pulse247 Oy",
      • "first_name": "Example",
      • "last_name": "Customer",
      • "street_address": "Kaivokatu 12",
      • "street_name": "Moussaouistraat",
      • "street_number": "22",
      • "house_extension": "b",
      • "postal_code": "00100",
      • "city": "Helsinki",
      • "country": "fi",
      • "phone": "+3585012312312"
      },
    • "comments": [
      • {
        },
      • {
        }
      ],
    • "tax_summary": {
      • "subtotal": {
        },
      • "discount": {
        },
      • "shipping_costs": {
        },
      • "payment_costs": {
        },
      • "total": {
        }
      },
    • "events": {
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "code": "PAYMENT_CHANGED_TO_PAID",
      • "message": "Payment transaction 144 (9,60€) status was changed as paid.",
      • "data": {
        }
      },
    • "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
{
  • "data": {
    • "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": {
      • "type": "CAMPAIGN",
      • "coupon_id": 6,
      • "campaign_id": 4,
      • "code": "ALE25",
      • "value": 12
      },
    • "total": 49.99,
    • "status": "COMPLETED",
    • "details": "Please deliver ASAP, it is an emergency",
    • "custom_data": { },
    • "source": "WEB",
    • "referral_code": "REF123",
    • "shipping_method_id": 5,
    • "shipping_costs": 5.9,
    • "payment_method_id": 6,
    • "payment_costs": 2.5,
    • "customer_information": {
      • "email": "mail@example.com",
      • "company": "Pulse247 Oy",
      • "first_name": "Example",
      • "last_name": "Customer",
      • "street_address": "Kaivokatu 12",
      • "street_name": "Moussaouistraat",
      • "street_number": "22",
      • "house_extension": "b",
      • "postal_code": "00100",
      • "city": "Helsinki",
      • "country": "fi",
      • "phone": "+3585012312312"
      },
    • "shipping_address": {
      • "id": 1,
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "updated_at": "2013-06-19T20:41:47+03:00",
      • "customer_id": 2,
      • "primary": false,
      • "email": "mail@example.com",
      • "company": "Pulse247 Oy",
      • "first_name": "Example",
      • "last_name": "Customer",
      • "street_address": "Kaivokatu 12",
      • "street_name": "Moussaouistraat",
      • "street_number": "22",
      • "house_extension": "b",
      • "postal_code": "00100",
      • "city": "Helsinki",
      • "country": "fi",
      • "phone": "+3585012312312"
      },
    • "comments": [
      • {
        },
      • {
        }
      ],
    • "tax_summary": {
      • "subtotal": {
        },
      • "discount": {
        },
      • "shipping_costs": {
        },
      • "payment_costs": {
        },
      • "total": {
        }
      },
    • "events": {
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "code": "PAYMENT_CHANGED_TO_PAID",
      • "message": "Payment transaction 144 (9,60€) status was changed as paid.",
      • "data": {
        }
      },
    • "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
required
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.

allow_open_invoice_payments
boolean
Default: false

Allow quick processing even if order contains unpaid invoice payments.

If set to false, and the order has open invoice payments, 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,
  • "allow_open_invoice_payments": true,
  • "ignore_payment_activation_errors": true,
  • "tracking_code": "JJFI65229310013494123",
  • "send_emails": false
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "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": {
      • "type": "CAMPAIGN",
      • "coupon_id": 6,
      • "campaign_id": 4,
      • "code": "ALE25",
      • "value": 12
      },
    • "total": 49.99,
    • "status": "COMPLETED",
    • "details": "Please deliver ASAP, it is an emergency",
    • "custom_data": { },
    • "source": "WEB",
    • "referral_code": "REF123",
    • "shipping_method_id": 5,
    • "shipping_costs": 5.9,
    • "payment_method_id": 6,
    • "payment_costs": 2.5,
    • "customer_information": {
      • "email": "mail@example.com",
      • "company": "Pulse247 Oy",
      • "first_name": "Example",
      • "last_name": "Customer",
      • "street_address": "Kaivokatu 12",
      • "street_name": "Moussaouistraat",
      • "street_number": "22",
      • "house_extension": "b",
      • "postal_code": "00100",
      • "city": "Helsinki",
      • "country": "fi",
      • "phone": "+3585012312312"
      },
    • "shipping_address": {
      • "id": 1,
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "updated_at": "2013-06-19T20:41:47+03:00",
      • "customer_id": 2,
      • "primary": false,
      • "email": "mail@example.com",
      • "company": "Pulse247 Oy",
      • "first_name": "Example",
      • "last_name": "Customer",
      • "street_address": "Kaivokatu 12",
      • "street_name": "Moussaouistraat",
      • "street_number": "22",
      • "house_extension": "b",
      • "postal_code": "00100",
      • "city": "Helsinki",
      • "country": "fi",
      • "phone": "+3585012312312"
      },
    • "comments": [
      • {
        },
      • {
        }
      ],
    • "tax_summary": {
      • "subtotal": {
        },
      • "discount": {
        },
      • "shipping_costs": {
        },
      • "payment_costs": {
        },
      • "total": {
        }
      },
    • "events": {
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "code": "PAYMENT_CHANGED_TO_PAID",
      • "message": "Payment transaction 144 (9,60€) status was changed as paid.",
      • "data": {
        }
      },
    • "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
optional
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
{
  • "data": {
    • "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": {
      • "type": "CAMPAIGN",
      • "coupon_id": 6,
      • "campaign_id": 4,
      • "code": "ALE25",
      • "value": 12
      },
    • "total": 49.99,
    • "status": "COMPLETED",
    • "details": "Please deliver ASAP, it is an emergency",
    • "custom_data": { },
    • "source": "WEB",
    • "referral_code": "REF123",
    • "shipping_method_id": 5,
    • "shipping_costs": 5.9,
    • "payment_method_id": 6,
    • "payment_costs": 2.5,
    • "customer_information": {
      • "email": "mail@example.com",
      • "company": "Pulse247 Oy",
      • "first_name": "Example",
      • "last_name": "Customer",
      • "street_address": "Kaivokatu 12",
      • "street_name": "Moussaouistraat",
      • "street_number": "22",
      • "house_extension": "b",
      • "postal_code": "00100",
      • "city": "Helsinki",
      • "country": "fi",
      • "phone": "+3585012312312"
      },
    • "shipping_address": {
      • "id": 1,
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "updated_at": "2013-06-19T20:41:47+03:00",
      • "customer_id": 2,
      • "primary": false,
      • "email": "mail@example.com",
      • "company": "Pulse247 Oy",
      • "first_name": "Example",
      • "last_name": "Customer",
      • "street_address": "Kaivokatu 12",
      • "street_name": "Moussaouistraat",
      • "street_number": "22",
      • "house_extension": "b",
      • "postal_code": "00100",
      • "city": "Helsinki",
      • "country": "fi",
      • "phone": "+3585012312312"
      },
    • "comments": [
      • {
        },
      • {
        }
      ],
    • "tax_summary": {
      • "subtotal": {
        },
      • "discount": {
        },
      • "shipping_costs": {
        },
      • "payment_costs": {
        },
      • "total": {
        }
      },
    • "events": {
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "code": "PAYMENT_CHANGED_TO_PAID",
      • "message": "Payment transaction 144 (9,60€) status was changed as paid.",
      • "data": {
        }
      },
    • "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
{
  • "data": {
    • "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": {
      • "type": "CAMPAIGN",
      • "coupon_id": 6,
      • "campaign_id": 4,
      • "code": "ALE25",
      • "value": 12
      },
    • "total": 49.99,
    • "status": "COMPLETED",
    • "details": "Please deliver ASAP, it is an emergency",
    • "custom_data": { },
    • "source": "WEB",
    • "referral_code": "REF123",
    • "shipping_method_id": 5,
    • "shipping_costs": 5.9,
    • "payment_method_id": 6,
    • "payment_costs": 2.5,
    • "customer_information": {
      • "email": "mail@example.com",
      • "company": "Pulse247 Oy",
      • "first_name": "Example",
      • "last_name": "Customer",
      • "street_address": "Kaivokatu 12",
      • "street_name": "Moussaouistraat",
      • "street_number": "22",
      • "house_extension": "b",
      • "postal_code": "00100",
      • "city": "Helsinki",
      • "country": "fi",
      • "phone": "+3585012312312"
      },
    • "shipping_address": {
      • "id": 1,
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "updated_at": "2013-06-19T20:41:47+03:00",
      • "customer_id": 2,
      • "primary": false,
      • "email": "mail@example.com",
      • "company": "Pulse247 Oy",
      • "first_name": "Example",
      • "last_name": "Customer",
      • "street_address": "Kaivokatu 12",
      • "street_name": "Moussaouistraat",
      • "street_number": "22",
      • "house_extension": "b",
      • "postal_code": "00100",
      • "city": "Helsinki",
      • "country": "fi",
      • "phone": "+3585012312312"
      },
    • "comments": [
      • {
        },
      • {
        }
      ],
    • "tax_summary": {
      • "subtotal": {
        },
      • "discount": {
        },
      • "shipping_costs": {
        },
      • "payment_costs": {
        },
      • "total": {
        }
      },
    • "events": {
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "code": "PAYMENT_CHANGED_TO_PAID",
      • "message": "Payment transaction 144 (9,60€) status was changed as paid.",
      • "data": {
        }
      },
    • "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
required
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
{
  • "data": {
    • "order_id": 0,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "text": "Some disturbances with your order...",
    • "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
{
  • "data": {
    • "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",
    }
}

Activate a payment

Used only with Klarna, Walley (through Paytrail) and Ropo 24 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
{
  • "data": {
    • "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",
    }
}

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

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

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

Add off-hand products to an order

Using this endpoint you can add off-hand products, i.e. products that are not included in your online store's product catalog, to orders.

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

Unique identifier for the order

Request Body schema: application/json
required
list_price
any
product_name
required
any
purchase_price
any
quantity
any
Default: 1
unit_price
required
any
vat_rate
required
any
weight
any

Weight in grams

Responses

Request samples

Content type
application/json
{
  • "list_price": 247,
  • "product_name": "Off-hand product",
  • "purchase_price": 2.47,
  • "quantity": 25,
  • "unit_price": 24.7,
  • "vat_rate": 24,
  • "weight": 200
}

Response samples

Content type
application/json
{
  • "data": {
    • "order_id": 0,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "text": "Some disturbances with your order...",
    • "visibility": "PUBLIC",
    • "update_timestamp": true
    }
}

Change the quantity of a product on an order

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

Unique identifier for the order

orderProductID
required
integer >= 1

Unique identifier for an order product

Request Body schema: application/json
required
quantity
integer >= 1

The quantity of the order product

Responses

Request samples

Content type
application/json
{
  • "quantity": 25
}

Response samples

Content type
application/json
{
  • "id": 161,
  • "created_at": "2022-01-17T10:24:46+02:00",
  • "updated_at": "2022-01-17T10:24:46+02:00",
  • "delivered_at": null,
  • "order_id": 105,
  • "product_id": 0,
  • "variation_id": null,
  • "download_id": null,
  • "download_time_ends": null,
  • "download_times_left": null,
  • "download_url": null,
  • "customizations": null,
  • "vat_rate": 24,
  • "bundle_id": null,
  • "campaign_id": null,
  • "compare_price": 247,
  • "unit_price": 24.7,
  • "purchase_price": 2.47,
  • "quantity": 2,
  • "product_code": null,
  • "product_name": "Off-hand product",
  • "model_name": null,
  • "product_type": null,
  • "warranty": null,
  • "custom_data": null,
  • "shipment_id": 144,
  • "related_id": null,
  • "return_to_stock": null
}

Remove a product from an order

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

Unique identifier for the order

orderProductID
required
integer >= 1

Unique identifier for an order product

Responses

Response samples

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

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
required
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

Request Body schema: application/json
optional
parcel_count
int

Shipment parcel count

Responses

Request samples

Content type
application/json
{
  • "parcel_count": 4
}

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

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
{
  • "data": {
    • "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
required
name
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": [
    • {
      • "language": "fi",
      • "name": "Lasku",
      • "description": "Maksa laskulla, 14 päivää maksuaikaa.",
      • "help": "Lähetämme sähköpostiisi PDF-laskun, joka sisältää tarkat maksutiedot."
      },
    • {
      • "language": "en",
      • "name": "Invoice",
      • "description": "Pay by invoice within 14 days.",
      • "help": "We will email you a PDF invoice that contains further payment details."
      }
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "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": [
      • {
        },
      • {
        }
      ]
    }
}

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

Create a new product attribute

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
required
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": {
    • "fi": "Materiaali",
    • "en": "Material"
    }
}

Response samples

Content type
application/json
{
  • "data": {
    • "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": {
      • "fi": "Materiaali",
      • "en": "Material"
      }
    }
}

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
{
  • "data": {
    • "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": {
      • "fi": "Materiaali",
      • "en": "Material"
      }
    }
}

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
required
code
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
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": {
    • "fi": "Materiaali",
    • "en": "Material"
    }
}

Response samples

Content type
application/json
{
  • "data": {
    • "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": {
      • "fi": "Materiaali",
      • "en": "Material"
      }
    }
}

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

labels
object

Object containing translations for the value's label text.

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
{
  • "data": {
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "code": "string",
    • "sort": 0,
    • "labels": { }
    }
}

Modify a product attribute value

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
required
code
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.

labels
object

Object containing translations for the value's label text.

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "sort": 0,
  • "labels": { }
}

Response samples

Content type
application/json
{
  • "data": {
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "code": "string",
    • "sort": 0,
    • "labels": { }
    }
}

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>"
}

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

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
{
  • "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

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 - 1703044631 (Unix timestamp)
created_at-to
string <date-time>
Example: created_at-to=2017-06-14T20:45:52

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 - 1703044631 (Unix timestamp)
updated_at-from
string <date-time>
Example: updated_at-from=2017-06-14T20:45:52

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 - 1703044631 (Unix timestamp)
updated_at-to
string <date-time>
Example: updated_at-to=2017-06-14T20:45:52

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 - 1703044631 (Unix timestamp)
page_size
integer
Default: 50
Example: page_size=50

Determines the number of items included on a page of the response list.

page
integer
Default: 0
Example: page=2

Determines the page that is retrieved (used only in conjunction with page_size).

sort
string
Default: "id-asc"
Enum: "id-asc" "id-desc"
Example: sort=id-asc

Determines the sorting of the response list.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": 1,
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "updated_at": "2013-06-19T20:41:47+03:00",
      • "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,
      • "parcel_type": "PARCEL",
      • "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": {
        }
      }
    ],
  • "meta": {
    • "page": 1,
    • "page_size": 100,
    • "page_count": 3,
    • "item_count": 300
    }
}

Create a new product

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
required
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

parcel_type
string
Enum: "LETTER" "LARGE_LETTER" "REGISTERED_LETTER" "PARCEL" "LARGE_PARCEL" "LONG_PARCEL" "INSURED_PARCEL" "CARGO" "DIGITAL"

The product's parcel size

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 (seo_title)

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

seo_page_title
string (seo_page_title)

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

seo_meta_description
string (seo_meta_description)

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.

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,
  • "parcel_type": "PARCEL",
  • "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": [
    • {
      • "language": "fi",
      • "name": "Leveäolkaiminen juhlamekko, vihreä",
      • "description": "<p>Näyttävä ja tyylikäs iltajuhlien timantti!</p>",
      • "information": "<p><strong>pituus</strong>: pitkä<br />\\n<strong>kuosi</strong>: yksivärinen<br />\\n<strong>kokonaispituus</strong>: 160 cm koossa M<br />\\n<strong>päällikankaan materiaali</strong>: 50 % puuvilla, 50 % pellava<br />\\n<strong>hoito-ohje</strong>: ei rumpukuivausta, konepesu 30°C</p>,",
      • "seo_title": "Upea vihreä Gary's -juhlamekko,",
      • "seo_page_title": "Upea vihreä Gary's -juhlamekko, puuvillan ja pellavan sekoitusta",
      • "seo_meta_description": "Ajaton ja klassinen muotoilu. Leveät olkaimet tekevät mekosta myös mukavan yllä."
      },
    • {
      • "language": "en",
      • "name": "Dress with wide straps, green",
      • "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>",
      • "seo_title": "Spctacular green Gary's party dress",
      • "seo_page_title": "Spectacular green Gary's party dress, mix of cottom and flax",
      • "seo_meta_description": "Timeless and classic design. Comfy to wear, thanks to wide straps."
      }
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "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,
    • "parcel_type": "PARCEL",
    • "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": {
      • "_color": [
        ],
      • "material": [
        ]
      },
    • "variations": {
      • "id": 1,
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "updated_at": "2013-06-19T20:41:47+03:00",
      • "image_id": 5,
      • "product_id": 65,
      • "sort": 2,
      • "name": "S",
      • "product_code": "S330",
      • "price": 35.99,
      • "purchase_price": 15.5,
      • "weight": 1.25,
      • "features": {
        },
      • "stock_item": {
        }
      },
    • "brand": {
      • "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",
      • "template": "brand/custom-template"
      },
    • "stock_item": {
      • "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 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
{
  • "data": {
    • "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,
    • "parcel_type": "PARCEL",
    • "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": {
      • "_color": [
        ],
      • "material": [
        ]
      },
    • "variations": {
      • "id": 1,
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "updated_at": "2013-06-19T20:41:47+03:00",
      • "image_id": 5,
      • "product_id": 65,
      • "sort": 2,
      • "name": "S",
      • "product_code": "S330",
      • "price": 35.99,
      • "purchase_price": 15.5,
      • "weight": 1.25,
      • "features": {
        },
      • "stock_item": {
        }
      },
    • "brand": {
      • "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",
      • "template": "brand/custom-template"
      },
    • "stock_item": {
      • "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 product

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

Unique identifier for the product

Request Body schema: application/json
required
product_code
string

The product code

supplier_code
string

The supplier's product code

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.

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

parcel_type
string
Enum: "LETTER" "LARGE_LETTER" "REGISTERED_LETTER" "PARCEL" "LARGE_PARCEL" "LONG_PARCEL" "INSURED_PARCEL" "CARGO" "DIGITAL"

The product's parcel size

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 (seo_title)

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

seo_page_title
string (seo_page_title)

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

seo_meta_description
string (seo_meta_description)

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.

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,
  • "parcel_type": "PARCEL",
  • "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": [
    • {
      • "language": "fi",
      • "name": "Leveäolkaiminen juhlamekko, vihreä",
      • "description": "<p>Näyttävä ja tyylikäs iltajuhlien timantti!</p>",
      • "information": "<p><strong>pituus</strong>: pitkä<br />\\n<strong>kuosi</strong>: yksivärinen<br />\\n<strong>kokonaispituus</strong>: 160 cm koossa M<br />\\n<strong>päällikankaan materiaali</strong>: 50 % puuvilla, 50 % pellava<br />\\n<strong>hoito-ohje</strong>: ei rumpukuivausta, konepesu 30°C</p>,",
      • "seo_title": "Upea vihreä Gary's -juhlamekko,",
      • "seo_page_title": "Upea vihreä Gary's -juhlamekko, puuvillan ja pellavan sekoitusta",
      • "seo_meta_description": "Ajaton ja klassinen muotoilu. Leveät olkaimet tekevät mekosta myös mukavan yllä."
      },
    • {
      • "language": "en",
      • "name": "Dress with wide straps, green",
      • "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>",
      • "seo_title": "Spctacular green Gary's party dress",
      • "seo_page_title": "Spectacular green Gary's party dress, mix of cottom and flax",
      • "seo_meta_description": "Timeless and classic design. Comfy to wear, thanks to wide straps."
      }
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "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,
    • "parcel_type": "PARCEL",
    • "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": {
      • "_color": [
        ],
      • "material": [
        ]
      },
    • "variations": {
      • "id": 1,
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "updated_at": "2013-06-19T20:41:47+03:00",
      • "image_id": 5,
      • "product_id": 65,
      • "sort": 2,
      • "name": "S",
      • "product_code": "S330",
      • "price": 35.99,
      • "purchase_price": 15.5,
      • "weight": 1.25,
      • "features": {
        },
      • "stock_item": {
        }
      },
    • "brand": {
      • "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",
      • "template": "brand/custom-template"
      },
    • "stock_item": {
      • "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
      }
    }
}

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

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
required
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": [
    • {
      • "language": "fi",
      • "name": "Vihreä paita"
      },
    • {
      • "language": "en",
      • "name": "Green shirt"
      }
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "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
{
  • "data": {
    • "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
required
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": [
    • {
      • "language": "fi",
      • "name": "Vihreä paita"
      },
    • {
      • "language": "en",
      • "name": "Green shirt"
      }
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "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
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "_color": [
    • "white"
    ],
  • "material": [
    • "cotton",
    • "wool",
    • "silk"
    ]
}

Response samples

Content type
application/json
{
  • "_color": [
    • "white"
    ],
  • "material": [
    • "cotton",
    • "wool",
    • "silk"
    ]
}

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

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
required
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
{
  • "data": {
    • "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
{
  • "data": {
    • "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
required
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
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
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
{
  • "data": {
    • "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 a product option's choices

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

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
required
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
{
  • "data": {
    • "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
{
  • "data": {
    • "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
required
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
{
  • "data": {
    • "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
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "_color": [
    • "white"
    ],
  • "material": [
    • "cotton",
    • "wool",
    • "silk"
    ]
}

Response samples

Content type
application/json
{
  • "_color": [
    • "white"
    ],
  • "material": [
    • "cotton",
    • "wool",
    • "silk"
    ]
}

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
{
  • "data": [
    • {
      • "product_id": 1,
      • "image_id": 2,
      • "sort": 3,
      • "filename": "image.png",
      • "caption": "Product image caption"
      }
    ]
}

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
required
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
{
  • "data": {
    • "product_id": 0,
    • "image_id": 0,
    • "sort": 0,
    • "filename": "string",
    • "caption": "string"
    }
}

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
{
  • "data": [
    • {
      • "version_id": 1,
      • "is_visible": false
      }
    ]
}

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
required
Array
version_id
integer >= 1

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

is_visible
boolean

Determines whether the item is visible in the designated version.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "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
required
language
string (language)
Enum: "fi" "en" "de" "ru" "se" "ee" "cn" "es" "jp" "it" "fr" "pt" "ee" "is" "no" "da" "nl"
name
string (Product-properties-name)

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

description
string (Product-properties-description)

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

information
string (information)

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
{
  • "data": {
    • "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,
    • "parcel_type": "PARCEL",
    • "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": {
      • "_color": [
        ],
      • "material": [
        ]
      },
    • "variations": {
      • "id": 1,
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "updated_at": "2013-06-19T20:41:47+03:00",
      • "image_id": 5,
      • "product_id": 65,
      • "sort": 2,
      • "name": "S",
      • "product_code": "S330",
      • "price": 35.99,
      • "purchase_price": 15.5,
      • "weight": 1.25,
      • "features": {
        },
      • "stock_item": {
        }
      },
    • "brand": {
      • "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",
      • "template": "brand/custom-template"
      },
    • "stock_item": {
      • "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 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
{
  • "data": {
    • "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,
    • "parcel_type": "PARCEL",
    • "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": {
      • "_color": [
        ],
      • "material": [
        ]
      },
    • "variations": {
      • "id": 1,
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "updated_at": "2013-06-19T20:41:47+03:00",
      • "image_id": 5,
      • "product_id": 65,
      • "sort": 2,
      • "name": "S",
      • "product_code": "S330",
      • "price": 35.99,
      • "purchase_price": 15.5,
      • "weight": 1.25,
      • "features": {
        },
      • "stock_item": {
        }
      },
    • "brand": {
      • "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",
      • "template": "brand/custom-template"
      },
    • "stock_item": {
      • "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
      }
    }
}

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

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
{
  • "data": {
    • "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
required
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": [
    • {
      • "language": "fi",
      • "name": "Posti Postipaketti",
      • "description": "Kuljetus noutopisteeseen 1-3 päivän sisällä.",
      • "tracking_info": ""
      },
    • {
      • "language": "en",
      • "name": "Posti Postal Parcel",
      • "description": "Delivery to a package locker in 1–3 days.",
      • "tracking_info": ""
      }
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "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": [
    • {
      • "id": 1,
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "updated_at": "2013-06-19T20:41:47+03:00",
      • "shipping_method_id": 4,
      • "price": 4.2,
      • "max_weight": 80
      }
    ],
  • "meta": {
    • "page": 1,
    • "page_size": 100,
    • "page_count": 3,
    • "item_count": 300
    }
}

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.

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

Filters subscribers whose details have been updated at 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 - 1703044631 (Unix timestamp)
updated_at-to
string <date-time>
Example: updated_at-to=2017-06-14T20:45:52

Filters subscribers whose details have been updated at 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 - 1703044631 (Unix timestamp)

Responses

Response samples

Content type
application/json
[
  • {
    • "id": 1,
    • "phone": "05012312312",
    • "country": "fi",
    • "language": "fi",
    • "version_id": 1,
    • "subscribed_at": "2013-06-19T20:41:47+03:00",
    • "unsubscribed_at": null
    },
  • {
    • "id": 2,
    • "phone": "05012312313",
    • "country": "fi",
    • "language": "fi",
    • "version_id": 1,
    • "subscribed_at": "2013-06-19T20:41:47+03:00",
    • "unsubscribed_at": "2013-06-19T20:41:47+03:00"
    }
]

Add new SMS subsciber

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
required
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
{
  • "data": {
    • "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
{
  • "data": {
    • "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
{
  • "data": [
    • {
      • "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
      }
    ],
  • "meta": {
    • "page": 1,
    • "page_size": 100,
    • "page_count": 3,
    • "item_count": 300
    }
}

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
{
  • "data": {
    • "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
required
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
{
  • "data": {
    • "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
path Parameters
productCode
required
string

The unique product code assigned to the product

Request Body schema: application/json
required
balance_change
required
integer

The amount added to or subtracted from the stock balance.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "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
{
  • "data": [
    • {
      • "id": 1,
      • "changed_at": "2021-03-03T12:57:26+02:00",
      • "user_id": 4,
      • "source_type": "PRODUCT",
      • "source_id": 5,
      • "stock_item_id": 54,
      • "quantity": 4,
      • "quantity_change": -1
      }
    ],
  • "meta": {
    • "page": 1,
    • "page_size": 100,
    • "page_count": 3,
    • "item_count": 300
    }
}

Retrieve a list of stock locations

Authorizations:
HTTP Basic Access Authentication

Responses

Response samples

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

Get stock location

Authorizations:
HTTP Basic Access Authentication
path Parameters
locationCode
required
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    • "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
required
name
required
string

Name of the stock location

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "data": {
    • "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": [
    • {
      • "location": "london-warehouse",
      • "quantity": 5
      }
    ]
}

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
required
Array
location
required
string

The code of the stock location

quantity
required
integer

The product quantity in the specified stock location

Responses

Request samples

Content type
application/json
[
  • {
    • "location": "london-warehouse",
    • "quantity": 5
    }
]

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "location": "london-warehouse",
      • "quantity": 5
      }
    ]
}

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

Create a new supplier

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
required
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
{
  • "data": {
    • "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
{
  • "data": {
    • "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
required
name
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
{
  • "data": {
    • "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": [
    • {
      • "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
      }
    ],
  • "meta": {
    • "page": 1,
    • "page_size": 100,
    • "page_count": 3,
    • "item_count": 300
    }
}

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
{
  • "data": {
    • "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
    }
}

Webhooks

The Webhooks API enables you to subscribe to certain events (topics) in your store and to receive HTTP notifications on those events to the URL of your choosing. For example, you could subscribe to the order.created event, which would send your integration a Webhook HTTP request everytime an order is created in your store.

The Webhooks API will replace the old Webhooks extension in October 2022. The extension will be permanently removed, and all integrations using it need to be migrated over to the new Webhooks API.

For further information about the update, see https://support.mycashflow.com/fi/tiedotteet/uusi-webhooks-api-korvaa-webhooks-laajennuksen

Subscribing to events

Using a Webhook in your integration starts by subscribing to any needed topic types in a MyCashflow store. This is done by using the POST /api/v1/webhooks request and specifying the topic type in the request body:

POST /api/v1/webhooks
{
  "topic": "order.created",
  "expands": [
    "payments",
    "shipments"
  ],
  "url": "https://www.example.com"
}

Upon subscribing you also define a target URL for the Webhook request and possible expandable subresources (for example, you can include shipment details in order Webhooks).

If you want to monitor more than one topic types, you need to send a separate subscription request for each of them.

After subscribing, the store will start sending Webhook notifications to the configured URL per the settings you configured in the subscription requests.

Receiving notifications

When the Webhook is triggered (an order is created), the API sends an HTTP request to the configured URL, where you need to have some sort of system to receive the notification (a custom integration or a 3rd party service).

The body of the HTTP request contains the contains the event data (for example, a JSON object with order data) and the header of the request contains metadata on the event.

The Webhook notification content

The headers of the Webhook request include important details of the Webhook notification:

X-MCF-Webhook-Id: 123e4567-e89b-12d3-a456-426614174000  
X-MCF-Webhook-Shop-Domain: example.mycashflow.fi  
X-MCF-Webhook-Signature: < base64(hmac_sha256(api_key, request_body)) >  
X-MCF-Webhook-Topic: order.created  

Below we go over the contents of these headers:

  • X-MCF-Webhook-Id: The Webhook subscription UUID, which is generated upon subscribing to the Webhook
  • X-MCF-Webhook-Shop-Domain: The default domain of the originating MyCashflow store
  • X-MCF-Webhook-Signature: A unique signature, which is cryptographically generated based on the API user and the Webhook payload
  • X-MCF-Webhook-Topic: The topic type of the Webhook

The body of the Webhook request contains the data of the event (for example, a JSON object containing order data). The structure of the body is the same as when normally retrieving content from the API. You can find the response samples of Webhook requests under the Callbacks section of the POST /api/v1/webhooks request.

Verifying Webhook requests

When the Webhooks API sends notifications about monitored events, you should verify the identity of said notifications in the receiving system. This improves the security of your Webhooks integration, as you can filter out possibly malicious, external requests mimicing the MyCashflow Webhooks API.

The request verification is done based on the HTTP headers and payload of the notification request.

The HTTP header X-MCF-Webhook-Signature contains an HMAC string that is compiled by encrypting (SHA-256 ) and encoding (base64) the request payload and API key of the API user that subscribed to the Webhook.

Below is an example of creating the verification string with PHP:

$signature = base64_encode(
  hash_hmac(
    'sha256',
    $request_body,
    $api_user_password
  )
);

To verify the request, simply compare the resulting reference signature with the content of the request's X-MCF-Webhook-Signature header.

Retrieve a list of webhooks

Authorizations:
HTTP Basic Access Authentication

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "uuid": "083c584d-ae65-11ec-aef4-0242ac130002",
      • "user_id": 2,
      • "topic": "order.created",
      • "expands": [
        ],
      }
    ]
}

Subscribe to a new webhook

Authorizations:
HTTP Basic Access Authentication
Request Body schema: application/json
required
uuid
string
user_id
integer
topic
string
Value: "order.created"
expands
Array of strings
Items Enum: "payments" "shipments" "products" "products.return_reasons" "tax_summary" "comments" "events"
url
string

Responses

Callbacks

Request samples

Content type
application/json
{
  • "uuid": "083c584d-ae65-11ec-aef4-0242ac130002",
  • "user_id": 2,
  • "topic": "order.created",
  • "expands": [
    • "payments",
    • "shipments"
    ],
}

Response samples

Content type
application/json
{
  • "data": {
    • "uuid": "083c584d-ae65-11ec-aef4-0242ac130002",
    • "user_id": 2,
    • "topic": "order.created",
    • "expands": [
      • "payments",
      • "shipments"
      ],
    }
}

Callback payload samples

Callback
POST: Order created
Content type
application/json
{
  • "data": {
    • "id": 1,
    • "created_at": "2013-06-19T20:41:47+03:00",
    • "updated_at": "2013-06-19T20:41:47+03:00",
    • "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": {
      • "type": "CAMPAIGN",
      • "coupon_id": 6,
      • "campaign_id": 4,
      • "code": "ALE25",
      • "value": 12
      },
    • "total": 49.99,
    • "status": "COMPLETED",
    • "details": "Please deliver ASAP, it is an emergency",
    • "custom_data": { },
    • "source": "WEB",
    • "referral_code": "REF123",
    • "shipping_method_id": 5,
    • "shipping_costs": 5.9,
    • "payment_method_id": 6,
    • "payment_costs": 2.5,
    • "customer_information": {
      • "email": "mail@example.com",
      • "company": "Pulse247 Oy",
      • "first_name": "Example",
      • "last_name": "Customer",
      • "street_address": "Kaivokatu 12",
      • "street_name": "Moussaouistraat",
      • "street_number": "22",
      • "house_extension": "b",
      • "postal_code": "00100",
      • "city": "Helsinki",
      • "country": "fi",
      • "phone": "+3585012312312"
      },
    • "shipping_address": {
      • "id": 1,
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "updated_at": "2013-06-19T20:41:47+03:00",
      • "customer_id": 2,
      • "primary": false,
      • "email": "mail@example.com",
      • "company": "Pulse247 Oy",
      • "first_name": "Example",
      • "last_name": "Customer",
      • "street_address": "Kaivokatu 12",
      • "street_name": "Moussaouistraat",
      • "street_number": "22",
      • "house_extension": "b",
      • "postal_code": "00100",
      • "city": "Helsinki",
      • "country": "fi",
      • "phone": "+3585012312312"
      },
    • "comments": [
      • {
        },
      • {
        }
      ],
    • "tax_summary": {
      • "subtotal": {
        },
      • "discount": {
        },
      • "shipping_costs": {
        },
      • "payment_costs": {
        },
      • "total": {
        }
      },
    • "events": {
      • "created_at": "2013-06-19T20:41:47+03:00",
      • "code": "PAYMENT_CHANGED_TO_PAID",
      • "message": "Payment transaction 144 (9,60€) status was changed as paid.",
      • "data": {
        }
      },
    • "products": [
      • {
        },
      • {
        }
      ],
    • "shipments": [],
    • "payments": [
      • {
        }
      ]
    },
  • "meta": {
    • "expands": [
      • "shipments",
      • "products"
      ],
    • "item_count": 1,
    • "webhook_topic": "order.created"
    }
}

Unsubscribe from a webhook

Authorizations:
HTTP Basic Access Authentication
path Parameters
UUID
required
string
Example: 083c584d-ae65-11ec-aef4-0242ac130002

Unique identifier for the webhook

Responses

Response samples

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