Introduction
The REST API provides programmatic access to read and write Productsup data. Create sites, upload product data, enable export channels and more.
For PHP users we provide an API Client, please see the Readme.md for more information.
Authentication
All requests to our API require valid authorization. The authentication token can be built with the client ID and client secret, which will be issued by our team.
The token has the following format:
client_id:client_secret
, it needs to be sent as value for the X-Auth-Token
HTTP header.
The client_id
and client_secret
are account specific, so you can only access projects,
sites and other resources which lie under your account.
<?php
$Client = new Productsup\Client();
$Client->id = 1234;
$Client->secret = 'simsalabim';
# With shell, you can just pass the correct header with each request
curl -H "X-Auth-Token: 1234:simsalabim" https://platform-api.productsup.io/
Make sure to replace
1234
andsimsalabim
with the client ID and secret you got provided.
Version
The API uses a URL based versioning mechanism. You can switch to the latest version by replacing v1 in the examples by v2.
If you are using the latest version Platform API Client, then you are automatically on the latest stable version.
Projects
Projects are used to group your Sites.
Get
Lists all or one projects of your account.
For both requests the response looks identical. Except when requesting a specific project it will just list the one project.
<?php
$projectService = new Productsup\Service\Projects($client);
$projects = $projectService->get();
print_r($projects);
/*
result will look like this:
Array
(
[0] => Productsup\Platform\Project Object
(
[id] => 1
[name] => default project
[created_at] => 2013-03-21 12:47:57
)
...
)
# requesting a list of all your projects
curl https://platform-api.productsup.io/platform/v2/projects
# requesting one of projects
curl https://platform-api.productsup.io/platform/v2/projects/1
# response:
{
"success": true,
"Projects": [{
"id": "1",
"name": "default project",
"created_at": "2013-03-21 12:47:57",
"links": [...]
}]
}
HTTP Request - All projects for your account
GET https://platform-api.productsup.io/platform/v2/projects
HTTP Request - Get a project by it’s identifier
GET https://platform-api.productsup.io/platform/v2/projects/<projectId>
URL parameters
Field | Type | Description |
---|---|---|
projectId | integer | Project to list |
Response fields
Field | Type | Description |
---|---|---|
success | boolean | Indicates request status |
Projects | array | List of projects |
Project fields
Field | Type | Description |
---|---|---|
id | integer | Internal ID |
name | string | Name of the project |
created_at | date | Date of creation |
links | array | List of relevant resources |
Links fields and values
Name | Description |
---|---|
self | Link to the project detail endpoint |
sites | Link to a list of sites belonging to the project |
Create
To create a new project, you can use a POST request (or the insert method).
curl -d '{"name":"test project"}' \
https://platform-api.productsup.io/platform/v2/projects
# result:
{
"success": true,
"Projects": [{
"id": 125,
"name": "test project",
"created_at": "2015-07-30 12:54:52",
"links": [...]
}]
}
<?php
$projectService = new Productsup\Service\Projects($Client);
$project = new Productsup\Platform\Project();
$project->name = "test project";
$projectService->insert($project);
print_r($result);
/**
result:
Productsup\Platform\Project Object
(
[id] => 125
[name] => test project
[created_at] => 2015-07-30 12:54:52
)
*/
HTTP Request
POST https://platform-api.productsup.io/platform/v2/projects
HTTP headers
Name | Value |
---|---|
Content-Type | application/json |
The data to be inserted has to be provided as a JSON-Object.
Request body fields
Field | Type | Description |
---|---|---|
name | string | Name of the project |
id
and created_at
have to be empty, otherwise the values get overwritten, or the request may result in an error.
Response fields
Field | Type | Description |
---|---|---|
success | boolean | Indicates request status |
Projects | array | Details of the created project |
Project fields
See project fields
Links fields and values
See link fields
Edit
To edit an existing project, you can use a PUT request.
curl -d '{"name":"example project"}' \
https://platform-api.productsup.io/platform/v2/projects/125
# result:
{
"success": true,
"Projects": [{
"id": 125,
"name": "example project",
"created_at": "2015-07-30 12:54:52",
"links": [...]
}]
}
HTTP Request
PUT https://platform-api.productsup.io/platform/v2/projects/<projectId>
URL parameters
Field | Type | Description |
---|---|---|
projectId | integer | Existing project that’s being edited. |
HTTP headers
Name | Value |
---|---|
Content-Type | application/json |
The data to be inserted has to be provided as a JSON-Object.
Request body fields
Field | Type | Description |
---|---|---|
id | integer | Id of the existing project. |
name | string | Name of the project |
Response fields
Field | Type | Description |
---|---|---|
success | boolean | Indicates request status |
Projects | array | Details of the created project |
Project fields
See project fields
Links fields and values
See link fields
Delete
HTTP Request
DELETE https://platform-api.productsup.io/platform/v2/projects/<projectId>
URL parameters
Field | Type | Description |
---|---|---|
projectId | integer | Project to delete |
Response body fields
Field | Type | Description |
---|---|---|
success | boolean | Indicates the success of the action |
curl -X DELETE https://platform-api.productsup.io/platform/v2/projects/125
# response:
{"success":true}
<?php
$projectService = new Productsup\Service\Projects($client);
$result = $projectService->delete(125); // id fetched from API
// result is true, if the delete was successful
Sites
Sites are the smallest entity, below projects and have one data source and may have several exports/channels
Get
To list all sites of your account, or only certain sites, you can use get.
<?php
// our php client builds the urls for you, but you have to set the infos to the classes:
$siteService = new \Productsup\Service\Sites($client);
// sending the actual request
$list = $siteService->get();
print_r($list);
// or requesting it by reference/a tag:
$reference = new \Productsup\Platform\Site\Reference();
$reference->setKey('tagname');
$reference->setValue('123abc');
$list = $siteService->setReference($reference);
// or requesting the site by its id:
$list = $siteService->get(123);
/*
result will look like this:
Array
(
[0] => Productsup\Platform\Site Object
(
[id] => 123
[title] => site 1
[created_at] => 2015-01-01 11:22:33
[project_id] => 321
[links:protected] => Array(...)
[reference:protected] =>
)
...
*/
# requesting a list of all your sites
curl https://platform-api.productsup.io/platform/v2/sites
# requesting a list of all your sites within one project
curl https://platform-api.productsup.io/platform/v2/projects/321/sites
# requesting sites by tag
curl https://platform-api.productsup.io/platform/v2/sites/tagname:tagValue
# requesting one site by its ID
curl https://platform-api.productsup.io/platform/v2/sites/123
# response:
{
"success": true,
"Sites": [
{
"id": "123",
"title": "site 1",
"created_at": "2015-01-01 11:22:33",
"project_id": "321",
"links": [...]
},
...
]
}
HTTP Request - All sites for your account
GET https://platform-api.productsup.io/platform/v2/sites
HTTP Request - All sites for a specific project
GET https://platform-api.productsup.io/platform/v2/projects/<projectId>/sites
URL parameters
Field | Type | Description |
---|---|---|
projectId | integer | Project to list sites for |
HTTP Request - Get a site by it’s tag
GET https://platform-api.productsup.io/platform/v2/sites/<tagName>:<tagValue>
URL parameters
Field | Type | Description |
---|---|---|
tagName | string | Name of the tag for the site |
tagValue | string | Value of the tag for the site |
HTTP Request - Get a site by it’s identifier
GET https://platform-api.productsup.io/platform/v2/sites/<siteId>
URL parameters
Field | Type | Description |
---|---|---|
siteId | integer | Site to list |
Response fields
Field | Type | Description |
---|---|---|
success | boolean | Indicates request status |
Sites | array | List of sites |
Site fields
Field | Type | Description |
---|---|---|
id | integer | Site identifier |
title | string | Name of the site |
status | string | List of valid statusses |
project_id | integer | Identifier of the project this site belongs to |
import_schedule | string | Import schedule |
id_column | string | Name of the column that is considered as an identifier |
processing_status | string | Status of the site’s latest job (Running/Done) |
created_at | date | Date of creation |
links | array | List of relevant resources |
Links fields and values
Name | Description |
---|---|
self | Link to current site detail |
tags | Link to a list of tags belonging to the site |
project | Link to project |
Site status information
Value for status | Description |
---|---|
active | The site is fully operational; data can be pushed via the API and the site will import and export |
paused_upload | The site can receive data via the API and import the data; it will however not export data |
disabled | The site will block any data send via the API, neither imports or exports can be done |
Create
To create a new site, you can use a POST request (or the insert method).
curl -d '{"title":"example site","reference":"myReferenceKey:myReference1234", "id_column": "uniqueIdentifier"}' \
https://platform-api.productsup.io/platform/v2/projects/321/sites
# result:
{
"success": true,
"Sites": [{
"id": 125,
"title": "example site",
"created_at": "2015-07-30 12:54:52",
"project_id": 321,
"links": [...]
}]
}
<?php
$SitesService = new \Productsup\Service\Sites($Client);
$project = new \Productsup\Platform\Project();
$project->id = 321;
$SitesService->setProject($project);
$siteObject = new \Productsup\Platform\Site();
$siteObject->title = 'new example site';
$siteObject->id_column = 'uniqueIndetifier';
/* optional
$reference = new \Productsup\Platform\Site\Reference();
$reference->setKey('myReferenceKey');
$reference->setValue('myReference1234');
$siteObject->addReference($reference);
*/
$result = $SitesService->insert($siteObject);
print_r($result);
/**
result:
Productsup\Platform\Site Object
(
[id] => 125
[title] => new example site
[created_at] => 2015-07-30 12:54:52
[project_id] => 321
)
*/
HTTP Request
POST https://platform-api.productsup.io/platform/v2/sites
POST https://platform-api.productsup.io/platform/v2/projects/<projectId>/sites
URL parameters
Field | Type | Description |
---|---|---|
projectId | integer | Project under which to add the site. Required unless set in request body. |
HTTP headers
Name | Value |
---|---|
Content-Type | application/json |
The data to be inserted has to be provided as a JSON-Object.
Request body fields
Field | Type | Description |
---|---|---|
title | string | Name of the site |
reference | string | Textual site reference, consisting of tagName and tagValue |
project_id | integer | Project under which to add the site. Required unless provided in URL. |
id_column | string | ID column which is being used as an identifier when importing data to the platform. |
status | string | List of valid statusses |
id
and created_at
have to be empty, otherwise the values get overwritten, or the request may result in an error.
Field id_column
is optional and only needed if the site identifier is not "id"
, by default not passing an id_column
will set the identifier to "id"
. If an empty value ""
is given for the id_column
then the identifier column will not be set.
Response fields
See response fields
Site fields
See site fields
Links fields and values
See link fields
Edit
To edit an existing site, you can use a PUT request as follows:
curl -d '{"id": "1", "project_id": "1", "title":"My test site", "import_schedule": "TZ=Europe/Berlin\nH 2,6,19,22 * * 2,4,6"}' \
https://platform-api.productsup.io/platform/v2/projects/1/sites/1
# result:
{
"success": true,
"Sites": [{
"id": "1",
"title": "My test site",
"created_at": "2015-07-30 12:54:52",
"project_id": "1",
"import_schedule": "TZ=Europe\/Berlin\nH 2,6,19,22 * * 2,4,6\nH * * * *",
"links": [...]
}]
}
HTTP Request
PUT https://platform-api.productsup.io/platform/v2/sites/<siteId>
PUT https://platform-api.productsup.io/platform/v2/projects/<projectId>/sites/<siteId>
URL parameters
Field | Type | Description |
---|---|---|
projectId | integer | Project under which to edit the site. |
siteId | integer | Existing site that is being edited. |
HTTP headers
Name | Value |
---|---|
Content-Type | application/json |
The data to be inserted has to be provided as a JSON-Object.
Request body fields
Field | Type | Description |
---|---|---|
id | integer | Existing site that will be edited. |
project_id | integer | Project under which to edit the site. |
title | string | Name of the site |
id_column | string | ID column which is being used as an identifier when importing data to the platform. |
status | string | List of valid statusses |
import_schedule | string | A cron entry that sets the scheduling for data import. |
The field id_column
is optional and only needed if the site identifier needs to be set. If an empty value ""
is
given for the id_column
then the identifier column will not be set.
Cron entries format consists of a timezone and schedule format. All PHP timezones are supported. A newline should be used as separator between the timezone and each schedule.
For example:
TZ=Europe/Berlin
H 2,6,19,22 * * 2,4,6
H * * * *
1 3,8,21 */2 * *
For the minute entry we accept a value H
which indicates a random minute will
be used. This has our preference, since it prevents many jobs starting at the
exact same time. But it can be overridden if that is required.
Response fields
See response fields
Site fields
See site fields
Links fields and values
See link fields
Delete
HTTP Request
DELETE https://platform-api.productsup.io/platform/v2/sites/<siteId>
URL parameters
Field | Type | Description |
---|---|---|
siteId | integer | Site to delete |
Response body fields
Field | Type | Description |
---|---|---|
success | boolean | Indicates the success of the action |
curl -X DELETE https://platform-api.productsup.io/platform/v2/sites/125
# response:
{"success":true}
<?php
$SitesService = new Productsup\Service\Sites($Client);
$result = $siteService->delete(125); // id fetched from API
// result is true, if the delete was successful
Site Errors
With site errors, you can see the last errors or add new custom errors for a site.
Get
To list errors for one site, you can use get. See Sites for how to identify sites.
<?php
$site = new \Productsup\Platform\Site();
$site->id = 123;
$errorService = new \Productsup\Service\Errors($client);
$errorService->setSite($site);
// optional params
$errorService->setParam('pid','abc456def');
$errorService->setParam('limit',1);
$errorService->setParam('offset',2);
$result = $errorService->get();
/*
result will look like this:
Array
(
[0] => Productsup\Platform\Error Object
(
[id] => 123
[pid] => abd456
[error] => 10081
[data] =>
[links:protected] => ...
)
[1] => Productsup\Platform\Error Object
(
[id] => 124
[pid] => 537df1d87c39c
[error] => 10012
[data] => {"FTP Host":"sftp:\/\/example.org","User":"sftpuser"}
[links:protected] => ...
)
...
*/
# requesting all channels of one site
curl https://platform-api.productsup.io/platform/v2/sites/123/errors
# response:
{
"success": true,
"Errors": [
{
"id": "1802017",
"pid": "537cb0659a7dc",
"error": "10012",
"data": "{"FTP Host":"sftp:\/\/example.org","User":"sftpuser"}",
"site_id": "123",
"links": [{...}]
},
....
]
}
HTTP Request
GET https://platform-api.productsup.io/platform/v2/sites/<siteId>/errors
GET https://platform-api.productsup.io/platform/v2/sites/<siteid>/errors?pid=<pid>&limit=<limit>&offset=<offset>
URL parameters
Name | Type | Description |
---|---|---|
siteId | integer | Site to get the errors for |
Optional query parameters
Name | Example | Default | Description |
---|---|---|---|
pid | abc456def |
(latest) | Process id, by default the latest process is shown |
limit | 10 |
50 |
Maximum number of results |
offset | 20 |
0 |
Results begin at this position |
Response fields
Field | Type | Description |
---|---|---|
success | boolean | Indicates request status |
Errors | array | List of errors |
Error fields
Field | Type | Description |
---|---|---|
id | integer | Internal identifier |
pid | string | Process identifier |
error | integer | Error identifier |
data | array | Additional information about the error |
site_id | integer | Site identifier |
message | string | End user friendly error message |
links | array | List of relevant resources |
Links fields and values
Name | Description |
---|---|
self | Link to the error endpoint |
Create
To create a new error (information) for one site, you can use a POST request (or the insert method).
curl -d '{"pid":"abd456def","error":123,"data":{"foo":"bar"}}' \
https://platform-api.productsup.io/platform/v2/sites/123/errors
# result:
{
"success": true,
"Errors": [{
"id": 42,
"pid": "abc456def",
"error": 123,
"data": "{\"foo\":\"bar\"}",
"site_id": 123,
"links": [...]
}]
}
<?php
$site = new \Productsup\Platform\Site();
$site->id = 123;
$errorService = new \Productsup\Service\Errors($client);
$errorService->setSite($site);
$result = $errorService->get();
$error = new \Productsup\Platform\Error();
$error->pid = 'something';
$error->error = 123;
$error->data = ['foo' => 'bar'];
$result = $errorService->insert($error);
print_r($result);
/**
Productsup\Platform\Error Object
(
[id] => 42
[pid] => something
[error] => 123
[data] => {"foo":"bar"}
[links:protected] => ...
)
*/
HTTP Request
POST https://platform-api.productsup.io/platform/v2/sites/<siteId>/errors
URL parameters
Name | Type | Description |
---|---|---|
siteId | integer | Site to which the error will be added |
HTTP headers
Name | Value |
---|---|
Content-Type | application/json |
The data to be inserted has to be provided as a JSON-Object.
Request body parameters
Field | Type | Description |
---|---|---|
pid | string | Process identifier |
error | integer | Error id, this should be a valid identifier according to our error codes |
data | array | Additional information about the error |
Response fields
See response fields
Error fields
See error fields
Link fields and values
See link fields
Import History
With the endpoint import history, you may query for meta information about the last imports.
Get
Lists the information about your last imports.
<?php
$reference = new \Productsup\Platform\Site\Reference();
$reference->setKey(\Productsup\Platform\Site\Reference::REFERENCE_SITE);
$reference->setValue(123); // site id
$importHistory = new \Productsup\Service\ImportHistory($client);
$importHistory->setReference($reference);
$history = $importHistory->get();
print_r($history);
/*
result will look like this:
Array
(
[0] => Productsup\Platform\ImportHistory Object
(
[id] => 1111111111
[site_id] => 123
[import_time] => 2015-07-15 15:02:11
[product_count] => 18370
[links:protected] => Array
(
[site] => http://api.productsup.io/platform/v2/sites/123
)
[reference:protected] =>
)
)
*/
# requesting one site by its ID
curl https://platform-api.productsup.io/platform/v2/sites/123/importhistory
# response:
{
"success": true,
"Importhistory": [
{
"id": "11111111",
"site_id": 1234,
"import_time": "2015-01-01 11:22:33",
"product_count": "18370",
"links": [...]
},
...
]
}
HTTP Request
GET https://platform-api.productsup.io/platform/v2/sites/<siteId>/importhistory
URL parameters
Field | Type | Description |
---|---|---|
siteId | integer | Site to list import history for |
Response fields
Field | Type | Description |
---|---|---|
success | boolean | Indicates request status |
Sites | array | List of imports |
Site fields
Field | Type | Description |
---|---|---|
id | integer | Internal ID |
site_id | integer | ID of the referenced site |
import_time | date | Date of the import |
product_count | integer | Total amount of imported products |
links | array | List of relevant resources |
Links fields and values
Name | Description |
---|---|
site | Link to site |
Channels
Channels are targets of the data (like “Google Shopping”, Amazon,..)
Get
To list all channels of your account, or only certain sites, you can use get.
<?php
$reference = new \Productsup\Platform\Site\Reference();
$reference->setKey(\Productsup\Platform\Site\Reference::REFERENCE_SITE);
$reference->setValue(123); // site id
$channelService = new \Productsup\Service\Channels($client);
$channelService->setReference($reference);
$channels = $channelService->get();
/*
result will look like this:
Array
(
[0] => Productsup\Platform\Channel Object
(
[id] => 321
[site_id] => 123
[name] => Criteo DE
[export_name] => Criteo
[history] =>
[links:protected] => ...
)
[1] => Productsup\Platform\Channel Object
(
[id] => 543
[site_id] => 123
[name] => Zanox DE
[export_name] => Zanox
[history] =>
[links:protected] => ...
)
...
*/
# requesting all channels of one site
curl https://platform-api.productsup.io/platform/v2/sites/123/channels
# requesting a specific channel
curl https://platform-api.productsup.io/platform/v2/sites/123/channels/321
# response:
{
"success": true,
"Channels": [
{
"id": "321",
"site_id": "123",
"channel_id": "111",
"name": "Criteo DE",
"export_name": "Criteo",
"links": [...]
},
{
"id": "541",
"site_id": "123",
"channel_id": "222",
"name": "Zanox DE",
"export_name": "FZanox",
"links": [...]
}
]
}
HTTP Request - Get all channels for a site
GET https://platform-api.productsup.io/platform/v2/sites/<siteId>/channels
URL parameters
Field | Type | Description |
---|---|---|
siteId | integer | Site to list channels for |
HTTP Request - Get a channel by it’s identifier
GET https://platform-api.productsup.io/platform/v2/sites/<siteId>/channels/<channelId>
URL parameters
Field | Type | Description |
---|---|---|
siteId | integer | Site under which channel exists |
channelId | integer | Channel to get; use site channel relation id |
Response fields
Field | Type | Description |
---|---|---|
success | boolean | Indicates request status |
Channels | array | List of channels |
Channel fields
Field | Type | Description |
---|---|---|
id | integer | ID of the site channel relation |
site_id | integer | ID of the referenced site |
channel_id | integer | ID of the channel |
name | string | Name of the export you provided while creating the channel |
export_name | string | Generic name of the export in the productsup system |
links | array | List of relevant resources |
Links fields and values
Name | Description |
---|---|
self | Link to channel detail |
site | Link to site |
Channel History
With the channel history, you can get information on the last exports of a channel
Get
To list the history, you can use get.
<?php
$reference = new \Productsup\Platform\Site\Reference();
$reference->setKey(\Productsup\Platform\Site\Reference::REFERENCE_SITE);
$reference->setValue(123); // site id
$channelService = new \Productsup\Service\Channels($client);
$channelService->setReference($reference);
$channels = $channelService->get(321,'history');
/*
result will look like this:
Array
(
[0] => Productsup\Platform\Channel Object
(
[id] => 2116
[site_id] => 368693
[name] => Criteo DE
[export_name] => FusePump Criteo
[history] => Array
(
[0] => Array
(
[id] => 25190
[site_id] => 368693
[site_channel_id] => 2116
[export_time] => 2015-08-27 16:22:57
[export_start] => 2015-08-27 16:22:55
[product_count] => 20562
[product_count_now] => 20562
[product_count_previous] => 0
[process_status] => 0
[pid] => 55df182bde8e8
[product_count_new] => 0
[product_count_modified] => 0
[product_count_deleted] => 0
[product_count_unchanged] => 0
[uploaded] => 0
)
[1] => Array
(
[id] => 25163
[site_id] => 368693
[site_channel_id] => 2116
[export_time] => 2015-08-27 15:48:03
[export_start] => 2015-08-27 15:48:02
[product_count] => 20562
[product_count_now] => 20562
[product_count_previous] => 0
[process_status] => 0
[pid] => 55df10f8c89d2
[product_count_new] => 0
[product_count_modified] => 0
[product_count_deleted] => 0
[product_count_unchanged] => 0
[uploaded] => 0
)
...
*/
# requesting the history of one channel
curl https://platform-api.productsup.io/platform/v2/sites/123/channels/321/history
# response:
{
"success": true,
"Channels": [
{
"id": "321",
"site_id": "123",
"channel_id": "1",
"name": "Google Merchant Center DE",
"export_name": "Google Merchant Center",
"links": [...],
"history": [
{
"id": "333",
"site_id": "123",
"site_channel_id": "444",
"export_time": "2015-09-30 10:18:56",
"export_start": "2015-09-30 10:18:54",
"product_count": "18697",
"product_count_now": "20904",
"product_count_previous": "0",
"process_status": "0",
"pid": "560b96899e334",
"product_count_new": "0",
"product_count_modified": "0",
"product_count_deleted": "0",
"product_count_unchanged": "0",
"uploaded": "0"
},
...
]
}
]
}
HTTP Request
GET https://platform-api.productsup.io/platform/v2/sites/<siteId>/channels/<channelId>/history
URL parameters
Field | Type | Description |
---|---|---|
siteId | integer | Site under which channel exists |
channelId | integer | Channel to get; use site channel relation id |
Response fields
Field | Type | Description |
---|---|---|
success | boolean | Indicates request status |
Channels | array | List of channels |
Channel fields
Field | Type | Description |
---|---|---|
id | integer | ID of the site channel relation |
site_id | integer | ID of the referenced site |
channel_id | integer | ID of the channel |
name | string | Name of the export you provided while creating the channel |
export_name | string | Generic name of the export in the productsup system |
links | array | List of relevant resources |
history | array | List of channel history |
Links fields and values
Name | Description |
---|---|
self | Link to channel detail |
site | Link to site |
History fields
Field | Type | Description |
---|---|---|
id | integer | Internal identifier |
site_id | integer | Identifier of the referenced site |
site_channel_id | string | Internal id for the combination of an Export and Site |
export_time | dateTime | Time when the process was finished |
export_start | dateTime | Time when the process was started |
product_count | integer | Number of products exported |
pid | string | Internal identifier for the process |
product_count_new | integer | Number of new products (only for delta exports) |
product_count_modified | integer | Number of updated products (only for delta exports) |
product_count_deleted | integer | Number of deleted products (only for delta exports) |
product_count_unchanged | integer | Number of unchanged products (only for delta exports) |
uploaded | integer | Indicator if the export was uploaded to it’s destination |
Product Data (Write)
Uploading
curl --header 'Content-Type: application/json' -d '[{
"id": 123,
"title": "test title",
"price": 1.23
}, {
"id": 124,
"title": "next title",
"price": 3.21,
"shipping": "0.99"
}]'
https://platform-api.productsup.io/platform/v2/sites/Identifier:123/products/md5string32chars/upload
<?php
// our php client builds the urls for you, but you have to set the info in the classes:
$ProductService = new Productsup\Service\ProductData($Client);
$Reference = new Productsup\Platform\Site\Reference();
/**
* You have to specify the site the products belong to.
* This is done by references to the site.
**/
// In case you have a productsup site id, you can pass it like this:
$Reference->setKey($Reference::REFERENCE_SITE);
$Reference->setValue(123); // Site ID
// In case you have a custom reference, you can use the follow logic
$Reference->setKey($siteTagName);
$Reference->setValue($siteTagValue);
// Assign the reference to the endpoint class
$ProductService->setReference($Reference);
// Actual creating of upload data
$ProductService->insert(array(
'id' => 123,
'price' => 1.23,
'description' => 'test title',
)
);
$ProductService->insert(array(
'id' => 124,
'price' => 3.21,
'description' => 'next title',
'shipping' => 0.99
)
);
Uploading to the API works via batches. A batch is a collection of products, potentially delivered by multiple requests. The batch can, once all product data is delivered, be committed or discarded.
HTTP Request
POST https://platform-api.productsup.io/platform/v2/sites/<siteIdentifier>/products/<batchId>/upload
URL parameters
Field | Type | Description |
---|---|---|
siteIdentifier | mixed | Either a siteId or siteTags |
batchId | string (32 characters) | Any sequence of characters which indicate a unique batch. It should be exactly 32 characters long. A possible idea is to generate a unique number and then hash it with the md5 algorithm. |
Site identifier values
Type | Data type | Description |
---|---|---|
siteId | integer | Using a site identifier (numeric value) |
siteTags | string (format: tagName:tagValue ) |
A combination of a tag name and tag value for a site, see also site tags |
HTTP headers
Name | Value |
---|---|
Content-Type | application/json |
The data to be inserted has to be provided as a JSON-Object.
Product format
When uploading products the following rules apply:
- Columns can be named freely, but ideally should be in lowercase and not contain any spaces or special characters. Our technology relies on SQLite databases so that’s where our limits lie.
- When columns are added:
- Existing data will have an empty value for these columns.
- When columns are not uploaded (removed):
- If any existing data has a value for that column, it will remain and the new data will just have an empty value.
- If no existing data has a value, that column will be automatically removed.
- The amount of products per upload request is limited to 10000. We recommend sending multiple upload requests with the same batch id, if you reach this limit.
A list of example product data:
id | title | price | shipping | pup:isdeleted |
---|---|---|---|---|
123 | my first product | 1.23 | ||
124 | my second product | 3.21 | 0.99 | |
125 | my other product | 5.99 | - | 1 |
126 | another product of mine | 0.50 | - | -1 |
Unique identifier id
The id
column is required and should contain a unique value to represent
your product. If a duplicate value for the id
is present, we will import the
last product with the duplicate value.
When sending updates or in case a product needs to be deleted, the correct id
should be used.
Deleting products
# Soft delete
curl -d '[{
"id": 124,
"pup:isdeleted": 1
}]'
https://platform-api.productsup.io/platform/v2/sites/Identifier:123/products/md5string32chars/upload
# Hard delete
curl -d '[{
"id": 124,
"pup:isdeleted": -1
}]'
https://platform-api.productsup.io/platform/v2/sites/Identifier:123/products/md5string32chars/upload
<?php
// Soft delete
$ProductService->delete(array(
'id' => 123,
)
);
// Hard delete
$ProductService->insert(array(
'id' => 123,
'pup:isdeleted' => -1
)
);
Deleting specific products can be achieved by adding the column pup:isdeleted. Depending on it’s value a soft or a hard delete can be triggered. A soft delete marks the product as deleted, but it will still show up in the Dataview of the Platform. When doing a hard delete, the product will not be imported and will not be visible in the platform.
This applies to both full and delta uploads. Sending a full upload will also override all data, so it’s not needed to remove products beforehand. Additionally it’s also possible to clear your api data by sending just a dummy product, marking it for a hard delete and doing a full commit.
Value for pup:isdeleted | Description |
---|---|
1 | Soft delete, product will be present in platform, but marked |
-1 | Hard delete, product will not be present in platform |
0 | No delete, product will be present in platform |
Response status codes
Code | Message | Details |
---|---|---|
200 | N/A | The request was successful |
423 | Request was blocked because another data operation is already running | Concurrent uploads to the same batch id are not allowed. This needs to be done consecutively. |
Committing
curl --header 'Content-Type: application/json' -d '{"type":"full", "automatic_import":true}'
https://platform-api.productsup.io/platform/v2/sites/Identifier:123/products/md5string32chars/commit
<?php
$productsService->setImportType(\Productsup\Service\ProductData::TYPE_DELTA);
// OR
$productsService->setImportType(\Productsup\Service\ProductData::TYPE_FULL);
// note: if you do not define the type the "full" is used as default
$result = $ProductService->commit();
Once you are finished with uploading all product data, you can start the processing of the data. This is done batch by batch, so it’s advisable to use one batch ID per upload (even if it consists of multiple upload requests).
HTTP Request
POST https://platform-api.productsup.io/platform/v2/sites/<siteIdentifier>/products/<batchId>/commit
URL parameters
See url parameters
HTTP Headers
See HTTP headers
Request body fields
Field | Type | Description |
---|---|---|
type | string | Type of upload |
automatic_import | boolean | Whether the automatic triggering of an import & export should be scheduled. |
Automatic import & export scheduling
The default behaviour is that 20 minutes after a commit we schedule a full process (import and export). Every new commit within this time frame resets the time to 20 minutes after that commit. After the last commit the process will then be triggered, this has been default behaviour. Therefore we recommend setting the value of automatic_import to true.
Via the process endpoint it’s possible to programmatically trigger a process and be more specific of the type. When implementing this, we recommend a value of false for the key automaticimport_.
Type values
Value | Description |
---|---|
full | The current upload are all products for the given site, all data from past uploads will be removed. |
delta | The current upload is only a part of all your products. Use this in case you plan to send incremental uploads. |
Values should be set accordingly:
Commit value | Product Update Mode value |
---|---|
full | replace |
delta | update |
Response status codes
Code | Message | Details |
---|---|---|
200 | N/A | The request was successful |
423 | Request was blocked because another data operation is already running | Concurrent commits are not allowed, since it’s a one time operation for a batch ID. So once a commit starts, we lock it until a response is given. |
Discarding
curl https://platform-api.productsup.io/platform/v2/sites/Identifier:123/products/md5string32chars/discard
<?php
$result = $ProductService->discard();
If something has gone wrong during the upload process, it is possible to cancel the whole batch. This allows you be more strict with your data integrity. This is achieved by calling the discard endpoint on a batch id.
HTTP Request
POST https://platform-api.productsup.io/platform/v2/sites/<siteIdentifier>/products/<batchId>/discard
URL parameters
See url parameters
HTTP Headers
See HTTP headers
Deleting
curl --header 'Content-Type: application/json'
--request DELETE 'http://platform-api.productsup.io/platform/v2/sites/Identifier:123/products'
It’s possible to delete all product data stored in the Platform API by sending a DELETE request. Once you have send the request on the next run it will import 0 products and clear all stored data. This also allows you to start sending new requests with data after the delete request.
Product Data (Read)
Get
curl https://platform-api.productsup.io/product/v2/site/123/stage/intermediate/
?filter=id+%3C%3E+%27%27
&limit=5000
&offset=0
&fields%5B0%5D=id
&fields%5B1%5D=gtin
&hidden=0
{
"success": true,
"products": [{
"id": "123",
"gtin": "42"
}]
}
<?php
$productData = new \Productsup\Service\ProductData($client);
$reference = new \Productsup\Platform\Site\Reference();
$reference->setKey(\Productsup\Platform\Site\Reference::REFERENCE_SITE);
$reference->setValue(123); // site id
$productData->setReference($reference);
$query = new \Productsup\Query();
$query->fields = array(
'id',
'gtin'
);
$query->filter = "id <> ''";
$query->limit = 5000;
$query->offset = 0;
$products = $productData->get(
\Productsup\Service\ProductData::STAGE_INTERMEDIATE,
0,
$query
);
result:
Array
(
[success] => 1
[products] => Array
(
[0] => Array
(
[id] => 123
[gtin] => 42
)
)
)
HTTP Request - Get product data
GET https://platform-api.productsup.io/product/v2/site/<siteId>/stage/<stageName>/<stageId>?limit=<limit>&ofset=<offset>&fields=<fields>&hidden=<hidden>&filter=<filter>
URL parameters
Field | Type | Description |
---|---|---|
siteId | integer | Site identifier |
stageName | integer | Stage name |
stageId | integer | Stage id, set to 0 for stages import and intermediate |
Stage names
The table below represents the processing stages in which the product data is available. Each stage can add transformations and filters on product data. Export and channel are quite similar in their use. However we no longer use new exports, we only create new channels.
Name | Stage description |
---|---|
import | Directly after importing the product data from an API upload |
intermediate | Generic transformations, always required for all product data, may be applied |
export | Specific export transformations are applied |
channel | Specific channel transformations are applied |
Query fields
The query fields allow a more precise control over the product data being returned. Certain requirements and filters can be set, as well as functionality to paginate through long result sets.
Name | Type | Default | Description |
---|---|---|---|
limit | integer | 5000 | Maximum number of products |
offset | integer | 0 | Offset for querying products |
fields | array | all fields | Array of fields to select |
hidden | numeric boolean (0 or 1) | 0 | If set to 1 also hidden fields (fields that are not exported) are included |
filter | string | none | Condition to filter for, in SQL syntax |
Response body fields
Field | Type | Description |
---|---|---|
success | boolean | Indicates request status |
products | array | List of product data, at least containing and id column |
<?php
// see Product Data write for more info
$ProductService = new Productsup\Service\ProductData($Client);
$Reference = new Productsup\Platform\Site\Reference();
$productData = new \Productsup\Service\ProductData($client);
$reference = new \Productsup\Platform\Site\Reference();
$reference->setKey(\Productsup\Platform\Site\Reference::REFERENCE_SITE);
$reference->setValue(123); // site id
$productData->setReference($reference);
$metaData = $productData->getProperties(\Productsup\Service\ProductData::STAGE_INTERMEDIATE,0);
/** response:
Array (
[success] => 1
[columns] => Array
(
[0] => id
[1] => gtin
[2] => price
...
)
[products] => 42
)
*/
curl https://platform-api.productsup.io/product/v2/site/123/stage/intermediate/0/properties/
result:
{
"success": true,
"columns": ["id", "gtin", "price", ...],
"products": 42
}
HTTP Request - Get product data properties
GET https://platform-api.productsup.io/product/v2/site/<siteId>/stage/<stageName>/<stageId>/properties
URL parameters
See url parameters
Response body fields
Field | Type | Description |
---|---|---|
success | boolean | Indicates request status |
columns | array | Columns of the data set |
products | integer | Total amount of products in data set |
Response status codes
Code | Message | Details |
---|---|---|
200 | N/A | The process was successfully called or scheduled |
429 | Too many attempts | The API is rate limiting your request. You can do a maximum of 60 requests per minute. |
We can offer a this product read endpoint, but due to our infrastructure setup it’s not meant as a high-performing endpoint. We currently do not offer a high-performance product read endpoint. Depending on the complexity of the filter, the database size and amount of columns, requests can sometimes take up to minutes or more. In these cases we expect you to not send concurrent requests and only send then consecutively.
Process
Process can be used to trigger processing actions on your site. You can can use the Platform API Client with the Process object or make the call to the endpoint yourself.
Post
Trigger a processing action on your site.
<?php
$processAction = new Productsup\Service\Process($Client);
// Only required if not setting the site_id property for the model
$reference = new \Productsup\Platform\Site\Reference();
$reference->setKey($reference::REFERENCE_SITE);
$reference->setValue(123456789);
$processModel = new Process();
$processModel->action = 'import';
// Only required for types 'export' or 'channel'
// $processModel->action_id = 1234567890;
$processModel->addReference($reference);
// Instead of a reference you can also set the site id manually
// $processModel->site_id = 123457890;
$result = $processAction->post($processModel);
var_dump($result);
/*
result will look like this:
bool(true)
*/
# Triggering an action on your site
curl -X POST H "Content-Type:application/json" -d '{"action": "import"}' https://platform-api.productsup.io/platform/v2/process/<siteId>
{
"success": true,
"process_id": "<uuid-32-formatted-string>"
}
HTTP Request
POST https://platform-api.productsup.io/platform/v2/process/<siteId>
URL parameters
Field | Type | Description |
---|---|---|
siteId | integer | Site you want to trigger processing for |
HTTP headers
Name | Value |
---|---|
Content-Type | application/json |
The data to be inserted has to be provided as a JSON-Object.
Request body fields
Field | Type | Description |
---|---|---|
action | string | Action value |
id | integer | Export or channel id, only required for action types export and channel |
batch_id | string | An id of a batch that was recently committed. |
Passing a “batch_id” will trigger the process once the batch’s data is ready for an import.
Action value explanation
Action value | Description |
---|---|
import | Trigger an import on the site |
export | Trigger an export, export id is required (old style of exporting) |
channel | Trigger a channel, channel id is required (new style of exporting) |
export-all | Trigger all exports and channels |
all | Trigger an import, all exports and channels |
Response body fields
Field | Type | Description |
---|---|---|
success | boolean | Indicates status of job scheduling on the Jenkins server |
process_id | string | Process Identifier aka PID (format: UUID 32 - only on success) |
message | string | On failure this field will indicate why the request failed |
Response status codes
Code | Message | Details |
---|---|---|
200 | N/A | The process was successfully called or scheduled |
429 | Too many attempts | The API is rate limiting your request. You can do 1 request per site per 5 minutes. |
429 | Cannot trigger a new process, a process is already in the current queue. | This indicates that our job queue for this site still has a job that is queued. Retrying in this case makes little sense, since the current job in the queue needs to be started before another job can be queued or ran. |
500 | Could not trigger job |
A previous request for this site has locked any further requests. The lock is released once the previous request has returned a response. |
500 | Error occurred while interacting with the job server | This indicates a problem with our job running infrastructure. A retry can be done to ensure it wasn’t a single occurrence. However continuously retrying on this error, just causes more problem. |
Status
The status endpoint can be used to get a status of a Process Identifier (PID) for a specific site. A valid pid must always be given as secondary parameter . When calling the Process endpoint, it will return a valid pid. If an invalid PID will be given, the sites status will always be queued.
Get
Get the status of PID for a site
curl -i -L -X GET \
'https://platform-api.productsup.io/platform/v2/sites/<siteId>/status/<pid>'
{
"success": true,
"status": "failed",
"links":[
{
# Only available when status equals failed
"errors": "http://platform-api.productsup.io/platform/v2/sites/<siteId>/errors?pid=<pid>"
},
{
"self": "http://platform-api.productsup.io/platform/v2/sites/<siteId>/status/<pid>"
}
]
}
HTTP Request
GET https://platform-api.productsup.io/platform/v2/sites/<siteId>/status/<pid>
URL parameters
Field | Type | Description |
---|---|---|
siteId | integer | Site to which the PID belongs |
pid | string | The PID you want to check the status of |
Response body fields
Field | Type | Description |
---|---|---|
success | boolean | Indicates status of the request |
status | string | Indicates the status of the pid |
links | array | List of links, to resource itself and error resource (if status equals failed) |
Status value explanation
Status value | Description |
---|---|
queued | Site is queued (default when PID is valid, but not yet visible) |
running | Site is being processed |
success | Site has run, no errors found |
failed | Site has run, but errors were found |
API Errors
The API follows HTTP Status Codes for error handling. As a body again JSON is returned. The “message” will provide more information about the specific error.
The API can return the following status codes:
# example error response:
{
"success": false,
"message": "Forbidden, your auth token seems to be invalid"
}
<?php
try {
// code that might result in an error from the API
} catch (\Productsup\Exceptions\ServerException $e) {
// A exception at the API Server happened, should not happen but may be caused by a short down time
// You may want to retry it later, if you keep getting this kind of exceptions please notice us.
throw new Exception('Error at the productsup API, retry later');
} catch (\Productsup\Exceptions\ClientException $e) {
// Most likely some of the data you provided was malformed
// The error codes follow http status codes, @see http://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_Error
// The message may give more information on what was wrong:
echo $e->getCode().' '.$e->getMessage();
} catch (\Exception $e) {
// Exceptions not within the Productsup namespace are not thrown by the client, so these exceptions were most likely
// thrown from your application or another 3rd party application
// however, if you don't catch Productsup exceptions explicitly, you can catch them all like this
echo $e->getCode().' '.$e->getMessage();
throw $e;
}
Error Code | Meaning |
---|---|
400 | Bad Request – Your request was malformed |
401 | Unauthorized – Your API key is wrong |
403 | Forbidden – The entity requested is hidden for administrators only |
404 | Not Found – The specified entity could not be found |
405 | Method Not Allowed – You tried to access a entity with an invalid method |
406 | Not Acceptable – You requested a format that isn’t json |
410 | Gone – The entity requested has been removed from our servers |
418 | I’m a teapot |
500 | Internal Server Error – We had a problem with our server. Try again later. |
503 | Service Unavailable – We’re temporarially offline for maintanance. Please try again later. |