Introduction

The 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, please see the Readme.md for more information.

Authentication

All requests to our API require valid authorization. The authentication token can be built with the client ID and client secret, which will be issued by our team.

The token has the following format: client_id:client_secret, it needs to be sent as 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.

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

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

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

Version

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

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

Projects

Projects are used to group your Sites.

Get

Lists all or one projects of your account.

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

<?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
        )
    ...
)

# requesting a list of all your projects
curl https://platform-api.productsup.io/platform/v2/projects

# requesting one of projects
curl https://platform-api.productsup.io/platform/v2/projects/1

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

HTTP Request - All projects for your account

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

HTTP Request - Get a project by it’s 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

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

Links fields and values

Name	Description
self	Link to the project detail endpoint
sites	Link to a list of sites belonging to the project

Create

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

 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
        )
*/

HTTP Request

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	Name of the project

id and created_at have to 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

Project fields

See project fields

Links fields and values

See link fields

Edit

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

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

HTTP Request

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

URL parameters

Field	Type	Description
projectId	integer	Existing project that’s 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	Name of the project

Response fields

Field	Type	Description
success	boolean	Indicates request status
Projects	array	Details of the created project

Project fields

See project fields

Links fields and values

See link fields

Delete

HTTP Request

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

URL parameters

Field	Type	Description
projectId	integer	Project to delete

Response 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, below projects and have one data source and may have several exports/channels

Get

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

<?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);

// 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] =>
        )
    ...
*/

# requesting a list of all your sites
curl https://platform-api.productsup.io/platform/v2/sites

# requesting a list of all your sites within one project
curl https://platform-api.productsup.io/platform/v2/projects/321/sites

# requesting sites by tag
curl https://platform-api.productsup.io/platform/v2/sites/tagname:tagValue

# requesting one site by its ID
curl https://platform-api.productsup.io/platform/v2/sites/123

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

HTTP Request - All sites for your account

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

HTTP Request - 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

HTTP Request - Get a site by it’s 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

HTTP Request - Get a site by it’s 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

Site fields

Field	Type	Description
id	integer	Site identifier
title	string	Name of the site
status	string	List of valid statusses
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 as an identifier
processing_status	string	Status of the site’s latest job (Running/Done)
created_at	date	Date of creation
links	array	List of relevant resources

Links fields and values

Name	Description
self	Link to current site detail
tags	Link to a list of tags belonging to the site
project	Link to project

Site status information

Value for status	Description
active	The site is fully operational; data can be pushed via the API and the site will import and export
paused_upload	The site can receive data via the API and import the data; it will however not export data
disabled	The site will block any data send via the API, neither imports or exports can be done

Create

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

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
)

*/

HTTP Request

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 request body.

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
title	string	Name of the site
reference	string	Textual site reference, consisting of tagName and tagValue
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 statusses

id and created_at have to be 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 will set the identifier to "id". If an empty value "" is given for the id_column then the identifier column will not be set.

Response fields

See response fields

Site fields

See site fields

Links fields and values

See link fields

Edit

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

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

HTTP Request

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	Project under which to edit the site.
siteId	integer	Existing site that is 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	Existing site that will be edited.
project_id	integer	Project under which to edit the site.
title	string	Name of the site
id_column	string	ID column which is being used as an identifier when importing data to the platform.
status	string	List of valid statusses
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 then the identifier column will not be set.

Cron entries format consists of a timezone and schedule format. All PHP timezones are supported. A newline should be used as separator between the timezone and each schedule.

For example:

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

For the minute entry we accept a value H which indicates a random minute will be used. This has our preference, since it prevents many jobs starting at the exact same time. But it can be overridden if that is required.

Response fields

See response fields

Site fields

See site fields

Links fields and values

See link fields

Delete

HTTP Request

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 the success of the action

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.

<?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] => ...
        )
...
*/

# requesting all channels of one site
curl https://platform-api.productsup.io/platform/v2/sites/123/errors

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

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	Site to get the errors for

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

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

