Productsup Platform and Stream API documentation

Productsup Platform and Stream APIs

Welcome to the Productsup API doc site.

At the moment, the following APIs are available for your use:

Platform API - Management and product data API
Stream API - High-performance product upload API

Some APIs overlap in specific areas of functionalities. See the following:

Management API - These functionalities are all part of the Platform API:
- Management of projects and sites
- Get information about previous imports
- Check errors per site run
- Get info about channels and their history
- Check the status of a site
- Trigger a run for a site
Content API:
- Product Data (write)
  - Legacy functionality offered by the Platform API
  - A high-performance solution provided by the Stream API
- Product Data (read)
  - Access to data via Platform API

Platform API (v2)

Introduction

The Productsup REST API provides programmatic access to read and write Productsup data. Create sites, upload product data, enable export channels, and more.

For PHP users we provide an API Client, see the Readme.md for more information. We accept non-breaking changes from client pull requests.

Note

The latest PHP Client version is 2.4.0.

Authentication

All requests to the Productsup API require valid authorization. You can build the authentication token with the client ID and client secret issued by Productsup.

The token has the following format: client_id:client_secret, it needs to be sent as a value for the X-Auth-Token HTTP header.

The client_id and client_secret are account specific, so you can only access projects, sites, and other resources which lie under your account.

Example 1. Make sure to replace 1234 and simsalabim with the client ID and secret you got provided.

# With shell, you can just pass the correct header with each request
curl -H "X-Auth-Token: 1234:simsalabim" https://platform-api.productsup.io/

<?php
$Client = new Productsup\Client();
$Client->id = 1234;
$Client->secret = 'simsalabim';

Version

The API uses a URL-based versioning mechanism. You can switch to the latest version by replacing v1 in the examples by v2.

Note

The current stable version is version 2. Always use the latest version of the API, unless otherwise instructed.

If you are using the latest version of the Platform API Client, then you are automatically on the latest stable version.

Cursor pagination

The API uses a cursor pagination mechanism. It supports three parameters for the pagination.

HTTP request

Only GET requests that return a list of entities

Example 2. HTTP request

GET https://platform-api.productsup.io/platform/v2/sites/<siteId>/streams?limit=number1&previous=number2&cursor=number3

Cursor parameters

Name	Type	Default	Description
limit	integer	50	Maximum number of entities per page
cursor	integer	0	Using an identifier to return entities that ids come after the cursor parameter (numeric value)
previous	integer	0	Return the previous entity id if not return 0 (numeric value)

Response fields

Field	Type	Description
meta	array	Indicates cursor details. See Cursor fields.

Cursor fields

Field	Type	Description
current	integer	The current cursor ID
prev	integer	The previous entity ID
next	integer	The next entity page starter ID
count	integer	Number of returned entities

# result: 
{
    "success": true,
    "Entities": [
        {

        }
    ],
    "meta": {
        "cursor": {
            "current": 0,
            "prev": 0,
            "next": 1,
            "count": 1
        }
    }
}

Projects

Projects are used to group your sites. See Sites.

Get

Lists all or one project from your account.

For both requests, the response looks identical. Except when requesting a specific project it will just list the one project.

Example 3. Get all projects for your account

GET https://platform-api.productsup.io/platform/v2/projects

Example 4. Get a project by its identifier

GET https://platform-api.productsup.io/platform/v2/projects/<projectId>

URL parameters

Field	Type	Description
projectId	integer	Project to list

Response fields

Field	Type	Description
success	boolean	Indicates request status
Projects	array	List of projects. See Project fields.

Project fields

Field	Type	Description
id	integer	Internal ID
name	string	Name of the project
created_at	date	Date of creation
links	array	List of relevant resources. See Link fields and values.

Links, fields, and values

Name	Description
self	Link to the project detail endpoint. See Get a project by its identifier.
sites	Link to a list of sites belonging to the project. See Get all sites for a specific project.

Example 5. Requesting a list of all your projects

curl https://platform-api.productsup.io/platform/v2/projects

{
    "success": true,
    "Projects": [
        {
            "id": "1",
            "name": "default project",
            "created_at": "2013-03-21 12:47:57",
            "links": [...]
        },
        ...
    ]
}

<?php
$projectService = new Productsup\Service\Projects($client);
$projects = $projectService->get();
print_r($projects);

/*
result will look like this:
Array
(
    [0] => Productsup\Platform\Project Object
        (
            [id] => 1
            [name] => default project
            [created_at] => 2013-03-21 12:47:57
        )
    ...
)

Example 6. Requesting a single project

curl https://platform-api.productsup.io/platform/v2/projects/1

{
    "success": true,
    "Projects": [{
        "id": "1",
        "name": "default project",
        "created_at": "2013-03-21 12:47:57",
        "links": [...]
    }]
}

<?php                                      
$rojectId = 1;
$projectService = new Productsup\Service\Projects($client);
$project = $projectService->get($projectId);
print_r($project);

/*
result will look like this:
Array
(
    [0] => Productsup\Platform\Project Object
        (
            [id] => 1
            [name] => default project
            [created_at] => 2013-03-21 12:47:57
        )
)

Create

To create a new project, you can use a POST request (or the insert method).

Example 7. Create project

POST https://platform-api.productsup.io/platform/v2/projects

HTTP headers

Name	Value
Content-Type	application/json

The data to be inserted has to be provided as a JSON-Object.

Request body fields

Field	Type	Description
name	string	Project name

The id and created_at must be empty, otherwise, the values get overwritten, or the request may result in an error.

Response fields

Field	Type	Description
success	boolean	Indicates request status
Projects	array	Details of the created project. See Project fields.

Project fields

Field	Type	Description
id	integer	Internal ID
name	string	Name of the project
created_at	date	Date of creation
links	array	List of relevant resources. See Link fields and values.

Links, fields, and values

Name	Description
self	Link to the project detail endpoint. See Get a project by its identifier.
sites	Link to a list of sites belonging to the project. See Get all sites for a specific project.

curl -d '{"name":"test project"}' \
    https://platform-api.productsup.io/platform/v2/projects

# result:
{
    "success": true,
    "Projects": [{
        "id": 125,
        "name": "test project",
        "created_at": "2015-07-30 12:54:52",
        "links": [...]
    }]
}

<?php
$projectService = new Productsup\Service\Projects($Client);
$project = new Productsup\Platform\Project();
$project->name = "test project";
$projectService->insert($project);
print_r($result); 
/**
result:
Productsup\Platform\Project Object
        (
            [id] => 125
            [name] => test project
            [created_at] => 2015-07-30 12:54:52
        )
*/

Edit

To edit an existing project, you can use a PUT request.

Example 8. Update project

PUT https://platform-api.productsup.io/platform/v2/projects/<projectId>

URL parameters

Field	Type	Description
projectId	integer	Existing project being edited

HTTP headers

Name	Value
Content-Type	application/json

The data to be inserted has to be provided as a JSON-Object.

Request body fields

Field	Type	Description
id	integer	Id of the existing project
name	string	Project name

Response fields

Field	Type	Description
success	boolean	Indicates request status
Projects	array	Details of the changed project. See Project fields.

Project fields

Field	Type	Description
id	integer	Internal ID
name	string	Name of the project
created_at	date	Date of creation
links	array	List of relevant resources. See Link fields and values.

Links, fields, and values

Name	Description
self	Link to the project detail endpoint. See Get a project by its identifier.
sites	Link to a list of sites belonging to the project. See Get all sites for a specific project.

curl -d '{"name":"example project"}' \
    https://platform-api.productsup.io/platform/v2/projects/125


# result:
{
    "success": true,
    "Projects": [{
        "id": 125,
        "name": "example project",
        "created_at": "2015-07-30 12:54:52",
        "links": [...]
    }]
}

Delete

Example 9. Delete project

DELETE https://platform-api.productsup.io/platform/v2/projects/<projectId>

URL parameters

Field	Type	Description
projectId	integer	Project to delete

Request body fields

Field	Type	Description
success	boolean	Indicates the success of the action

curl -X DELETE https://platform-api.productsup.io/platform/v2/projects/125

# response:
{"success":true}

<?php
$projectService = new Productsup\Service\Projects($client);
$result = $projectService->delete(125); // id fetched from API
// result is true, if the delete was successful

Sites

Sites are the smallest entity under projects, have one data source, and may have several exports or channels.

Get

To list all sites of your account or only certain sites, you can use GET.

Example 10. Get all sites for your account

GET https://platform-api.productsup.io/platform/v2/sites

Example 11. Get all sites for a specific project

GET https://platform-api.productsup.io/platform/v2/projects/<projectId>/sites

URL parameters

Field	Type	Description
projectId	integer	Project to list sites for

Get a site by its tag

GET https://platform-api.productsup.io/platform/v2/sites/<tagName>:<tagValue>

URL parameters

Field	Type	Description
tagName	string	Name of the tag for the site
tagValue	string	Value of the tag for the site

