NAV
shell php

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.

For testing our API, you can use the Api Explorer

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 header.
The client id and 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 "api_endpoint_here"
  -H "X-Auth-Token: 1234:simsalabim"

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 request 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
status 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
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,
    "Sites": [{
        "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
status boolean Indicates request status
Sites array Details of the created project

Project fields

See project fields

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
status boolean Indicates request status
Projects array Details of the created project

Project fields

See project fields

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
$SitesService = new Productsup\Service\Projects($Client);
$result = $siteService->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
status boolean Indicates request status
Sites array List of sites

Site fields

Field Type Description
id integer Site identifier
title string Name of the site
created_at date Date of creation
project_id integer Identifier of the project this site belongs to
import_schedule string Import schedule
links array List of relevant resources
Name Description
self Link to current site detail
tags Link to a list of tags belonging to the site
project Link to project

Create

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

 curl
    -d '{"title":"example site","reference":"myReferenceKey:myReference1234"}'
    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';
/* 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 and created_at have to be empty, otherwise the values get overwritten, or the request may result in an error.

Response fields

See response fields

Site fields

See site fields

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
import_schedule string A cron entry that sets the scheduling for data import.

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

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
ls/321
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
status 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
links array List of relevant resources
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

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.com/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,
    "Sites": [{
                "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
status 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
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

Response fields

Field Type Description
status boolean Indicates request status
Channels array List of channels

Channel fields

Field Type Description
id integer Internal ID
site_id integer ID of the referenced site
channel_id integer ID of the referenced site
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
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


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

Response fields

Field Type Description
status boolean Indicates request status
Channels array List of channels

Channel fields

Field Type Description
id integer Internal ID
site_id integer ID of the referenced site
channel_id integer ID of the referenced site
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
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 -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:

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

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

Committing

curl -d '{"type":"full"}'
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

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

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

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

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

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 The Process Identifier (PID) (format: UUID 32)

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.