Links fields and values

Name	Description
self	Link to the error endpoint

Create

To create a new error (information) for one site, you can use a POST request (or the insert method).

curl -d '{"pid":"abd456def","error":123,"data":{"foo":"bar"}}' \
    https://platform-api.productsup.io/platform/v2/sites/123/errors

# result:
{
    "success": true,
    "Errors": [{
        "id": 42,
        "pid": "abc456def",
        "error": 123,
        "data": "{\"foo\":\"bar\"}",
        "site_id": 123,
        "links": [...]
    }]
}

<?php
$site = new \Productsup\Platform\Site();
$site->id = 123;
$errorService = new \Productsup\Service\Errors($client);
$errorService->setSite($site);
$result = $errorService->get();

$error = new \Productsup\Platform\Error();
$error->pid = 'something';
$error->error = 123;
$error->data = ['foo' => 'bar'];
$result = $errorService->insert($error);
print_r($result);

/**
Productsup\Platform\Error Object
(
    [id] => 42
    [pid] => something
    [error] => 123
    [data] => {"foo":"bar"}
    [links:protected] => ...
)
*/

HTTP Request

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

URL parameters

Name	Type	Description
siteId	integer	Site to which the error will be added

HTTP headers

Name	Value
Content-Type	application/json

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

Request body parameters

Field	Type	Description
pid	string	Process identifier
error	integer	Error id, this should be a valid identifier according to our error codes
data	array	Additional information about the error

Response fields

See response fields

Error fields

See error fields

Link fields and values

See link fields

Import History

With the endpoint import history, you may query for meta information about the last imports.

Get

Lists the information about your last imports.

<?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] => 
        )

)
*/

# requesting one site by its ID
curl https://platform-api.productsup.io/platform/v2/sites/123/importhistory

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

HTTP Request

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

URL parameters

Field	Type	Description
siteId	integer	Site to list import history for

Response fields

Field	Type	Description
success	boolean	Indicates request status
Sites	array	List of imports

Site fields

Field	Type	Description
id	integer	Internal ID
site_id	integer	ID of the referenced site
import_time	date	Date of the import
product_count	integer	Total amount of imported products
links	array	List of relevant resources

Links fields and values

Name	Description
site	Link to site

Channels

Channels are targets of the data (like “Google Shopping”, Amazon,..)

Get

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

<?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] => ...
        )
...
*/

# requesting all channels of one site
curl https://platform-api.productsup.io/platform/v2/sites/123/channels

# requesting a specific channel
curl https://platform-api.productsup.io/platform/v2/sites/123/channels/321

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

HTTP Request - Get all channels for a site

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

URL parameters

Field	Type	Description
siteId	integer	Site to list channels for

HTTP Request - Get a channel by it’s identifier

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

URL parameters

Field	Type	Description
siteId	integer	Site under which 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

Channel fields

Field	Type	Description
id	integer	ID of the site channel relation
site_id	integer	ID of the referenced site
channel_id	integer	ID of the channel
name	string	Name of the export you provided while creating the channel
export_name	string	Generic name of the export in the productsup system
links	array	List of relevant resources

Links fields and values

Name	Description
self	Link to channel detail
site	Link to site

Channel History

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

Get

To list the history, you can use get.

<?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(321,'history');