More information about references, also known as site tags. See References or site tags.

Get a site by its identifier

GET https://platform-api.productsup.io/platform/v2/sites/<siteId>

URL parameters

Field	Type	Description
siteId	integer	Site to list

Response fields

Field	Type	Description
success	boolean	Indicates request status
Sites	array	List of sites. See Site fields.

Site fields

Field	Type	Description
id	integer	Site identifier
title	string	Name of the site
status	string	List of valid statuses. See Link fields and values.
project_id	integer	Identifier of the project this site belongs to
import_schedule	string	Import schedule
id_column	string	Name of the column that is considered an identifier
processing_status	string	Status of the site's latest run job (Running/Done)
created_at	date	Date of creation
links	array	List of relevant resources. See Link fields and values.

Links, fields, and values

Name	Description
self	Link to current site detail. See Get a site by its identifier.
tags	Link to a list of tags belonging to the site
project	Link to project. See Get a project by its identifier.

Site status information

Value for status	Description
active	The site is fully operational. You can push data via the API and the site imports and exports.
paused_upload	The site can receive data via the API and import the data. However, it does not export data.
disabled	The site blocks any data sent via the API. You cannot send imports or exports.

Example 12. Requesting a list of all your sites

curl https://platform-api.productsup.io/platform/v2/sites

<?php
// our php client builds the urls for you, but you have to set the infos to the classes:

$siteService = new \Productsup\Service\Sites($client);

// sending the actual request
$list = $siteService->get();
print_r($list);

/*
result will look like this:
Array
(
    [0] => Productsup\Platform\Site Object
        (
            [id] => 123
            [title] => site 1
            [created_at] => 2015-01-01 11:22:33
            [project_id] => 321
            [links:protected] => Array(...)
            [reference:protected] =>
        )
    ...
*/

Example 13. Requesting a list of all your sites within one project

curl https://platform-api.productsup.io/platform/v2/projects/321/sites

Example 14. Requesting sites by ID or tag

curl https://platform-api.productsup.io/platform/v2/sites/tagname:tagValue

curl https://platform-api.productsup.io/platform/v2/sites/123

// or requesting it by reference/a tag:
$reference = new \Productsup\Platform\Site\Reference();
$reference->setKey('tagname');
$reference->setValue('123abc');
$list = $siteService->setReference($reference);

// or requesting the site by its id:
$list = $siteService->get(123);

/*
result will look like this:
Array
(
    [0] => Productsup\Platform\Site Object
        (
            [id] => 123
            [title] => site 1
            [created_at] => 2015-01-01 11:22:33
            [project_id] => 321
            [links:protected] => Array(...)
            [reference:protected] =>
        )
    ...
*/

# response:
{
    "success": true,
    "Sites": [
        {
            "id": "123",
            "title": "site 1",
            "created_at": "2015-01-01 11:22:33",
            "project_id": "321",
            "links": [...]
        },
        ...
    ]
}

Create

To create a new site, you can use a POST request, or the insert method.

Example 15. Create site

POST https://platform-api.productsup.io/platform/v2/sites

POST https://platform-api.productsup.io/platform/v2/projects/<projectId>/sites

URL parameters

Field	Type	Description
projectId	integer	Project under which to add the site. Required unless set in the request body.

HTTP headers

Name	Value
Content-Type	application/json

The data for insertion is provided as a JSON-Object.

Request body fields

Field	Type	Description
title	string	Site name
reference	string	Textual site reference, consisting of `tagName` and `tagValue`. This must be unique per site.
project_id	integer	Project under which to add the site. Required unless provided in URL.
id_column	string	ID column which is being used as an identifier when importing data to the platform.
status	string	List of valid statuses. See Site status information.

Leave id and created_at empty, otherwise, the values get overwritten, or the request may result in an error.

Field id_column is optional and only needed if the site identifier is not id. By default, not passing an id_column sets the identifier to id. If an empty value "" is given for the id_column then the identifier column is not set.

References or site tags

A reference allows you to use a textual representation of your own choice for a site. This way you don't need to store the site ID itself.

A reference, also called a site tag, consists of a tagName and tagValue. The reference format appears as follows: tagName:tagValue.

Note

The reference for a site must be unique, as you can only use it once in your account.

Response fields

Field	Type	Description
success	boolean	Indicates request status
Sites	array	List of sites. See Site fields.

Site fields

Field	Type	Description
id	integer	Site identifier
title	string	Name of the site
status	string	List of valid statuses. See Links, fields, and values.
project_id	integer	Identifier of the project this site belongs to
import_schedule	string	Import schedule
id_column	string	Name of the column that is considered an identifier
processing_status	string	Status of the site's latest run job (Running/Done)
created_at	date	Date of creation
links	array	List of relevant resources. See Links, fields, and values.

Links, fields, and values

Name	Description
self	Link to current site detail. See Get a site by its identifier.
tags	Link to a list of tags belonging to the site
project	Link to project. See Get a project by its identifier.

Example 16. Create site

curl -d '{"title":"example site","reference":"myReferenceKey:myReference1234", "id_column": "uniqueIdentifier"}' \
    https://platform-api.productsup.io/platform/v2/projects/321/sites

# result:
{
    "success": true,
    "Sites": [{
        "id": 125,
        "title": "example site",
        "created_at": "2015-07-30 12:54:52",
        "project_id": 321,
        "links": [...]
    }]
}

<?php
$SitesService = new \Productsup\Service\Sites($Client);
$project = new \Productsup\Platform\Project();
$project->id = 321;
$SitesService->setProject($project);
$siteObject = new \Productsup\Platform\Site();
$siteObject->title = 'new example site';
$siteObject->id_column = 'uniqueIndetifier';
/* optional
$reference = new \Productsup\Platform\Site\Reference();
$reference->setKey('myReferenceKey');
$reference->setValue('myReference1234');
$siteObject->addReference($reference);
*/

$result = $SitesService->insert($siteObject);
print_r($result);
/**
result:
Productsup\Platform\Site Object
(
    [id] => 125
    [title] => new example site
    [created_at] => 2015-07-30 12:54:52
    [project_id] => 321
)

*/

Edit

To edit an existing site, you can use a PUT request as follows:

Example 17. Update site

PUT https://platform-api.productsup.io/platform/v2/sites/<siteId>

PUT https://platform-api.productsup.io/platform/v2/projects/<projectId>/sites/<siteId>

URL parameters

Field	Type	Description
projectId	integer	The project where to edit the site.
siteId	integer	The existing site in edit mode.

HTTP headers

Name	Value
Content-Type	application/json

The data for insertion is provided as a JSON-Object.

Request body fields

Field	Type	Description
id	integer	Existing site expecting edits.
project_id	integer	Project under which to edit the site.
title	string	Site name
id_column	string	ID column which is being used as an identifier when importing data to the platform.
status	string	List of valid statuses. See Site status information.
import_schedule	string	A cron entry that sets the scheduling for data import.

The field id_column is optional and only needed if the site identifier needs to be set. If an empty value "" is given for the id_column, the identifier column is not set.

The Cron entries format consists of a timezone and schedule format. All PHP timezones are supported. Use a new line as a separator between the timezone and each schedule. For example:

TZ=Europe/BerlinH
2,6,19,22 * * 2,4,6
H * * * *
1 3,8,21 */2 * *

For the minute entry, accept the value H, which indicates a random minute is used. This is preferred since it prevents many jobs from starting at the same time. You can override it if required.

Response fields

Field	Type	Description
success	boolean	Indicates request status
Sites	array	List of sites. See Site fields.

Site fields

Field	Type	Description
id	integer	Site identifier
title	string	Name of the site
status	string	List of valid statuses. See Links, fields, and values.
project_id	integer	Identifier of the project this site belongs to
import_schedule	string	Import schedule
id_column	string	Name of the column that is considered an identifier
processing_status	string	Status of the site's latest run job (Running/Done)
created_at	date	Date of creation
links	array	List of relevant resources. See Links, fields, and values.

Links, fields, and values

Name	Description
self	Link to current site detail. See Get a site by its identifier.
tags	Link to a list of tags belonging to the site
project	Link to project. See Get a project by its identifier.

Example 18. Update site

curl -d '{"id": "1", "project_id": "1", "title":"My test site", "import_schedule": "TZ=Europe/Berlin\nH 2,6,19,22 * * 2,4,6"}' \
    https://platform-api.productsup.io/platform/v2/projects/1/sites/1

# result:
{
    "success": true,
    "Sites": [{
        "id": "1",
        "title": "My test site",
        "created_at": "2015-07-30 12:54:52",
        "project_id": "1",
        "import_schedule": "TZ=Europe\/Berlin\nH 2,6,19,22 * * 2,4,6\nH * * * *",
        "links": [...]
    }]
}

Delete

Example 19. Delete site

DELETE https://platform-api.productsup.io/platform/v2/sites/<siteId>

URL parameters

Field	Type	Description
siteId	integer	Site to delete

