Sharespine Developer Portal

Products

Create a simple product

A product can be quite complex and contain a lot of information. This example shows the minimum information required to be able to handle the inventory.

Below is the minimum information that is needed:

remoteId
Must be unique. This could be the internal id from the connected system. Make sure that to save the relation between remoteId and localId in the connected system. localId is the unique identifier within the Integration Platform.
vatRatePercent
Is mandatory and must be provided.
stock
The available stock.
stockType
An enum see the API reference for available options.
sku
A unique SKU for the product.

Example on creating simple product

Request

$ curl \
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/product \
    -XPOST \
    -d \
    '{
        "remoteId": "x",
        "vatRatePercent": "25",
        "stock": "10",
        "stockType": "stocked",
        "sku": "z"
    }'
Note

Save the localId from the response, it will be needed in subsequent requests to interact with the product.

Response

Full response omitted for brevity.

{
    "localId": "0006463d034d595774bf76d0311a21be",
    "remoteId": "x",
    ...
}

Create a product with attributes

This section will explain how a product with variants can be added to the Integration Platform by using the API. This article will use an example product with attributes. The product is a T-shirt that have the sizes XL, L, M, S and XS. The T-shirt also have the colors blue, white and black. In this example we will group the individual products into a variant group (variant group) and use the attributes color and size.

The structure in the Integration Platform:

erDiagram Product ||--o{ VariantGroup : "refers to" Product ||--o{ Category : "refers to" Product ||--o{ AttributeValue : "contains" AttributeValue ||--|| Attribute : "refers to"

Example of the data:

Record type Data
Category Clothes
Product Variant Group T-shirt
Product T-shirt blue XL
T-shirt blue L
T-shirt blue M
T-shirt blue S
T-shirt white XL
T-shirt white L
T-shirt white M
T-shirt white S
T-shirt black XL
T-shirt black L
T-shirt black M
T-shirt black S
Attribute Size
Color

Create a variant group

The first step is to create a variant group for the T-shirt. Goto the API reference to read more about the endpoint /product/variantgroup. The variant group contains a general product description that can be used for all the products that belong to this variant group. Products in the variant group have their own unique product description.

The Integration Platform have support for adding a remoteId to most resources. The external system add its own unique id for the T-shirt in the field remoteId and can use that ID for future calls to the API.

The Integration Platform will always create a localId for each resource. It is recommended that you save this id since it will be used when using the API. Read more about localId and remoteId.

Note

The remoteId must be unique within the record type.

This example will create a variant group with the remoteId t-shirt-group which can be used later when referring to this new object.

Request

$ curl \
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/product/variantgroup \
    -XPOST \
    -d \
    '{
        "remoteId": "t-shirt-group",
        "title_lang": {
            "eng": "T-shirt"
        },
        "description_lang": {
            "eng": "Lorem ipsum dolor ..."
        }
    }'

Create attributes

In the example we will have two attributes, color and size. Start by adding the attributes to the Integration Platform unless they already exists. A product can be created in one call if the attribute and variant group already exists. It is possible to add an attribute after the product is created but that will require multiple calls to the API. Use a remoteId or save the localId from the call below.

This example will create an attribute with the remoteId=color. In our case we would also need to create an attribute with the remoteId=size

Requests

$ curl \
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/attribute \
    -XPOST \
    -d \
    '{
        "remoteId": "color",
        "name_lang": {
            "eng": "Color"
        }
    }'

Request

$ curl \
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/attribute \
    -XPOST \
    -d \
    '{
        "remoteId": "size",
        "name_lang": {
            "eng": "Size"
        }
    }'

Create a category

A product can belong to one or many categories. A category is a way to group a set of products or variant groups. Save the localId if you want to add the category directly when you create the product. It is also possible to add a product in a category by using the remoteId when using the endpoint POST /product/by-remote-id/category.

Request

$ curl \
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/product/category \
    -XPOST \
    -d \
    '{
        "remoteId": "clothes",
        "title_lang": {
            "eng": "Clothes"
        },
        "description_lang": {
            "eng": "Lorem ipsum dolor ..."
        }
    }'

