Introduction into our APIs

Welcome to the Productsup API Documentation space!

At this moment we have the following APIs available for our client:

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

The APIs overlap in certain parts of the functionalities, we can make the following division:

• 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
  • Find information 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 Platform API
    • High performance solution offered by Stream API
  • Product Data read
    • Access to data via Platform API

Platform API

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, please see the Readme.md for more information. We will accept non-breaking changes from client pull requests.

Authentication

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

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.

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.

Cursor Pagination

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

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

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

HTTP Request

only GET requests that return a list of entities

Example

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

Cursor parameters

Response fields

Cursor fields

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.

Requesting a list of all your projects

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

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

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

Get all projects for your account

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

Get a project by its identifier

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

URL parameters

Response fields

Project fields

Link fields and values

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

Create project

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

HTTP headers

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

Request body fields

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

Response fields

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

Update project

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

URL parameters

HTTP headers

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

Request body fields

Response fields

Project fields

See project fields

Links fields and values

See link fields

Delete

Delete project

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

URL parameters

Response body fields

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.

Requesting a list of all your 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] =>
        )
    ...
*/

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 id or tag

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

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

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

Get all sites for your account

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

Get all sites for a specific project

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

URL parameters

Get a site by its tag

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

URL parameters

More information about references aka site tags.

Get a site by its identifier

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

URL parameters

Response fields

Site fields

Links fields and values

Site status information

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
)

*/

Create site

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

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

URL parameters

HTTP headers

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

Request body fields

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.

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 site tag, consist of a tagName and tagValue. The reference format looks as follows: tagName:tagValue.

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

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

HTTP headers

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

Request body fields

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

Delete site

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

URL parameters

Response body fields

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.

Requesting all channels of one site

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

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

Optional query parameters

Response fields

Error fields

Links fields and values

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

Response fields

Site fields

Links fields and values

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

Get all channels for a site

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

URL parameters

Get a channel by its identifier

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

URL parameters

Response fields

Channel fields

Links, fields and values

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

Response fields

Channel fields

Links fields and values

History fields

Product Data (Write)

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:

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.

Response status codes

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

Site identifier values

HTTP headers

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

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

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

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 automatic_import.

Type values

Values should be set accordingly:

Response status codes

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

There are two ways to delete products in the Platform API.

Deleting all products

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.

Deleting one or more 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. Soft deleted products will not be exported.
• 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. A full upload will also override all data, so it's not needed to remove outdated products beforehand.

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

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.

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.

Response body fields

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

Response status codes

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.

Site Stream Datasources

List stream datasources

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

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

Query fields

See cursor parameters

HTTP headers

Response fields

Datasource fields

Datasource import type information

Datasource status information

Response status codes

Create stream datasource

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

Create stream datasource

Create a datasource that read data from Stream

HTTP Request

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

URL parameters

HTTP headers

Request body fields

Request default values (if not included in request body)

Response fields

See response fields

Datasource fields

See datasource fields

Response status codes

Update stream datasource

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

Update stream datasource

Update the datasource that is linked to the stream

HTTP Request

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

URL parameters

HTTP headers

Request body fields

Response fields

See response fields

Datasource fields

See datasource fields

Response status codes

Delete stream datasource

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

Update stream datasource

Delete the datasource that is linked to the stream

HTTP Request

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

URL parameters

HTTP headers

Response fields

Response status codes

Process

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

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

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

URL parameters

HTTP headers

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

Request body fields

Passing a "batch_id" will trigger the process once the batch's data is ready for an import.

Action value explanation

Response body fields

Response status codes

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

Response body fields

Status value explanation

API Errors

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

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:

Stream API

Introduction

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

Glossary

Authentication

Example authentication request (actually lists streams)

# Stream API only has cURL examples

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

We have renewed the authentication layer for the Stream API in comparison with our existing APIs. It's based on the concept of PAT. The Products platform links PATs to user accounts. In the future, they will let you 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.

The following is an example of the header format:

Authorization: Bearer <token>

At the point when it's not yet possible to create or refresh tokens, this function later follows. Productsup will then offer a token to clients who request Stream API access.

API Standards

The Stream API follows the JSON API standard. This implies that all requests and responses are following the defined structure and are using 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. The reason for this is because:

• The application/vnd.api+json content-type has too much overhead for product data
• The application/x-ndjson offers better performance when extracting single products from a request
• The application/json is our legacy standard, as Productsup does not want to force existing clients to change their entire integration

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

Streams

With this API we're introducing a concept called Streams. Streams are spaces where we can receive ongoing flows of structured data. Streams leverage our clients to use their data in any way they want, since:

• Multiple Streams can be used when importing into a single site; allowing clients to easily merge data from different systems
• Streams can be created and managed by clients themselves
• Streams support different structured data types; for now we've limited the input to the following format, but the flexibility we built in supports expansion of different formats in the future
  • Classic JSON
  • Newline Delimited JSON(NDJSON)

Stream types: Chunked & Referenced

The Stream API supports two Stream types for handling data: - Chunked type - Referenced type

Chunked

The design of chunked type was to support clients who require high throughput for single product updates. Chunked enforces the use of the NDJSON format. Because of its structure, we can keep the object deserialization simple and leverage it to process more data.

Referenced

The referenced type is for clients who send large quantities of data in grouped segments. For now, this also lets clients send data in the regular JSON format, which is not possible with the chunked approach.

Stream Management

The Stream Management endpoints bring independence and flexibility to our clients. They let clients integrate Stream management into their workflow.

Stream creation

Example: Create a Stream

# Stream API only has cURL examples

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

When you create a Stream, two attributes are required:

• name - arbitrary value clients can use to identify their Stream.
  This is also visible in the UI when selecting a Stream in a Data Source