Response body fields

Field	Type	Description
success	boolean	Indicates a successful action

Example 20. Delete site

curl -X DELETE https://platform-api.productsup.io/platform/v2/sites/125

# response:
{"success":true}

<?php
$SitesService = new Productsup\Service\Sites($Client);
$result = $siteService->delete(125); // id fetched from API
// result is true, if the delete was successful

Site errors

With site errors, you can see the last errors or add new custom errors for a site.

Get

To list errors for one site, you can use get. See Sites for how to identify sites.

Example 21. HTTP Request

GET https://platform-api.productsup.io/platform/v2/sites/<siteId>/errors

GET https://platform-api.productsup.io/platform/v2/sites/<siteid>/errors?pid=<pid>&limit=<limit>&offset=<offset>

URL parameters

Name	Type	Description
siteId	integer	Get errors for this site

Optional query parameters

Name	Example	Default	Description
pid	`abc456def`	(latest)	Process ID. By default, the latest process is shown.
limit	`10`	`50`	Maximum number of results
offset	`20`	`0`	Results begin at this position

Response fields

Field	Type	Description
success	boolean	Indicates request status
Errors	array	List of errors. See Error fields.

Error fields

Field	Type	Description
id	integer	Internal identifier
pid	string	Process identifier
error	integer	Error identifier
data	array	Additional information about the error
site_id	integer	Site identifier
message	string	End-user friendly error message
links	array	List of relevant resources. See Links, fields, and values.

Links, fields, and values

Name	Description
self	Link to the error endpoint. See Example 21, “HTTP Request”.

Example 22. Requesting all channels from a site

curl https://platform-api.productsup.io/platform/v2/sites/123/errors

<?php
$site = new \Productsup\Platform\Site();
$site->id = 123;

$errorService = new \Productsup\Service\Errors($client);
$errorService->setSite($site);

// optional params
$errorService->setParam('pid','abc456def');
$errorService->setParam('limit',1);
$errorService->setParam('offset',2);


$result = $errorService->get();

/*
result will look like this:
Array
(
    [0] => Productsup\Platform\Error Object
        (
            [id] => 123
            [pid] => abd456
            [error] => 10081
            [data] => 
            [links:protected] => ...
        )

    [1] => Productsup\Platform\Error Object
        (
            [id] => 124
            [pid] => 537df1d87c39c
            [error] => 10012
            [data] => {"FTP Host":"sftp:\/\/example.org","User":"sftpuser"}
            [links:protected] => ...
        )
...
*/

# response: 
{
    "success": true,
    "Errors": [
        {
            "id": "1802017",
            "pid": "537cb0659a7dc",
            "error": "10012",
            "data": "{"FTP Host":"sftp:\/\/example.org","User":"sftpuser"}",
            "site_id": "123",
            "links": [{...}]
        },
        ....
    ]
}

Import history

Endpoint import history lets you query for meta-information regarding the last imports.

Get

Lists the information regarding your last imports.

Note

Import history is always for one site. For more information about querying sites, see Sites.

Example 23. HTTP Request

GET https://platform-api.productsup.io/platform/v2/sites/<siteId>/importhistory

URL parameters

Field	Type	Description
siteId	integer	List import history for the site

Response fields

Field	Type	Description
success	boolean	Indicates request status
Sites	array	List of imports. See Site fields.

Site fields

Field	Type	Description
id	integer	Internal identifier
site_id	integer	Site identifier
import_time	date	Date of the import
product_count	integer	The total amount of imported products
links	array	List of relevant resources. See Links, fields, and values.

Links, fields, and values

Name	Description
site	Link to site. See Get a site by its identifier.

Note

Creating and deleting the import history is not possible.

Example 24. Requesting one site by its ID

curl https://platform-api.productsup.io/platform/v2/sites/123/importhistory

<?php
$reference = new \Productsup\Platform\Site\Reference();
$reference->setKey(\Productsup\Platform\Site\Reference::REFERENCE_SITE);
$reference->setValue(123); // site id
$importHistory = new \Productsup\Service\ImportHistory($client);
$importHistory->setReference($reference);
$history = $importHistory->get();
print_r($history);

/*
result will look like this:
Array
(
    [0] => Productsup\Platform\ImportHistory Object
        (
            [id] => 1111111111
            [site_id] => 123
            [import_time] => 2015-07-15 15:02:11
            [product_count] => 18370
            [links:protected] => Array
                (
                    [site] => http://api.productsup.io/platform/v2/sites/123
                )

            [reference:protected] => 
        )

)
*/

# response:
{
    "success": true,
    "Importhistory": [
        {
            "id": "11111111",
            "site_id": 1234,
            "import_time": "2015-01-01 11:22:33",
            "product_count": "18370",
            "links": [...]
        },
        ...
    ]
}

Channels

Channels are the data targets, for example, Google Shopping, Amazon, etc.

Get

To list all channels in your account or specific sites, you can use get.

Example 25. Get all channels for a site

GET https://platform-api.productsup.io/platform/v2/sites/<siteId>/channelsET https://platform-api.productsup.io/platform/v2/sites/<siteId>/importhistory

URL parameters

Field	Type	Description
siteId	integer	List channels for site

Example 29. Get a channel by its identifier

GET https://platform-api.productsup.io/platform/v2/sites/<siteId>/channels/<channelId>

URL parameters

Field	Type	Description
siteId	integer	The site where the channel exists
channelId	integer	Channel to get. Use the site channel relation ID

Response fields

Field	Type	Description
success	boolean	Indicates request status
Channels	array	List of channels. See Channel fields.

Channel fields

Field	Type	Description
id	integer	Site channel relation identifier
site_id	integer	Site identifier
channel_id	integer	Channel identifier
name	string	Name of the export you provided while creating the channel
export_name	string	Generic name of the export in the Productsup platform
links	array	List of relevant resources. See Links, fields, and values.

Links, fields, and values

Name	Description
self	Link to channel detail. See Example 29, “Get a channel by its identifier”.
site	Link to site. See Get a site by its identifier.

<?php
$reference = new \Productsup\Platform\Site\Reference();
$reference->setKey(\Productsup\Platform\Site\Reference::REFERENCE_SITE);
$reference->setValue(123); // site id
$channelService = new \Productsup\Service\Channels($client);
$channelService->setReference($reference);
$channels = $channelService->get();

/*
result will look like this:
Array
(
    [0] => Productsup\Platform\Channel Object
        (
            [id] => 321
            [site_id] => 123
            [name] => Criteo DE
            [export_name] => Criteo
            [history] => 
            [links:protected] => ...
        )

    [1] => Productsup\Platform\Channel Object
        (
            [id] => 543
            [site_id] => 123
            [name] => Zanox DE
            [export_name] => Zanox
            [history] => 
            [links:protected] => ...
        )
...
*/

Example 26. Requesting all channels of one site

curl https://platform-api.productsup.io/platform/v2/sites/123/channels

Example 27. Requesting a specific channel

curl https://platform-api.productsup.io/platform/v2/sites/123/channels/321

Example 28. Response

{
    "success": true,
    "Channels": [
        {
            "id": "321",
            "site_id": "123",
            "channel_id": "111",
            "name": "Criteo DE",
            "export_name": "Criteo",
            "links": [...]
        }, 
        {
            "id": "541",
            "site_id": "123",
            "channel_id": "222",
            "name": "Zanox DE",
            "export_name": "FZanox",
            "links": [...]
        }
    ]
}

Channel history

With the channel history, you can get information on the last channel exports.

Get

To list the history, you can use get.

Example 30. HTTP Request

GET https://platform-api.productsup.io/platform/v2/sites/<siteId>/channels/<channelId>/historyET https://platform-api.productsup.io/platform/v2/sites/<siteId>/importhistory

URL parameters

Field	Type	Description
siteId	integer	Site where the channel exists
channelId	integer	Channel to get; use site channel relation ID

Response fields

Field	Type	Description
success	boolean	Indicates request status
Channels	array	List of channels. See Channel fields.

Channel fields

Field	Type	Description
id	integer	Site channel relation identifier
site_id	integer	Referenced Site identifier
channel_id	integer	Channel identifier
name	string	Name of the export you provided while creating the channel
export_name	string	Generic name of the export in the Productsup platform
links	array	List of relevant resources. See Links, fields, and values.
history	array	List of channel history. See History fields.

Links, fields, and values

Name	Description
self	Link to channel detail. See Get a channel by its identifier.
site	Link to site. See Get a site by its identifier.

History fields

Field	Type	Description
id	integer	Internal identifier
site_id	integer	Referenced site identifier
site_channel_id	string	Internal ID for the combination of an export and site. See Channels and Sites for more information.
export_time	dateTime	Time when the process finished
export_start	dateTime	Time when the process started
product_count	integer	Number of exported products
pid	string	Internal identifier of the process
product_count_new	integer	Number of new products. Only for delta exports
product_count_modified	integer	Number of updated products. Only for delta exports
product_count_deleted	integer	Number of deleted products. Only for delta exports
product_count_unchanged	integer	Number of unchanged products. Only for delta exports
uploaded	integer	Indicator if the export was uploaded to its destination