Create the products

The variant group, attribute and category was created in previous steps and now it is time to create each product. In this case there will be one product for every combination e.g T-shirt black L, T-shirt blue M and so on.

Goto the API reference to read more about the endpoint /product/.

This example will create a product with SKU=1000. We can create the product and connect the other object since the attribute, category and the variant group was created before the product. There are also endpoints to add these relations in a later step if needed.

Note

There is a title but no description in this example. This call will be needed for every unique product. Also note that vatRatePercent is mandatory.

Request

$ curl \
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/product \
    -XPOST \
    -d \
    '{
        "remoteId": "1000",
        "sku": "1000",
        "title_lang": {
            "eng": "T-shirt black L"
        },
        "vatRatePercent": "25",
        "productCategories": [
            {
                "localId": "3fb2568eb7e165e34dd311af5550002b"
            }
        ],
        "productVariantGroups": [
            {
                "remoteId": "t-shirt-group"
            }
        ],
        "attributes": [
            {
                "remoteId": "color",
                "values": [
                    {
                        "value_lang": {
                            "eng": "black"
                        }
                    }
                ]
            },
            {
                "remoteId": "size",
                "values": [
                    {
                        "value_lang": {
                            "eng": "L"
                        }
                    }
                ]
            }
        ]
    }'

Fetch products

Get the products from the API if the products already exists in the Integration Platform. You will need to get the products from the API to get the unique id in the Integration Platform. Make sure to save the related values of SKU and localId (or remoteId and localId). The remoteId is related to the API Connector and is null if the product was imported from another system. Read more about remoteId at Local and remote ID’s.

Request

$ curl \
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/product?modifiedAtOrAfter=2020-09-24T17:23:01Z

Response

Full response omitted for brevity.

[
    {
        "href": "/api/product/0006463d034d595774bf76d0311a21be",
        "localId": "0006463d034d595774bf76d0311a21be",
        "remoteId": "x",
        "sku": "y",
        ...
    }
]
Note

All products will be returned if modifiedAtOrAfter is excluded.

Update price

Read Price list before continuing this tutorial.

Price list

The Integration Platform uses Price list’s to structure the price of a product. A product can have prices for multiple pricelist e.g Pricelist default, Campaign pricelist A, Pricelist EUR and so on.

Note

All product prices are excluding Tax.

Request

$ curl \
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/product/pricelist \
    -XPOST \
    -d \
    '{
        "name": "My price list",
        "currency": "SEK"
     }'

The call will only create the price list which will later be referred to from the product.

Price

The price will be saved directly to the product with a reference to the selected price list. See API reference product price.

Request

$ curl \
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/product/{localId}/price \
    -XPOST \
    -d \
    '{
        "pricelist": {
            "localId": "3fb2568eb7e165e34dd311af5550002b",
        },
        "qtyPrices": [
            {
                "purchaseQty": "1.0",
                "originalPriceExclVat": {
                    "currency": "SEK",
                    "amount": "10.00"
                }
            },
            {
                "purchaseQty": "5.0",
                "originalPriceExclVat": {
                    "currency": "SEK",
                    "amount": "8.00"
                }
            }
        ]
    }'
Note

The price will be updated if a price already exist for the selected price list. qtyPrices can have multiple levels to support a price discount when the purchased quantity is above a defined threshold.

Product data

The product in the Integration Platform will contain information about all prices.

This means that:

  • It is possible to get all prices related to a product by fetching the product.
  • It is not possible to get all prices related to a price list with a single API-call.

The product will contain a price section like the one below.

Please read the section API reference get product for more detailed information.

Response

Full response omitted for brevity.

{
    ...
    "prices": [
        {
            "pricelist": {
                "....": "...."
            },
            "qtyPrices": [
                {
                    "purchaseQty": "1.0",
                    "originalPriceExclVat": {
                        "currency": "SEK",
                        "amount": "1.0",
                        "decimals": 0
                    }
                }
            ]
        },
        {
            "pricelist": {
                "....": "...."
            },
            "qtyPrices": [
                {
                    "purchaseQty": "1.0",
                    "originalPriceExclVat": {
                        "currency": "SEK",
                        "amount": "2.0",
                        "decimals": 0
                    }
                }
            ]
        }
    ],
    ...
}