• type - the Stream type, chunked or referenced
  See Stream types: chunked and referenced

List Stream

Example: List all Streams

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

Example: List Streams next page

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

Example: List a specific Stream

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

You can either list all streams the user has access to or a specific, individual stream.

List of all streams is paginated to a maximum of 10 streams per page. To traverse the paginated list you can use the pagination links which can be found in the top-level links object of the response.

Update Stream

Example: Update a specific Stream

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

Because of technical limitations, it's not possible to change the type of Stream. In case you require changes, we advise you to create a new Stream with the correct type and remove the old Stream.

Remove Stream

Example: Remove a Stream

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

Remove Streams to clean up streams that are no longer needed, or if a client needs to switch between the type of a Stream. When you delete a stream, you are deleting all contained data as well. In case you removed a client(s) because of a switch between stream types, you must push the full catalog to the new Stream.

When you remove a Stream, all data inside the Stream is unrecoverable after deletion.

Pushing Data

There is a single endpoint to push data to Productsup: /streams/{streamId}/products

Request body

Example 1: NDJSON with one product

# Stream API only has cURL examples

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 2: NDJSON with multiple products

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 3: JSON with one product

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 4: JSON with 3 products

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

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

• application/x-ndjson
• application/json

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

Product attribute requirements

We don't enforce a specific standard set of attributes or naming conventions. However, we always require that an id-attribute is present. This is our golden rule. The id-attribute is a unique identifier to your specific data row and the platform uses the id-attribute to create new rows, apply permutations, and delete specific rows.

We recommend the following for naming and handling attributes: - Use product attributes freely. However, it's ideal that they are in lowercase and do not contain any spaces or special characters.

• When you add new attributes in future requests:
  • New attributes horizontally expand existing data with empty values
• When attributes are not part of the push anymore, they are considered removed:
  • If any existing data has a value for that attribute, the attribute remains in existence. Any new data without a specified value has an empty value for the attribute.

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

Process Data

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

• Import: just import the data from all Data Sources into a side
• Export: just export the data for one or all configured Channel(s)
• Combined: run an import and consecutively export all Channels

Tips and tricks

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

• The Process endpoint works with Sites, not Streams
• The Site(s) should have a Data Source setup to import from your Stream(s)
• Only a single Process can run per site, we allow you to queue up to 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 in which the Site remains
    • The User to which the PAT belongs should be granted access to the specific Site

Get your data into the Platform

Trigger an import with PAT authentication

# Stream API only has cURL examples

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

URL example

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

URL parameters

HTTP headers

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

Request body fields

Action value explanation

Response body fields

Response status codes

Batches

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

Example Note: This is stream-specific. The following example uses the chunked stream:

# Stream API only has cURL examples

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

We keep track of 3 overall statuses of a batch:

• uploaded - when products were fully or partially uploaded to a stream
• processed - when products were fully or partially processed and imported to a site
• failed - when all products from a batch were invalid either during upload or processing stage.

Each batch transits through 2 stages: upload and processing and each stage can be found with one of 3 statuses:

• success - no invalid products were encountered
• warning - at least 1 invalid product was encountered
• failure - all products were invalid

Partial uploads

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

A referenced stream does not validate products on upload and will always indicate that an upload was either a success or failure.

Processing

When you run an import process, the property data.attributes.stages.processing of the batch object gets updated with the status of the processing stage, which also includes a number of successfully imported products, a number of errors encountered, and a list of unique error messages captured with example raw product data.

Delete products

We have two different endpoints that let clients 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

Example: Delete a single product

# Stream API only has cURL examples

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: Delete multiple products

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: Delete all products

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

You can delete one or several products by:

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

In case 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 omit the request body.

Delete a product via the URL

Example: Delete a single product

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

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

Import Data

Regardless of how familiar you are with the Productsup platform, setting up an import using the Stream API is fairly straightforward. But in case you need help, we'll guide you through the process below.

Prerequisites

• You have user access to the Productsup platform
• You have a site set up in the Productsup platform for importing the data
• You have a Stream at hand. Both the Stream ID and Stream name(s) are good to note

Set up the import

1. Open your site in the platform and go to Data Sources in the main menu.
2. Select Add Data Source.
3. In the search field, search for Stream API. You should see the Stream API Data Source.
4. Add the data source by selecting the Add.
5. You can give your data source a custom name. In case you're using multiple data sources, it's more efficient to identify each data source.
6. Once done, select Next and you are on the Data Source Configuration page.
7. The Data Source configuration consists of two parts:
   1. Select the Stream to import from. You can use the label Stream to find your Stream
   2. Changing the Description (if needed)
      This is the same attribute previously found in step 6.
8. Select Save to store all settings and the platform returns you to the Data Sources page.
9. If your Stream already contains data, you can now import it by selecting the Import in the upper-right corner.
10. Once the import is complete, you can view your data in the Data View menu.

Empty Data Sources

By default the Platform does not import from an empty Data Source, this usually indicates a failure. In certain API scenario's it can be required to import an empty Data Source, e.g. if all data needs to be purged.

1. Open your site in the platform and go to Data Sources in the main menu.
2. Edit the Stream API Data Source
3. Go to the tab Advanced Settings
4. Go to the Options
5. Check the checkbox Allow this datasource to have no products
6. Save the changes via Save Options

To disabled importing an empty Data Source repeat all steps and uncheck the checkbox for Allow this datasource to have no products.

Rate limiting

Different endpoints of the Stream API are subject to different rate limits. Rate limits are calculated based on the client's IP address and URL path of the accessed endpoint.

As visible in the following table, products and batches endpoints get rate limited by client's IP and by the unique stream ID from the URL. Meaning that each stream gets rate limited independently.

Rate limit HTTP headers

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

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

When you exceed the rate limit, an error response returns:

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

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