Note

Creating and deleting channel history is not possible.

Example 31. Requesting a channel's history

curl https://platform-api.productsup.io/platform/v2/sites/123/channels/321/history

# response:
{
    "success": true,
    "Channels": [
        {
            "id": "321",
            "site_id": "123",
            "channel_id": "1",
            "name": "Google Merchant Center DE",
            "export_name": "Google Merchant Center",
            "links": [...],
            "history": [
                {
                    "id": "333",
                    "site_id": "123",
                    "site_channel_id": "444",
                    "export_time": "2015-09-30 10:18:56",
                    "export_start": "2015-09-30 10:18:54",
                    "product_count": "18697",
                    "product_count_now": "20904",
                    "product_count_previous": "0",
                    "process_status": "0",
                    "pid": "560b96899e334",
                    "product_count_new": "0",
                    "product_count_modified": "0",
                    "product_count_deleted": "0",
                    "product_count_unchanged": "0",
                    "uploaded": "0"
                },
                ...
            ]
        }
    ]
}

Product data (write)

Note

See Stream API for the latest solution targeted specifically to high-performance product data uploading.

Uploading

Uploading to the API works via batches. A batch is a collection of products, potentially delivered by multiple requests. The batch can, once all product data is delivered, be committed or discarded.

Example 32. HTTP Request

POST https://platform-api.productsup.io/platform/v2/sites/<siteIdentifier>/products/<batchId>/upload

URL parameters

Field	Type	Description
siteIdentifier	mixed	Either `siteId` or `siteTags`. See Site identifier values.
batchId	string (32 characters)	Any sequence of characters that indicates a unique batch. It should be exactly 32 characters long. One possibility is to generate a unique number and hash it with the md5 algorithm.

Site identifier values

Type	Data type	Description
siteId	integer	Using a site identifier (numeric value)
siteTags	string (format: `tagName:tagValue`)	A combination of a tag name and tag value for a site. See References or site tags.

HTTP headers

Name	Value
Content-Type	application/json

You must insert the data as a JSON-Object.

curl --header 'Content-Type: application/json' -d '[{
   "id": 123,
   "title": "test title",
   "price": 1.23
}, {
   "id": 124,
   "title": "next title",
   "price": 3.21,
   "shipping": "0.99"
}]'
https://platform-api.productsup.io/platform/v2/sites/Identifier:123/products/md5string32chars/upload

<?php
// our php client builds the urls for you, but you have to set the info in the classes:
$ProductService = new Productsup\Service\ProductData($Client);
$Reference = new Productsup\Platform\Site\Reference();

/**
 * You have to specify the site the products belong to.
 * This is done by references to the site.
 **/
// In case you have a productsup site id, you can pass it like this:
$Reference->setKey($Reference::REFERENCE_SITE);
$Reference->setValue(123); // Site ID

// In case you have a custom reference, you can use the follow logic
$Reference->setKey($siteTagName);
$Reference->setValue($siteTagValue);

// Assign the reference to the endpoint class
$ProductService->setReference($Reference);

// Actual creating of upload data
$ProductService->insert(array(
        'id' => 123,
        'price' => 1.23,
        'description' => 'test title',
    )
);

$ProductService->insert(array(
        'id' => 124,
        'price' => 3.21,
        'description' => 'next title',
        'shipping' => 0.99
    )
);

Product format

When uploading products, apply the following rules:

Columns can be named freely, but ideally, name them in lowercase and they should not contain spaces or special characters. Productsup's technology relies on SQLite database limits.
When columns are added:
- Existing data has an empty value for these columns.
When columns are not uploaded or removed:
- If any existing data has a value for that column, it remains and the new data has an empty value.
- If existing data doesn't have a value, that column is automatically removed.
The amount of products per upload request is limited to 10,000. It is recommended that you send multiple upload requests with the same batch ID if you reach this limit.
Note
The id key is mandatory. All other keys end up as columns.

Table 1. Example product data list

id	title	price	shipping	pup:isdeleted
123	my first product	1.23
123	my second product	3.21	0.99
124	my other product	5.99	-	1
126	another product of mine	0.50	-	-1

Unique identifier `id`

The id column is required and should contain a unique value to represent your product. If a duplicate value for the id is present, Productsup imports the last product with a duplicate value.

When sending updates or in case a product needs to be deleted, the correct id should be used.

Note

The id key value must be unique unless you want to specifically overwrite a product with different data.

Delete products

You can delete specific products by adding the column pup:isdeleted. Depending on the product's value, a trigger can perform a soft or hard delete. A soft delete marks the product as deleted, but it still shows up in the Dataview section of the Platform. When performing a hard delete, the product does not import and is not visible in the platform.

This applies to both full and delta uploads. Sending a full upload also overrides all data, so it's not needed to remove products beforehand. Additionally, it's also possible to clear your API data by sending a dummy product, marking it for a hard delete, and doing a full commit.

Value for `pup:isdeleted`	Description
1	Soft delete, the product is present in the platform but marked
-1	Hard delete, the product is not present in the platform
0	No delete, the product is present in the platform

Response status codes

Code	Message	Details
200	N/A	The request was successful.
423	Request was blocked because another data operation is already running	You can't upload to the same batch ID concurrently. You must perform uploads consecutively.

Example 33. Delete products

## Soft delete
curl -d '[{
    "id": 124,
    "pup:isdeleted": 1
}]'
https://platform-api.productsup.io/platform/v2/sites/Identifier:123/products/md5string32chars/upload

## Hard delete
curl -d '[{
    "id": 124,
    "pup:isdeleted": -1
}]'
https://platform-api.productsup.io/platform/v2/sites/Identifier:123/products/md5string32chars/upload

<?php
// Soft delete
$ProductService->delete(array(
        'id' => 123,
    )
);

// Hard delete
$ProductService->insert(array(
        'id' => 123,
        'pup:isdeleted' => -1
    )
);

Committing

Once you finish uploading all product data, you can start processing the data. This is done batch by batch, so it's advisable to use one batch ID per upload, even if it consists of multiple upload requests.

Example 34. HTTP Request

POST https://platform-api.productsup.io/platform/v2/sites/<siteIdentifier>/products/<batchId>/commit

URL parameters

Field	Type	Description
siteIdentifier	mixed	Either `siteId` or `siteTags`. See Site identifier values.
batchId	string (32 characters)	Any sequence of characters that indicates a unique batch. It should be exactly 32 characters long. One possibility is to generate a unique number and hash it with the md5 algorithm.

HTTP headers

Name	Value
Content-Type	application/json

Request body fields

Field	Type	Description
type	string	Type of upload. See Type values.
automatic_import	boolean	Determines if the automatic triggering of an import and export is scheduled.

Automatic import and export scheduling

The default behavior is that 20 minutes after a commit we schedule a full process (import and export). Every new commit within this time frame resets the time to 20 minutes after that commit. After the last commit, the process triggers, this is the default behavior. Therefore we recommend setting the value of automatic_import to true.

Via the process endpoint, it's possible to programmatically trigger a process to be more specific about the type. When implementing this, we recommend a value of false for the key automatic_import. See Process.

Type values

Value	Description
full	The current upload are all products for the given site, all data from past uploads will be removed.
delta	The current upload is only a part of all your products. Use this in case you plan to send incremental uploads.

Note

When setting up the API as a Data Source in our Platform, the field Product Update Mode represents the mode of handling products.

See the following table and set values accordingly:

Commit value	Product Update Mode value
full	replace
delta	update

Response status code

Code	Message	Details
200	N/A	The request was successful
423	A request was blocked because another data operation is already running	Concurrent commits are not allowed, since it's a one-time operation for a batch ID. So once a commit starts, we lock it until a response is given.

curl --header 'Content-Type: application/json' -d '{"type":"full", "automatic_import":true}'
https://platform-api.productsup.io/platform/v2/sites/Identifier:123/products/md5string32chars/commit

<?php
$ProductService->setImportType(\Productsup\Service\ProductData::TYPE_DELTA);
// OR
$ProductService->setImportType(\Productsup\Service\ProductData::TYPE_FULL);

// Disable automatic import scheduling, by disabling this a process needs to be triggered via the process endpoint
$ProductService->setAutomaticImportScheduling(false);

// note: if you do not define the type the "full" is used as default
$result = $ProductService->commit();

Discarding

If something has gone wrong during the upload process, it is possible to cancel the whole batch. This allows you to be more strict with your data integrity. This is achieved by calling the discard endpoint on a batch id.

Example 35. HTTP Request

POST https://platform-api.productsup.io/platform/v2/sites/<siteIdentifier>/products/<batchId>/discard

URL parameters