Upload a product picture

The Integration Platform supports pictures connected to a product or a variant group. This article explains by examples how a picture is uploaded to the Integration Platform and connected to the right resource.

Note

Read about the record type File before continuing this section.

Step 1: Create a file

The first step is to create a file in the Integration Platform. The file can have a name, mimeType and publicAccess settings, see API reference for more information.

Note

The content is added in the next step.

Request

$ curl \
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/file \
    -XPOST \
    -d \
    '{
        "name": "myfile",
        "mimeType": "image/jpeg",
        "publicAccess": true
     }'

Response

Full response omitted for brevity.

{
    "name": "myfile",
    "mimeType": "image/jpeg",
    "publicAccess": true,
    "localId": "3fb2568eb7e165e34dd311af5550002b",
    ...
 }

Step 2: Upload the file content

The file was created in the previous step, and now it is time to add the file content.

Request

  • PUT /file/{localId}/data (example: /file/3fb2568eb7e165e34dd311af5550002b/data)
  • Content-Type: application/octet-stream
  • see API reference /file/{localId}/data for more information

Step 3a: Connect as product picture

Connect the file to a product as a product picture. The picture will be connected to a specific product and SKU.

Choose one of the options below:

  • POST /product/{localId}/picture- localId in the url relates to the product and NOT the file)
  • POST /product/by-remote-id/picture?remoteId={remoteId} - remoteId in the url relates to the product and NOT the file.

The fileId in the body is the localId for the file. See response from the step “Create a file” above.

Request

[
    {
        "fileId": "3fb2568eb7e165e34dd311af5550002b"
    }
 ]

Step 3b: Connect as variant group picture

The variant group picture is not related to a specific product (or SKU). A variant group can contain 0 to X number of products which each have their own SKU and potentially their own pictures.

Choose one of the options below:

  • POST /product/variantgroup/{localId}/picture - localId in the url relates to the variant group and NOT the file)
  • POST /product/variantgroup/by-remote-id/picture?remoteId={remoteId} - remoteId in the url relates to the variant group and NOT the file.

The fileId in the body is the localId for the file. See response from the step Create a file above.

Request

[
    {
        "fileId": "3fb2568eb7e165e34dd311af5550002b"
    }
 ]

Update inventory

The integration platform needs products to be able to handle the inventory. The products can either be added by the API or it can be imported into the Integration Platform from any of our connectors.

Find a reference localId or remoteId to the product in the Integration Platform:

flowchart TD S[Start] --> lr[localId/remoteId is known?] lr -->|Yes| ui[Update inventory]; lr -->|No| pe{Product exists?}; pe -->|Yes| fp[Fetch product]; fp --> ui; ui --> E[End]; pe ---->|No| cp[Create product]; cp --> ui;

  • Fetch products: get all multiple products by using the API see section Fetch products OR find a specific product by SKU see the endpoint GET /product/by-sku in the API reference.
  • Create a new product: a product must exist in the Integration Platform. See section Create a product which explains the minimal information necessary.
Note

Make sure to note the localId of the product that you want to update.

Update using localId

Make a PUT-request to update the product’s stock value. localId is the unique identifier within the Integration Platform.

Request

$ curl \
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/product/{localId} \
    -XPUT \
    -d \
    '{
        "stock": "10"
     }'

Update using remoteId

The Integration Platform allows you to add your own id to a product which is called remoteId and must be a unique id among all products. The remoteId is designed to contain the external systems unique identifier e.g a database key or a unique SKU.

The remoteId can be used instead of the localId when calling the API but note that it is only possible to use a remoteId that was set by the same API-connector.

Read more about localId and remoteId.

Make a PUT-request to update the product’s stock value in the Integration Platform.

Request

$ curl \
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/product/by-remote-id?remoteId={remoteId} \
    -XPUT \
    -d \
    '{
        "stock": "10"
     }'
Note

Where remoteId is the product remoteId for this specific API-Connector.

Related information

Next: Orders