MyCashflow API Use Cases

Here you will find useful and practical examples on using various features of the MyCashflow API.

For further information about the MyCashflow REST API's features, see our reference documentation.

Before trying any of these examples out yourself, see the introductory documentation of the API reference page. There we cover important prerequisites for working with the API, including allowed media types, protocols and authentication methods.

In this example we perform the following tasks:

  • Add a product
  • Attach an image to the product
  • Make the product visibile in one version
  • Modify some details of the product.

You can add new products via the API by sending a POST request to the endpoint /api/v1/products. The body of the request must contain at least the name of the product. See example request and JSON body below:

POST /api/v1/products
{
    "name": "Apple 80 GB iPod Video",
    "description": "",
    "information": "* Black iPod with 80 GB hard drive for songs, podcasts, videos, games, and more\r\n* Large, 2.5-inch, 320 x 240 pixel color display screen is 60 percent brighter\r\n* Holds up to 20,000 songs, thousands of photos, and hours of video\r\n* Search function lets you type name of song with Click Wheel for instant results\r\n* Measures 2.4 x 4.1 x 0.55 inches (W x H x D); 1-year limited warranty",
    "keywords": "apple, ipod, mp3 player",
    "price": 332.66,
    "purchase_price": 0,
    "vat_rate": 24,
    "weight": 0.2,
    "brand_id": 13
}

Notice that at the same time we assign the product to the brand with the ID 13.

If the product was added successfully, you will receive a 200 OK response. After adding the product itself, we add a new image to the store's file system and attach it to the product.

Images are added by sending a POST request to the endpoint /api/v1/images. The image can be sent to the in three different ways:

  1. In base64 encoded format
  2. By specifying the local path of an image file
  3. By specifying a remote path of an image file

See further details about adding images in the reference documentation.

Below is an example of a POST body, where we specify the local path of an image:

{
    "filename": "/path/to/image.png"  
}

Again, you will receive a 200 OK response, if the image was added succesfully. After adding the image, we will attach it to the product.

First, find and store the product ID by doing a GET /api/v1/products request. Then create a new image link by sending a POST request to the endpoint /api/v1/products/{productID}/image-links with the following body:

{
    "filename": "image.png",
    "caption": "Uuden tuotteeen ensimmäinen tuotekuva"
}

Once the image link has been created, you will receive a 200 OK response.

Now we make the product visible in one of the store's versions. By default, products – and other resources – created through the API are hidden, so they need to be made visible with a separate PATCH request.

PATCH /api/v1/products/{productId}/visibilities
{
    "version_id": 5,
    "is_visible": true
}

In this example we make the product visible in the version, with the ID 5.

Finally, we make some changes to the product's details. Use the product ID you stored earlier to do a PATCH request to the endpoint /api/v1/products/{productID}. Include any details in the body that you wish to edit:

{
    "name": "Apple 80 GB iPod Video player"
    "purchase_price": 280.00
}

If succesful, fhis request will also return a 200 OK response.

The stock balances of products and variations are defined in stock items, which are attached to them.

An example of a valid PATCH request and JSON body is provided below. Notice that stock items are always identified by the product code of the product or variation they belong to, and not the ID.

PATCH /api/v1/stock/{productCode}
{
  "sku": "A76543456",
  "barcode": "5678987654",
  "location": "Hylly 6, paikka 8",
  "enabled": true,
  "quantity": 6,
  "reserved": 5,
  "balance": 43,
  "balance_alert": true,
  "balance_limit": 3,
  "backorder_enabled": true,
  "backorder_estimate": "2–4 viikkoa"
}

Currently it is not possible to create new stock items via the API, but a new stock item is always created, when you create a new product or variation.

If you need to update the stock balance of a large number of items, we suggest you do not do this one product at a time, instead:

  1. Keep a local copy of the store's stock balances in your API client.
  2. Retrieve the stock items be using GET /api/v1/stock.
  3. Update the stock balances of any required stock items locally.
  4. Once you have updated the stock balances, send the udpated data to the store by doing PATCH /api/v1/stock/{productCode} for each stock item.