Field	Type	Description
siteIdentifier	mixed	Either `siteId` or `siteTags`. See Site identifier values.
batchId	string (32 characters)	Any sequence of characters that indicates a unique batch. It should be exactly 32 characters long. One possibility is to generate a unique number and hash it with the md5 algorithm.

HTTP headers

Name	Value
Content-Type	application/json

curl https://platform-api.productsup.io/platform/v2/sites/Identifier:123/products/md5string32chars/discard

<?php
$result = $ProductService->discard();

Deleting

It's possible to delete all product data stored in the Platform API by sending a DELETE request. Once you have sent the request on the next run it will import zero (0) products and clear all stored data. This also lets you start sending new requests with data after the delete request.

curl --header 'Content-Type: application/json' 
--request DELETE 'http://platform-api.productsup.io/platform/v2/sites/Identifier:123/products'

Product data (read)

Get

Example 36. HTTP Request - Get product data

GET https://platform-api.productsup.io/product/v2/site/<siteId>/stage/<stageName>/<stageId>?limit=<limit>&ofset=<offset>&fields=<fields>&hidden=<hidden>&filter=<filter>

URL parameters

Field	Type	Description
siteId	integer	Site identifier
stageName	integer	Stage name. See Stage names.
stageId	integer	Stage Id, set to `0` for import and intermediate stages

Stage names

The following table represents the processing stages in which the product data is available. Each stage can add transformations and filters on product data. Export and channel are quite similar in their use. However we no longer use new exports, we only create new channels.

Name	Stage description
import	Directly after importing the product data from an API upload
intermediate	Generic transformations, always required for all product data, may be applied
export	Apply specific export transformations
channel	Apply specific channel transformations

Query fields

The query fields allow more precise control over the product data being returned. Certain requirements and filters can be set, as well as functionality to paginate through long result sets.

Name	Type	Default	Description
limit	integer	5000	Maximum number of products
offset	integer	0	Offset for querying products
fields	array	all fields	An array of fields to select
hidden	numeric boolean (0 or 1)	0	If set to `1`, hidden fields, which are you don't export are included.
filter	string	none	Condition to filter for in SQL syntax. See SQL - Operators for more information.

Response body fields

Field	Type	Description
success	boolean	Indicates request status
products	array	Product data list at least containing an ID column

curl  https://platform-api.productsup.io/product/v2/site/123/stage/intermediate/
    ?filter=id+%3C%3E+%27%27
    &limit=5000
    &offset=0
    &fields%5B0%5D=id
    &fields%5B1%5D=gtin
    &hidden=0
{
    "success": true,
    "products": [{
        "id": "123",
        "gtin": "42"
    }]
}

<?php
$productData = new \Productsup\Service\ProductData($client);
$reference = new \Productsup\Platform\Site\Reference();
$reference->setKey(\Productsup\Platform\Site\Reference::REFERENCE_SITE);
$reference->setValue(123); // site id
$productData->setReference($reference);

$query = new \Productsup\Query();
$query->fields = array(
    'id',
    'gtin'
);

$query->filter = "id <> ''";
$query->limit = 5000;
$query->offset = 0;

$products = $productData->get(
    \Productsup\Service\ProductData::STAGE_INTERMEDIATE,
    0,
    $query
);

result:
Array
(
    [success] => 1
    [products] => Array
        (
            [0] => Array
                (
                    [id] => 123
                    [gtin] => 42
                )
        )
)

HTTP Request - Get product data properties

GET https://platform-api.productsup.io/product/v2/site/<siteId>/stage/<stageName>/<stageId>/properties

URL parameters

Field	Type	Description
siteId	integer	Site identifier
stageName	integer	Stage name. See Stage names.
stageId	integer	Stage Id, set to `0` for import and intermediate stages

Response body fields

Field	Type	Description
success	boolean	Indicates request status
columns	array	Data set columns
products	integer	The total amount of products in the data set

Response status code

Code	Message	Details
200	N/A	The process was successfully called or scheduled
429	Too many attempts	The API is rate-limiting your request. You can do a maximum of 60 requests per minute.

Warning

It's recommended that you do not make 60 requests per minute.

We can offer this product read endpoint, but it's not meant as a high-performing endpoint because of our infrastructure setup. We currently do not provide a high-performance product read endpoint. Depending on the complexity of the filter, the database size, and amount of columns, requests can sometimes take up to minutes or more. We expect you to not send concurrent requests and only send them consecutively in these cases.

Example 37. Get product data properties

curl https://platform-api.productsup.io/product/v2/site/123/stage/intermediate/0/properties/

result: 
{
    "success": true,
    "columns": ["id", "gtin", "price", ...],
    "products": 42
}

<?php
// see Product Data write for more info
$ProductService = new Productsup\Service\ProductData($Client);
$Reference = new Productsup\Platform\Site\Reference();

$productData = new \Productsup\Service\ProductData($client);
$reference = new \Productsup\Platform\Site\Reference();
$reference->setKey(\Productsup\Platform\Site\Reference::REFERENCE_SITE);
$reference->setValue(123); // site id
$productData->setReference($reference);
$metaData = $productData->getProperties(\Productsup\Service\ProductData::STAGE_INTERMEDIATE,0);
/** response: 
Array (
      [success] => 1
      [columns] => Array
          (
              [0] => id
              [1] => gtin
              [2] => price
              ...
          )
      [products] => 42
  )

*/

Site stream data sources

List stream data sources

List all stream data sources linked to a site.

HTTP Request

GET https://platform-api.productsup.io/platform/v2/sites/<siteId>/streams

URL parameters

Field	Type	Description
siteId	integer	Using a site identifier (numeric value)

Query fields

See Cursor parameters.

HTTP headers

Name	Value
Content-Type	application/json

Response fields

Field	Type	Description
success	boolean	Indicates request status
Sources	array	List of data sources. See Data source fields.
meta	array	Cursor details. See Cursor fields.

Data source fields

Field	Type	Description
id	integer	Data Source identifier
site_id	integer	This data source's site identifier
description	integer	Data source description
status	integer	List of valid statuses. See Data source status information.
source	string	Data source URL
import_type	integer	List of valid import type. See Data source import type information.
import_id	integer	Type of import method
settings	array	List of all settings related to data source

Data source import type information

Value for import type	Description
1	Main data feed
2	Additional data feed

Data source status information

Value for status	Description
active	Data source is fully operational
paused	Data source is paused and has not imported data

Response status codes

Code	Message	Details
200	Successfully return the list.	The list of all data sources related to a site is returned.
403	You don't have the rights to access this resource.	Lack of permissions to access the site.
404	The requested resource could not be found.	The site does not exist.
401	Unauthorized	You used an invalid authentication token.

curl --header 'X-Auth-Token: value' \
--header 'Content-Type: application/json' \
--request GET 'https://platform-api.productsup.io/platform/v2/sites/1/streams'

# result: 
{
    "success": true,
    "Sources": [
        {
            "id": 1,
            "site_id": 1,
            "description": "stream api",
            "source": "",
            "import_type": 1,
            "import_id": 331,
            "status": "active",
            "settings": [
                "stream : 1"
            ]
        }
    ],
    "meta": {
        "cursor": {
            "current": 0,
            "prev": 0,
            "next": 1,
            "count": 1
        }
    }
}

Create stream data source

Create a data source that reads Stream data.

HTTP Request

POST https://platform-api.productsup.io/platform/v2/sites/<siteId>/streams

URL parameters

Field	Type	Description
siteId	integer	Using a site identifier (numeric value)

HTTP headers

Name	Value
Content-Type	application/json

Request body fields

Field	Type	Description
stream_id	integer	Using a steam identifier (numeric value)
import_type	integer	List of valid import type. See Data source import type information.
description	string	Description of the data source
status	string	List of valid statuses. See Data source status information.

Request default values, if not included in request body

Field	Value
import_type	1
status	active

Response fields

Field	Type	Description
success	boolean	Indicates request status
Sources	array	List of data sources. See Data source fields.
meta	array	Cursor details. See Cursor Pagination.

Data source fields

Field	Type	Description
id	integer	Data Source identifier
site_id	integer	This data source's site identifier
description	integer	Data source description
status	integer	List of valid statuses. See Data source status information.
source	string	Data source URL
import_type	integer	List of valid import type. See Data source import type information.
import_id	integer	Type of import method
settings	array	List of all settings related to data source

Response status codes

Code	Message	Details
201	The stream data source for the site was created successfully.	The data source was created with stream configuration and linked to the site.
401	Unauthorized	You used an invalid authentication token.
403	You don't have the rights to access this resource.	Lack of permissions to access the site or stream.
404	The requested resource could not be found.	The site or stream does not exist.
422	The stream datasource for the site already exists.	The stream already linked the data source to the site.

curl --header 'X-Auth-Token: value' \
--header 'Content-Type: application/json' \
--request POST 'https://platform-api.productsup.io/platform/v2/sites/1/streams' \
--data-raw '{"import_type":1, "description":"stream api", "stream_id":1 , "status":"active"}'