/*
result will look like this:
Array
(
    [0] => Productsup\Platform\Channel Object
        (
            [id] => 2116
            [site_id] => 368693
            [name] => Criteo DE
            [export_name] => FusePump Criteo
            [history] => Array
                (
                    [0] => Array
                        (
                            [id] => 25190
                            [site_id] => 368693
                            [site_channel_id] => 2116
                            [export_time] => 2015-08-27 16:22:57
                            [export_start] => 2015-08-27 16:22:55
                            [product_count] => 20562
                            [product_count_now] => 20562
                            [product_count_previous] => 0
                            [process_status] => 0
                            [pid] => 55df182bde8e8
                            [product_count_new] => 0
                            [product_count_modified] => 0
                            [product_count_deleted] => 0
                            [product_count_unchanged] => 0
                            [uploaded] => 0
                        )

                    [1] => Array
                        (
                            [id] => 25163
                            [site_id] => 368693
                            [site_channel_id] => 2116
                            [export_time] => 2015-08-27 15:48:03
                            [export_start] => 2015-08-27 15:48:02
                            [product_count] => 20562
                            [product_count_now] => 20562
                            [product_count_previous] => 0
                            [process_status] => 0
                            [pid] => 55df10f8c89d2
                            [product_count_new] => 0
                            [product_count_modified] => 0
                            [product_count_deleted] => 0
                            [product_count_unchanged] => 0
                            [uploaded] => 0
                        )

...
*/

# requesting the history of one channel
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"
                },
                ...
            ]
        }
    ]
}

HTTP Request

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

URL parameters

Field	Type	Description
siteId	integer	Site under which 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

Channel fields

Field	Type	Description
id	integer	ID of the site channel relation
site_id	integer	ID of the referenced site
channel_id	integer	ID of the channel
name	string	Name of the export you provided while creating the channel
export_name	string	Generic name of the export in the productsup system
links	array	List of relevant resources
history	array	List of channel history

Links fields and values

Name	Description
self	Link to channel detail
site	Link to site

History fields

Field	Type	Description
id	integer	Internal identifier
site_id	integer	Identifier of the referenced site
site_channel_id	string	Internal id for the combination of an Export and Site
export_time	dateTime	Time when the process was finished
export_start	dateTime	Time when the process was started
product_count	integer	Number of products exported
pid	string	Internal identifier for 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 it’s destination

Product Data (Write)

Uploading

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
    )
);

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.

HTTP Request

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

URL parameters

Field	Type	Description
siteIdentifier	mixed	Either a siteId or siteTags
batchId	string (32 characters)	Any sequence of characters which indicate a unique batch. It should be exactly 32 characters long. A possible idea is to generate a unique number and then 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 also site tags

HTTP headers

Name	Value
Content-Type	application/json

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

Product format

When uploading products the following rules apply:

• Columns can be named freely, but ideally should be in lowercase and not contain any spaces or special characters. Our technology relies on SQLite databases so that’s where our limits lie.
• When columns are added:
  • Existing data will have an empty value for these columns.
• When columns are not uploaded (removed):
  • If any existing data has a value for that column, it will remain and the new data will just have an empty value.
  • If no existing data has a value, that column will be automatically removed.
• The amount of products per upload request is limited to 10000. We recommend sending multiple upload requests with the same batch id, if you reach this limit.

A list of example product data:

id	title	price	shipping	pup:isdeleted
123	my first product	1.23
124	my second product	3.21	0.99
125	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, we will import the last product with the duplicate value.
When sending updates or in case a product needs to be deleted, the correct id should be used.

Deleting 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
    )
);

Deleting specific products can be achieved by adding the column pup:isdeleted. Depending on it’s value a soft or a hard delete can be triggered. A soft delete marks the product as deleted, but it will still show up in the Dataview of the Platform. When doing a hard delete, the product will not be imported and will not be visible in the platform.

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

Value for pup:isdeleted	Description
1	Soft delete, product will be present in platform, but marked
-1	Hard delete, product will not be present in platform
0	No delete, product will be present in 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	Concurrent uploads to the same batch id are not allowed. This needs to be done consecutively.

Committing

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
$productsService->setImportType(\Productsup\Service\ProductData::TYPE_DELTA);
// OR
$productsService->setImportType(\Productsup\Service\ProductData::TYPE_FULL);

// note: if you do not define the type the "full" is used as default

$result = $ProductService->commit();

Once you are finished with uploading all product data, you can start the processing of 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).

HTTP Request

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

URL parameters

See url parameters

HTTP Headers

See HTTP headers

Request body fields