This will save a lot of time especially if the store's selection is large (> 10 000 products).

If you need to attach a stock item to a new product or variation, you can change the value of the stock item's code property:

PATCH /api/v1/stock/{productCode}
{
    "code": "245"
}

Notice that the stock item will no longer be available with the previous code, after this request.

Products are added to categories by creating category links. Contrary to brands, a product can have several categories.

Category links are created by sending a POST request to the endpoint /api/v1/category-links or, alternatively, to the endpoint /api/v1/products/{productID}/category-links.

When making the request to /api/v1/category-links, you need to specify the product and the category, which will be linked. In this example we also sort the product to the category's 2nd position:

POST /api/v1/category-links
{
    "product_id": 6,
    "category_id": 5,
    "category_sort": 2
}

When creating a category link in the endpoint /api/v1/products/{productID}/category-links, you only need to specify the category, to which you add the product:

POST /api/v1/products/{productID}/category-links
{
    "category_id": 5,
    "category_sort": 2
}

Both of these requests will return a 200 OK response upon success.

If you need to remove a product from a category, send a DELETE request to the endpoint /api/v1/products/{productID}/category-links/{categoryId}.

You can add translated content to products, variations, and categories through the MyCashflow API. You can also include the translations of any multilingual fields in GET responses.

When you are creating content – in this example products – you can include translated content in the POST body in the translations array:

POST /api/v1/products
{
    "product_code": "AE-12345-89",
    "supplier_code": "876567890",
    "price": 159.95,
    "purchase_price": 120,
    "vat_rate": 24,
    "weight": 0.8,
    "warranty": 12,
    "keywords": "mekot, juhlamekot, puuvilla, pellava",
    "available_from": "2014-08-28",
    "available_to": "2014-08-29",
    "brand_id": 3,
    "supplier_id": 5,
    "translations": [
        {
            "language": "fi",
            "name": ""Leveäolkaiminen juhlamekko, vihreä",
            "description": "<p>Näyttävä ja tyylikäs iltajuhlien timantti! Valmistettu kestävästä puuvillan ja pellavan sekoituksesta. Ajaton ja klassinen muotoilu. Leveät olkaimet tekevät mekosta myös mukavan yllä. Värinä keväinen kirkas vihreä.</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>",
        },
        {
            "language": "en",
            "name": "Wide strap evening dress, green",
            "description": "<p>Näyttävä ja tyylikäs iltajuhlien timantti! Valmistettu kestävästä puuvillan ja pellavan sekoituksesta. Ajaton ja klassinen muotoilu. Leveät olkaimet tekevät mekosta myös mukavan yllä. Värinä keväinen kirkas vihreä.</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>",
        }
    ]
}

Notice that when you are adding translated content in a POST / PATCH request, you only need to include the translated fields inside of the translations array.

If you need to modify translated content, you can do so with a PATCH request. In this example we only modify the content in one language. Any other translatations of the same fields will not be affected:

PATCH /api/v1/products/{productID}
{
    "translations": [
        {
            "language": "en",
            "name": "Apple 80 GB iPod Video",
            "information": "* Black iPod with 80 GB hard drive for songs, podcasts, videos, games, and more\r\n* Large, 2.5-inch, 320 x 240 pixel color display screen is 60 percent brighter\r\n* Holds up to 20,000 songs, thousands of photos, and hours of video\r\n* Search function lets you type name of song with Click Wheel for instant results\r\n* Measures 2.4 x 4.1 x 0.55 inches (W x H x D); 1-year limited warranty",
        }
    ]
}

By using the GET parameter expand=translations, you can include translations in GET requests – both when fetching lists and individual objects:

GET /api/v1/products/{productID}?expand=translations
{
    "data": {
        "id": 2,
        "created_at": "2007-04-25T11:35:24+03:00",
        "updated_at": "2013-03-22T10:41:20+02:00",
        "product_code": "",
        "supplier_code": "",
        "name": "Apple 80 GB iPod Video",
        "description": "",
        "information": "* Black iPod with 80 GB hard drive for songs, podcasts, videos, games, and more\r\n* Large, 2.5-inch, 320 x 240 pixel color display screen is 60 percent brighter\r\n* Holds up to 20,000 songs, thousands of photos, and hours of video\r\n* Search function lets you type name of song with Click Wheel for instant results\r\n* Measures 2.4 x 4.1 x 0.55 inches (W x H x D); 1-year limited warranty",
        "keywords": "",
        "price": 332.66,
        "purchase_price": 0,
        "vat_rate": 24,
        "weight": 0.2,
        "warranty": 0,
        "brand_id": 13,
        "supplier_id": 0,
        "available_from": null,
        "available_to": null,
        "barcode": null,
        "translations": [
            {
                "language": "fi",
                "name": "Apple 80 GB iPod Video",
                "description": "",
                "information": "* Black iPod with 80 GB hard drive for songs, podcasts, videos, games, and more\r\n* Large, 2.5-inch, 320 x 240 pixel color display screen is 60 percent brighter\r\n* Holds up to 20,000 songs, thousands of photos, and hours of video\r\n* Search function lets you type name of song with Click Wheel for instant results\r\n* Measures 2.4 x 4.1 x 0.55 inches (W x H x D); 1-year limited warranty"
            },
            {
                "language": "jp",
                "name": "",
                "description": "",
                "information": ""
            },
            {
                "language": "en",
                "name": "",
                "description": "",
                "information": ""
            }
        ]
    }
}

You can use the MyCashflow API to control the visibility of products and categories in the store's versions.

By default, products – and other resources – created through the API are hidden, so they need to be made visible with a separate PATCH request.

Below is an example of making a product visible in one of the store's versions:

PATCH /api/v1/products/{productId}/visibilities
{
    "version_id": 5,
    "is_visible": true
}

If you need to hide a product or category in a version, simply reverse the value of the is_visible key to false:

PATCH /api/v1/products/{productId}/visibilities
{
    "version_id": 5,
    "is_visible": false
}

You can use the MyCashflow API to add images to the store's file system, and to attach images to products.

Images are added to the store's file system by sending a POST request to the endpoint /api/v1/images.

There are 3 alternative ways of adding an image to the store's file system:

  • By providing the file path a locally stored image
  • By providing the URL of a remotely stored image
  • By providing the image in a base64 encoded format as part of the request body

Below is an example of sending an image from your own computer to the store's file system:

POST /api/v1/images
{
  "filename":"/path/to/image.png"
}

The following request would fetch an image from a remote source, and send it to the store:

POST /api/v1/images
{
  "url":"http://www.domain.fi/image.png"
}

And finally, the following request would send an image in base64 encoded format to the store. The image will be automatically decoded and placed in the store's file system:

POST /api/v1/images
{
  "image":
      {
         "filename":"image.png",
         "data":"[base64 encoded file contents]"
      }
}

Images are automatically assigned a numeric ID, which you can find by fetching a list of the store's images with GET /api/v1/images.

You can use either the image ID or the image filename to attach images to products. Below is an example of attaching an image based on its ID:

POST /api/v1//products/{productId}/image-links
{
  "product_id": 5,
  "image_id": "1",
  "sort": 1,
  "caption": "Kuva tuotteesta"
}

In this request we also sort the image to the top of the product's image list and provide the image with a caption.

You can fetch all the images of a single product with a GET /api/v1/products/{productId}/image-links request.

You can also deattach an image from a product with a DELETE request. When you do this, you need to specify either the filename or the ID of the image as part of the request URL:

DELETE /api/v1/products/{productId}/image-links/filename={fileName}
DELETE /api/v1/products/{productId}/image-links/image_id={imageId}