# result:   
{
    "success": true,
    "Sources": [
        {
            "id": 1,
            "site_id": 1,
            "description": "stream api",
            "source": "",
            "import_type": 1,
            "import_id": 331,
            "status": "active",
            "settings": [
                "stream : 1"
            ]
        }
    ]
}

Update stream data source

Update the data source linked to the stream.

HTTP Request

PUT https://platform-api.productsup.io/platform/v2/sites/<siteId>/streams/<streamId>

URL parameters

Field	Type	Description
siteId	integer	Using a site identifier (numeric value)
streamId	integer	Using a stream identifier (numeric value)

HTTP headers

Name	Value
Content-Type	application/json

Request body fields

Field	Type	Description
import_type	integer	List of valid import type. See Data source import type information.
description	string	Description of the data source
status	string	List of valid statuses. See Data source status information.

Response fields

Field	Type	Description
success	boolean	Indicates request status
Sources	array	List of data sources. See Data source fields.
meta	array	Cursor details. See Cursor fields.

Data source fields

Field	Type	Description
id	integer	Data Source identifier
site_id	integer	This data source's site identifier
description	integer	Data source description
status	integer	List of valid statuses. See Data source status information.
source	string	Data source URL
import_type	integer	List of valid import type. See Data source import type information.
import_id	integer	Type of import method
settings	array	List of all settings related to data source

Response status codes

Code	Message	Details
200	The stream data source for the site was created successfully.	You updated the data source.
401	Unauthorized	You used an invalid authentication token.
403	You don't have the rights to access this resource.	Lack of permissions to access the site or stream.
404	The requested resource could not be found.	The site or stream does not exist.
422	The stream data source for the site doesn't exist.	The stream has no link to the site.

curl --header 'X-Auth-Token: value' \
--header 'Content-Type: application/json' \
--request PUT 'https://platform-api.productsup.io/platform/v2/sites/1/streams/1' \
--data-raw '{"import_type":1, "description":"stream api", "status":"active"}'

# result:   
{
    "success": true,
    "Sources": [
        {
            "id": 1,
            "site_id": 1,
            "description": "stream api",
            "source": "",
            "import_type": 1,
            "import_id": 331,
            "status": "active",
            "settings": [
                "stream : 1"
            ]
        }
    ]
}

Delete stream data source

Delete the data source linked to the stream.

HTTP Request

DELETE https://platform-api.productsup.io/platform/v2/sites/<siteId>/streams/<streamId>

URL parameters

Field	Type	Description
siteId	integer	Using a site identifier (numeric value).
streamId	integer	Using a stream identifier (numeric value).

HTTP headers

Name	Value
Content-Type	application/json

Response fields

Field	Type	Description
success	boolean	Indicates request status.
message	string	Indicates request message.

Response status codes

Code	Message	Details
200	The stream data source for the site was deleted successfully.	You deleted the data source.
401	Unauthorized	You used an invalid authentication token.
403	You don't have the rights to access this resource.	Lack of permissions to access the site or stream.
404	The requested resource could not be found.	The site or stream does not exist.
422	The stream data source for the site doesn't exist.	The stream has no link to the site.

curl --header 'X-Auth-Token: value' \
--header 'Content-Type: application/json' \
--request DELETE 'https://platform-api.productsup.io/platform/v2/sites/1/streams/1'

# result:  
{
    "success": true,
    "message": "Resource was deleted successfully!"
}

Process

You can use the process object to trigger processing actions on your site. Use the Platform API Client with the process object or make the call to the endpoint yourself.

Post

Trigger a processing action on your site.

URL parameters

Field	Type	Description
siteId	integer	The site you want to trigger for processing

HTTP headers

Name	Value
Content-Type	application/json

Insert the data as a JSON-Object.

Request body fields

Field	Type	Description
action	string	Action value. See Action value explanation.
id	integer	Export or channel id, only required for action types export and channel
batch_id	string	A batch ID that was recently committed.

Passing a batch_id triggers the process once the batch's data is ready for import.

Action value explanation

Action value	Description
import	Trigger an import on the site
export	Trigger an export, export ID is required (legacy export method)
channel	Trigger a channel, channel ID is required
export-all	Trigger all exports and channels
all	Trigger an import, all exports, and channels

Response body fields

Field	Type	Description
success	boolean	Indicates the job scheduling status on the Jenkins server
process_id	string	Process Identifier, aka PID (format: UUID 32 - only on success)
message	string	For failures, the field indicates why the request failed

Response status code

Note

In general, if this endpoint returns anything but a successful response, it's recommended that you wait 30 minutes before sending another request.

Code	Message	Details
200	N/A	The process was successfully called or scheduled
429	Too many attempts	The API is rate-limiting your request. You can do a maximum of 60 requests per minute.
429	Cannot trigger a new process, a process is already in the current queue	This indicates that the job queue for this site has a queued job. Don't retry, as the active or recently-queued job must first begin before another job can queue or run.
500	Could not trigger job because a lock is already acquired	A previous request for this site has locked any further requests. The lock is released once the previous request has returned a response.
500	Error occurred while interacting with the job server	This indicates a problem with the job-running infrastructure. A retry can be done to ensure it wasn't a single occurrence. Do not continuously retry with this error, as it may cause further issues.

Example 38. Triggering an action on your site

{
    "success": true,
    "process_id": "<uuid-32-formatted-string>"
}

<?php
$processAction = new Productsup\Service\Process($Client);

// Only required if not setting the site_id property for the model
$reference = new \Productsup\Platform\Site\Reference();
$reference->setKey($reference::REFERENCE_SITE);
$reference->setValue(123456789); 

$processModel = new Process();
$processModel->action = 'import';
// Only required for types 'export' or 'channel'
// $processModel->action_id = 1234567890;
$processModel->addReference($reference);
// Instead of a reference you can also set the site id manually
// $processModel->site_id = 123457890;

$result = $processAction->post($processModel);

var_dump($result);

/*
result will look like this:
bool(true)
*/

curl -X POST H "Content-Type:application/json" -d '{"action": "import"}' https://platform-api.productsup.io/platform/v2/process/<siteId>

Status

The status endpoint can be used to get a status of a Process Identifier (PID) for a specific site. A valid PID must always be given as secondary parameter. When calling the process endpoint, found at Process, it returns a valid PID. If an invalid PID is given, the sites status is always queued.

Get

Get the PID status for a site.

HTTP Request

GET https://platform-api.productsup.io/platform/v2/sites/<siteId>/status/<pid>

URL parameters

Field	Type	Description
siteId	integer	The site where the PID belongs
pid	string	Check the PID status

Response body fields

Field	Type	Description
success	boolean	Indicates request status
status	string	Indicates PID status. See Status value explanation.
links	array	List of links, to the resource itself and error resource, if there's a `failed` status

Status value explanation

Status value	Description
queued	Site queued. This is the default when PID is valid, but not yet visible
running	Site processing
success	The site has run, no errors were found
failed	The site has run, errors were found

curl -i -L -X GET \
    'https://platform-api.productsup.io/platform/v2/sites/<siteId>/status/<pid>'

{
    "success": true,
    "status": "failed",
    "links":[
        {
            ## Only available when status equals failed
            "errors": "http://platform-api.productsup.io/platform/v2/sites/<siteId>/errors?pid=<pid>"
        },
        {
            "self": "http://platform-api.productsup.io/platform/v2/sites/<siteId>/status/<pid>"
        }
    ]
}

API errors

The API follows HTTP Status Codes for error handling. As a body again JSON is returned. The error message provides more information about the specific error.

The API can return the following status codes:

Error code	Message
400	Bad Request -- Your request was malformed
401	Unauthorized -- You used an invalid authentication token
403	Forbidden -- The entity requested is hidden for administrators only
404	Not Found -- The specified entity could not be found
405	Method Not Allowed -- You tried to access an entity with an invalid method
406	Not Acceptable -- You requested a format that isn't JSON
410	Gone -- The entity requested has been removed from our servers
500	Internal Server Error -- We had a problem with our server. Try again later
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later

Example 39. Example error response

{
    "success": false,
    "message": "Forbidden, your auth token seems to be invalid"
}

<?php
try {
    // code that might result in an error from the API
} catch (\Productsup\Exceptions\ServerException $e) {
    // A exception at the API Server happened, should not happen but may be caused by a short down time
    // You may want to retry it later, if you keep getting this kind of exceptions please notice us.
    throw new Exception('Error at the productsup API, retry later');
} catch (\Productsup\Exceptions\ClientException $e) {
    // Most likely some of the data you provided was malformed
    // The error codes follow http status codes, @see http://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_Error
    // The message may give more information on what was wrong:
    echo $e->getCode().' '.$e->getMessage();
} catch (\Exception $e) {
    // Exceptions not within the Productsup namespace are not thrown by the client, so these exceptions were most likely
    // thrown from your application or another 3rd party application

    // however, if you don't catch Productsup exceptions explicitly, you can catch them all like this
    echo $e->getCode().' '.$e->getMessage();
    throw $e;
}