Field	Type	Description
type	string	Type of upload
automatic_import	boolean	Whether the automatic triggering of an import & export should be scheduled.

Automatic import & export scheduling

The default behaviour 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 will then be triggered, this has been default behaviour. Therefore we recommend setting the value of automatic_import to true.

Via the process endpoint it’s possible to programmatically trigger a process and be more specific of the type. When implementing this, we recommend a value of false for the key automaticimport_.

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.

Values should be set accordingly:

Commit value	Product Update Mode value
full	replace
delta	update

Response status codes

Code	Message	Details
200	N/A	The request was successful
423	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.

Discarding

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

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

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

HTTP Request

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

URL parameters

See url parameters

HTTP Headers

See HTTP headers

Deleting

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

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

Product Data (Read)

Get

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

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
stageId	integer	Stage id, set to 0 for stages import and intermediate

Stage names

The table below 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	Specific export transformations are applied
channel	Specific channel transformations are applied

Query fields

The query fields allow a 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	Array of fields to select
hidden	numeric boolean (0 or 1)	0	If set to 1 also hidden fields (fields that are not exported) are included
filter	string	none	Condition to filter for, in SQL syntax

Response body fields

Field	Type	Description
success	boolean	Indicates request status
products	array	List of product data, at least containing and id column

<?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
  )

*/

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

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

HTTP Request - Get product data properties

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

URL parameters

See url parameters

Response body fields

Field	Type	Description
success	boolean	Indicates request status
columns	array	Columns of the data set
products	integer	Total amount of products in data set

Response status codes

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.

We can offer a this product read endpoint, but due to our infrastructure setup it’s not meant as a high-performing endpoint. We currently do not offer 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. In these cases we expect you to not send concurrent requests and only send then consecutively.

Process

Process can be used to trigger processing actions on your site. You can can 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.

<?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)
*/

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

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

HTTP Request

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

URL parameters

Field	Type	Description
siteId	integer	Site you want to trigger processing for

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
action	string	Action value
id	integer	Export or channel id, only required for action types export and channel
batch_id	string	An id of a batch that was recently committed.

Passing a “batch_id” will trigger the process once the batch’s data is ready for an import.

Action value explanation

Action value	Description
import	Trigger an import on the site
export	Trigger an export, export id is required (old style of exporting)
channel	Trigger a channel, channel id is required (new style of exporting)
export-all	Trigger all exports and channels
all	Trigger an import, all exports and channels

Response body fields

Field	Type	Description
success	boolean	Indicates status of job scheduling on the Jenkins server
process_id	string	Process Identifier aka PID (format: UUID 32 - only on success)
message	string	On failure this field will indicate why the request failed

Response status codes

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 1 request per site per 5 minutes.
429	Cannot trigger a new process, a process is already in the current queue.	This indicates that our job queue for this site still has a job that is queued. Retrying in this case makes little sense, since the current job in the queue needs to be started before another job can be queued or ran.
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 our job running infrastructure. A retry can be done to ensure it wasn’t a single occurrence. However continuously retrying on this error, just causes more problem.

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, it will return a valid pid. If an invalid PID will be given, the sites status will always be queued.

Get

Get the status of PID for a site

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

HTTP Request

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

URL parameters

Field	Type	Description
siteId	integer	Site to which the PID belongs
pid	string	The PID you want to check the status of

Response body fields

Field	Type	Description
success	boolean	Indicates status of the request
status	string	Indicates the status of the pid
links	array	List of links, to resource itself and error resource (if status equals failed)

Status value explanation

Status value	Description
queued	Site is queued (default when PID is valid, but not yet visible)
running	Site is being processed
success	Site has run, no errors found
failed	Site has run, but errors were found

API Errors

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

The API can return the following status codes:

# 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;
}

Error Code	Meaning
400	Bad Request – Your request was malformed
401	Unauthorized – Your API key is wrong
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 a 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
418	I’m a teapot
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarially offline for maintanance. Please try again later.