Stream API (v0.2)

Introduction

The Stream API is the latest addition to the APIs Productsup offers. Streams support a high throughput or number of items that undergo product changes and can leverage how you use your data in the Productsup Platform.

Because the Stream API does not have a PHP library, use the Open API Specification file to generate a client. See Download the Open API specification file.

Glossary

Term	Description
Stream	An account-bound space where you can send items via the Stream API. See Streams for more information.
batch	A collection of information about a group of products you send to Productsup.
site	A location in the Productsup platform where you import data from a Stream via Data Source.
product	Generic term to indicate data that you send to the Stream API. The Productsup API does not require you to send only product information. It lets you send different data types, as long as they follow the minimal requirements.
Data Source	A location in the Productsup platform from where you import data using a Stream.
Productsup platform	A connection between a Stream and a site. It lets clients select from where they want to import data. You can set this up in the Productsup platform.
Personal Access Token (PAT)	Means of authentication with the Productsup APIs.

Authentication

Productsup has renewed the Stream API's authentication layer compared to existing APIs. This authentication layer is based on the PAT concept and links to user accounts. In the future, you can finely control user permissions. However, there are currently no specific authorizations other than full access.

Each request you make to the Stream API needs authentication. To receive authentication, you must send an authorization header with a bearer token.

Example 40. Header format:

Authorization: Bearer <token>

At the point where you can't create or refresh tokens, Productsup can offer you a token if you request Stream API access.

Example 41. Authentication request, which actually lists streams (cURL example only)

curl --location --request GET 'https://stream-api.productsup.com/streams/124773' \
--header 'Authorization: Bearer <token>'

API standards

The Stream API follows the JSON API standard. All requests and responses follow this standard and use the content-type application/vnd.api+json. Productsup does not accept the content-type set with the JSON API Standard to request bodies for product uploads because:

The application/vnd.api+json content-type has too much overhead for product data.
The application/x-ndjson performs best when extracting single products from a request.
Productsup considers the application/json as a legacy standard and does not wish to force existing customers to change their entire integration.

The non-acceptance does not imply that Productsup doesn't support sending data in application/vnd.api+json format. However, there is a need to understand the value first.

Note

Product data upload endpoints are the only exception to the JSON API Standard.

Streams

The Productsup Stream API relies on a concept called Streams. The Productsup Streams API lets JavaScript programmatically receive and access streams of structured data over the network for you to process them as desired.

You can reuse Streams when importing to multiple sites allowing others to reuse the data.
You can reuse multiple Streams when importing into a single site, which lets you efficiently merge data from different systems.
You can create and manage Streams; coming soon as part of the second release.
Streams support different structured data types. For now, the input to the following format is limited, but Productsup built flexibility to support the expansion of various formats in the future.
- Classic JSON
- Newline Delimited JSON (NDJSON). See ndjson Newline Delimited JSON.

Stream types: Chunked and Referenced

The Stream API supports two stream types for handling data:

Chunked type
Referenced type

Chunked

The Chunked Stream type was to support clients who require high throughput for single product updates. Chunked enforces the use of the NDJSON format. The structure makes the object deserialization uncomplicated and lets you leverage it to process large data volumes.

Referenced

Use the Referenced Stream type to send large amounts of data in grouped segments. For now, this also lets you send data in the standard JSON format, which is not possible with the chunked approach. At this moment, Productsup doesn't accept nested objects for both NDJSON and JSON formats.

Stream management

The Stream management endpoints offer independence and flexibility to Productsup customers. These endpoints let you integrate Stream management into your workflow.

Stream creation

Two attributes are required when you create a Stream:

name - Arbitrary value clients can use to identify their Stream. This is also visible in the UI when you select a Stream in Data Source.
type - Stream type, Chunked or Referenced. See Stream types: Chunked and Referenced.

Example 42. Create a Stream (cURL example only)

curl --location --request POST 'https://stream-api.productsup.com/streams' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Accept: application/vnd.api+json' \
--data-raw '{
  "data": {
    "type": "stream",
    "attributes": {
      "name": "My product stream",
      "type": "chunked"
    }
  }
}'

List Stream

You can list all Streams users have access to or a specific individual stream.

Example 43. List all Streams (cURL example only)

curl --location --request GET 'https://stream-api.productsup.com/streams' \
--header 'Accept: application/vnd.api+json'

Example 44. List Streams next page (cURL example only)

curl --location --request GET 'https://stream-api.productsup.com/streams?page[offset]=10&page[limit]=10' \
--header 'Accept: application/vnd.api+json'

Example 45. List a specific Stream (cURL example only)

curl --location --request GET 'https://stream-api.productsup.com/streams/124773' \
--header 'Accept: application/vnd.api+json'

Update Stream

It's not possible to change the Stream type because of technical limitations. If you require changes, it's suggested you create a new Stream with the correct Stream type and remove the previous type.

Note

You can only change the name of a Stream when you perform an update.

Example 46. Update a specific Stream (cURL example only)

curl --location --request PATCH 'https://stream-api.productsup.com/streams/124773' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Accept: application/vnd.api+json' \
--data-raw '{
  "data": {
    "id": "124773",
    "type": "stream",
    "attributes": {
      "name": "My product Stream with an updated name"
    }
  }
}
'

Remove Stream

Remove Streams to clean up operations that are no longer needed or if a client needs to switch between Stream types. You delete all contained data when you delete a stream as well. If you removed a client(s) because you switched between Stream types, you must push the entire catalog to the new Stream.

All data inside the Stream is unrecoverable after deletion.

Example 47. Remove a Stream (cURL example only)

curl --location --request DELETE 'https://stream-api.productsup.com/streams/124773'

Pushing data

There is a single endpoint to push data to Productsup:

/streams/{streamId}/products

Note

The endpoint to push data is not REST compatible. Therefore the POST, PATCH, and PUT methods all produce similar behavior.

Request body

The Stream type attribute indicates which content types you can send in the request body. For now, the accepted content type headers are:

application/x-ndjson
application/json

Accompany every request with the correct Content-Type header. The platform does not support mixing different content types in a single Stream.

Example 48. NDJSON with one product (cURL example only)

curl --location --request POST 'https://stream-api.productsup.com/streams/124773/products' \
--header 'Content-Type: application/x-ndjson' \
--header 'Accept: application/vnd.api+json' \
--data-raw '{"id":"34SKJDF42DF","name":"Product 1","company":"My Company"}'

Example 49. NDJSON with multiple products (cURL example only)

curl --location --request POST 'https://stream-api.productsup.com/streams/124773/products' \--header 'Content-Type: application/x-ndjson' \--header 'Accept: application/vnd.api+json' \--data-binary @- <<EOF{"id":"34SKJDF42DF","name":"Product 1","company":"MyCompany"}{"id":"475-SHIRT-XL","name":"Product 2","company":"My Company","size":"XL"}{"id":7824796324,"name":"Product 3","company":"My Company","price":5,"sale_price":4.5}EOF

Example 50. JSON with one product (cURL example only)

curl --location --request POST 'https://stream-api.productsup.com/streams/124773/products' \
--header 'Content-Type: application/json' \
--header 'Accept: application/vnd.api+json' \
--data-raw '[{"id":"34SKJDF42DF","name":"Product1","company":"My Company"}]'

Example 51. JSON with 3 products (cURL example only)

curl --location --request POST 'https://stream-api.productsup.com/streams/124773/products' \--header 'Content-Type: application/json' \--header 'Accept: application/vnd.api+json' \--data-binary @- <<EOF [{"id":"34SKJDF42DF","name":"Product 1","company":"MyCompany"}, {"id":"475-SHIRT-XL","name":"Product 2","company":"My Company","size":"XL"},{"id":7824796324,"name":"Product 3","company":"My Company","price":5,"sale_price":4.5}]EOF

Product attribute requirements

Productsup doesn't enforce a specific standard set of attributes or naming conventions. However, Productsup recommends that you always require an id attribute is present. Requiring this attribute is fundamental. The id attribute is a unique identifier for your specific data row, and the platform uses the id attribute to create new rows, apply permutations, and delete particular rows.

Note

The id attribute is the only mandatory attribute.

Productsup recommends the following for naming and handling attributes:

Use product attributes freely. However, it's ideal that these attributes are lowercase and do not contain spaces or special characters.

Note

Productsup relies on and is technically bound to the SQLite format's limitations .

When you add new attributes in future requests:

New attributes expand existing data horizontally with empty values.

When attributes are no longer part of the push, the platform considers them removed.

If any existing data contains a value for a removed attribute, the attribute remains. Any new data without a specified value has an empty attribute value.

If no existing data contains an attribute value, the push automatically removes the data at a certain point.

Process data

The process endpoint lets you control when your data flows in and out of the platform. It supports triggering jobs to import and export your data in the following combinations:

Import - Imports the data from all data sources into a site.
Export - Exports the data for one or all configured channels.
Combined - Runs an import and consecutively exports to all channels.

Tips and tricks

It's essential to keep the following topics in mind:

The Process endpoint works with sites, not Streams.
The site(s) should have a data source set up to import from your Stream(s).
Only a single process can run per site. Productsup lets you queue up to one (1) additional process.
Authentication works with the Personal Access Token (PAT) and Platform API Authentication.
- Ensure that your PAT has access to the site, either:
  - The PAT should belong to a user that is part of the account where the site remains. Or,
  - Grant site-specific access to the user where the PAT belongs.

Note

The process endpoint is the first unified endpoint, for example, that uses the new Stream API PAT authentication to access functionality from the Platform API.

Get your data into the platform

Example 52. URL example

POST http://platform-api.productsup.io/platform/v2/process/<siteIdentifier>

URL parameters

Field	Type	Description
siteId	integer	The site you want to trigger for processing.

Note

To learn about the platform API sites, see Sites.

HTTP headers

Name	Value
Content-Type	`application/json`

Provide the data for insertion as a JSON-Object.

Request body fields

Field	Type	Description
action	string	Action value. See Action value explanation.
id	integer	Export or channel id, only required for action types export and channel
batch_id	string	Only relevant for Platform API integration. See Request body fields.

Note

The batch_id parameter is not relevant when importing from Streams. Once you push the data to a Stream, it is available for import immediately.

Action value explanation

Action value	Description
import	Trigger an import on the site.
export	Trigger an export using sing an old exporting style. The export ID is required.
channel	Trigger a channel using a new exporting style. The channel ID is required.
export-all	Trigger all exports and channels.
all	Trigger an import on all exports and channels.

Request body fields

Field	Type	Description
success	boolean	Indicates the job scheduling status on the Jenkins server.
process_id	string	Process Identifier, also known as PID (format: UUID 32, only on success).
message	string	For failures, this field indicates why the request failed.

Note

If this endpoint returns anything except a successful response, Productsup recommends a 30-minute cool-down period before sending another request.

Response status codes

Code	Message	Description
200	N/A	The requested or scheduled process was successful.
429	Too many attempts	The API rate limits your request. You can make one (1) request per site every five (5) minutes.
429	Cannot trigger a new process, a process is already in the current queue	This error indicates that your site's job queue still contains a queued job. Retrying, in this case, makes little sense since the current job in the queue needs to start before you send another job to the queue or perform a run.
500	Could not trigger job because a lock is already acquired	A previous request for this site has locked any further requests. The lock is released once the last request returns a response.
500	Error occurred while interacting with the job server	This error indicates a problem with Productsup's job-build infrastructure. You can perform a retry to ensure it isn't a single occurrence. However, continuously retrying this error may cause problems.

Example 53. Trigger an import with PAT authentication (cURL example only)

curl --location --request POST 'http://platform-api.productsup.io/platform/v2/process/1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{"action":"import"}'

Batches

Once you send product data via API, it responds with a status and a batch identifier or batch ID. Use the batch ID to check the status of a specific payload.

Here are the three overall batch statuses that Productsup tracks:

uploaded - If you fully or partially upload products to a Stream.
processed - If you fully or partially process and import products to a site.
failed - If all products from a batch are invalid during the upload or processing stage.

Each batch goes through two stages, upload, and processing. You can find one of three statuses in each stage:

success - The platform found no invalid products.
warning - The platform found at least one (1) invalid product.
failure - All products are invalid.

Note

The Batches section is a work in progress. See Open API Spec for more information.

Example 54. This is site-specific. The following request illustrates a chunked site (cURL example only):

curl --location --request GET 'https://stream-api.productsup.com/streams/124773/batches/b15e8bb1-bd53-470a-9597-785003536978' \
--header 'Accept: application/vnd.api+json'

Partial uploads

When you upload a batch that contains some invalid products, a chunked stream accepts it as a partial upload and responds with a 202 Accepted HTTP status code. The data.attributes.stages.upload batch object property next includes the status of the upload stage, the number of successfully uploaded products, how many invalid products the platform found, and a list of captured unique error messages containing example, raw product data.

A referenced stream does not validate products on upload and consistently indicates that an upload returned a success or failure status.

Processing

When you run an import process, the API updates the batch objects property data.attributes.stages.processing with the status of the processing stage. This process includes the number of successfully imported products, errors encountered, and a list of unique error messages captured with raw product data examples.

Delete products

You can use the following two endpoints to delete product data:

/streams/{streamId}/products/ - Supports the deletion of one, several, or all products via the request body.
/streams/{streamId}/products/{productId}/ - Supports the deletion of a single product via URL.

Delete products via the request body

You can delete one or several products by:

Sending a request to the endpoint /streams/{streamId}/products/.
Sending a request body with a list of id attributes for the products you want to remove.

If you want to delete all products, you need to add the query parameter and value all=true to the URL. In this case, you can exclude the request body.

Example 55. Delete a single product (cURL example only)

curl --location --request DELETE 'https://stream-api.productsup.com/streams/124773/products' \
--header 'Content-Type: application/x-ndjson' \
--header 'Accept: application/vnd.api+json' \
--data-raw '{"id":34SKJDF42DF}'

Example 56. Delete multiple products (cURL example only)

curl --location --request DELETE 'https://stream-api.productsup.com/streams/124773/products' \
--header 'Content-Type: application/x-ndjson' \ 
--header 'Accept: application/vnd.api+json' \
--data-binary @- <<EOF
{"id":"34SKJDF42DF"}
{"id":"475-SHIRT-XL"}
{"id":7824796324}
EOF

Example 57. Delete all products (cURL example only)

curl --location --request DELETE 'https://stream-api.productsup.com/streams/124773/products?all=true' \
--header 'Accept: application/vnd.api+json'

Delete a product via the URL

Delete single products by making a request to /streams/{streamId}/products/{productId}/.

Example 58. Delete a single product (cURL example only)

curl --location --request DELETE 'https://stream-api.productsup.com/streams/124773/products/475-SHIRT-XL' \
--header 'Accept: application/vnd.api+json'

Import data

Setting up an import using the Productsup Stream API is relatively straightforward, but if you need help, use this guide to help you through the process.

Prerequisites

You have user access to the Productsup platform.
You have a site in the Productsup platform ready to import data.
You have a Stream. Both the Stream ID and name(s) are noteworthy.

Note

If you are missing any of the prerequisites, contact support@productsup.com.

Set up the import

Go to Data Sources from your site's main menu and select ADD DATA SOURCE.
In the search field, search for Stream API. You should see the Stream API Data Source.
Add the data source by selecting Add.
You can give your data source a custom name. If you're using multiple data sources, it's more efficient to identify each data source.
Once done, select Next, and you are on the Data Source Configuration page.
The Data Source configuration consists of two parts:
1. Select the Stream from where you want to import. You can use the label Stream to find your Stream.
2. You can optionally change the Description. The description contains the same attribute previously found in step 5.
Select Save to store all settings, and the platform returns you to the Data Sources page.
If your Stream already contains data, you can import it by selecting Import in the upper-right corner.
Once the import is complete, you can view your data in the Data View menu.

Rate limiting

Different endpoints of the Stream API are subject to other rate limits. The platform calculates rate limits based on the client's IP address and the accessed endpoint URL path.

The following table shows that the client's IP and URL unique stream ID limit the products and batch endpoints. That means each stream gets rate-limited independently.

Endpoint	Description	Limit
`/streams/{streamId}/products`	Products endpoint for pushing data	30 requests per second per `{streamId}`
`/streams/{streamId}/batches`	Batch endpoints for reading the processing status of a batch	30 requests per second per `{streamId}`
`/*`	All other endpoints	5 requests per second

Rate limit HTTP headers

The response headers of all HTTP requests sent to the Stream API show your current rate limits:

Name	Description
ratelimit-limit	The maximum number of requests allowed per second.
ratelimit-observed	The number of requests remaining in the current rate limit window.
ratelimit-reset	The time at which the current rate limit window resets in Unix time.

An error response returns if you exceed the rate limit.

Example 59. Error response for exceeding the rate limit

$ curl -I https://stream-api.productsup.com
HTTP/2 200
ratelimit-limit: 5
ratelimit-observed: 1
ratelimit-remaining: 4
ratelimit-reset: 1651174223

$ curl -I https://stream-api.productsup.com
HTTP/2 200
ratelimit-limit: 5
ratelimit-observed: 1
ratelimit-remaining: 4
ratelimit-reset: 1651174223

HTTP/2 429
ratelimit-limit: 5
ratelimit-observed: 5
ratelimit-remaining: 0
ratelimit-reset: 1651174223

{"errors":[{"status":"429","title":"Too Many Requests"}]}

HTTP/2 429
ratelimit-limit: 5
ratelimit-observed: 5
ratelimit-remaining: 0
ratelimit-reset: 1651174223

{"errors":[{"status":"429","title":"Too Many Requests"}]}