Introduction into our APIs

Welcome to the Productsup API documentation space!

We have the following API documentation available for our clients, including a how-to section with documents on different integration possibilities:

• Stream API - High-performance API for product upload and content
  • Product Data write
• Platform API - Account management API
  • Manage projects and sites
  • Get information about previous imports
  • Check errors per site run
  • Find information about exports and their history
  • Check the status of a site
  • Trigger a run for a site
  • Product Data read

Unified authentication

You need different tokens to authenticate with the Platform API and the Stream API. However, some endpoints support unified authentication to simplify API usage. For now, these endpoints are:

• Process endpoint
• Site Stream Data Sources endpoint

In the future, we are planning to unify authentication for further endpoints. Your main contact at Productsup can help you get Stream Platform API access. You can also contact them to create new or additional tokens and revoke old ones.

Status Page

Our status page provides real-time information on system performance and security. You will find live and historical data on system performance. The Status page will also contain messages on any service interruptions.

You can subscribe on the page to updates and receive notifications via your preferred communication channel.

Status page

Sunset FAQ - Platform API data write endpoints

1. When do you plan to sunset the Platform API? We already sunsetted the Platform API data write endpoints on March 31, 2025. The Platform API is still available for account management and the Stream API is available for product data uploads for new integrations.

2. Why do you plan to sunset the Platform API? The Stream API is our latest content upload API that provides enhanced speed and efficiency for data uploads compared to the Platform API upload endpoints. We want to phase out the use of the Platform API data write endpoints to provide our customers with a better content upload experience and reduce API maintenance efforts.

3. What is the Stream API? The Stream API is a high-performance data upload API designed to handle a high throughput or a high number of items with product changes. See Stream API for more information on the capabilities of this API and Introduction to Streams to create your first Stream and upload your products to Productsup.

4. What do I need to do to migrate to the Stream API? You need to implement the Stream API content upload endpoints and phase out the respective Platform API endpoints. If you have any questions or need assistance during the transition, you can contact support@productsup.com.

5. Can I get a token for the Stream API? Yes, you can get a Stream API token for your account. You can request the token by reaching out to your main point of contact at Productsup or contacting support@productsup.com. See Stream API Authentication for more information.

6. How do I retrieve data from the Stream API? The Stream API does not support reading product data. You can still do it via the Platform API data read endpoints.

7. What do I need to know about the Stream API performance? The Stream API supports two Stream types. A suitable Stream type depends on your exact scenario. In general, we recommend using chunked streams as they benefit most from the performance boost of the Stream API. You can test different Stream types in a site within your sandbox project to better understand the performance impact. See Which is the best Stream type for your use case? for a more comprehensive guide on choosing a suitable Stream type.

8. Do you need anything from me to help with the migration process? If you reach out to us for help in the migration process, we would like to understand your specific needs to better support you. You can consider the answers to these three default questions and provide us with the related details when reaching out:

   1. How many products in total do you have in your product catalog?
   2. How many attributes does your product catalog have on average?
   3. How often do you make changes in your product catalog? Hourly or daily?

How-to guides

In this section, you can find different guides for integrating with our APIs.

Introduction to Streams

In this guide, you can learn about our Stream API and get the guidelines for the basic integration.

Prerequisites

• Read Authentication.
• Get a Personal Access Token.
• Get familiar with the terminology in our Glossary.
• Create a site for this tutorial in the Productsup platform.
• Have an HTTP client at hand.
  • Our tutorial provides cURL commands you can execute in the terminal or also easily import into Postman.

Get started

Each set of instructions matches with a request and response on the right.

Step 1: Create your first stream

Request 1: Create your first stream

curl --location --request POST 'https://stream-api.productsup.com/streams' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Accept: application/vnd.api+json' \
--data-raw '{
  "data": {
    "type": "stream",
    "attributes": {
      "name": "Getting started tutorial My first stream",
      "type": "chunked"
    }
  }
}'

Response 1: Create your first stream

{
  "data": {
    "type": "stream",
    "id": "<stream_id>",
    "attributes": {
      "name": "Getting started tutorial My first stream",
      "type": "chunked",
      "createdAt": "2022-11-23T18:07:45+01:00",
      "updatedAt": "2022-11-23T18:07:45+01:00"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "<account_id>"
        }
      }
    }
  }
 }

In the first request on the right, you can see how to create a Stream via our Stream API: 1. If needed, change the value of the name attribute. 2. Leave the type attribute chunked for the tutorial. The chunked type is the default type. See Stream types for more information.

In the response, you can see the values instead of the placeholders <stream_id> and <account_id>

Step 2: List your Streams

Request 2: List your Streams

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

Response 2: List your streams

{
  "data": {
    "type": "stream",
    "id": "<stream_id>",
    "attributes": {
      "name": "Getting started tutorial My first stream",
      "type": "chunked",
      "createdAt": "2022-11-23T18:07:45+01:00",
      "updatedAt": "2022-11-23T18:07:45+01:00"
     },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "<account_id>"
        }
      }
    }
  }
}

After creating a Stream in Step 1, you can see which Streams are available in your account. We can list all Streams using the example request on the right. If you already have some Streams in your account, the response also lists them.

See Listing Streams for more information about pagination or listing individual Streams.

Step 3: Upload data to your Stream

Request 3: Upload your products in NDJSON format

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

Response 3: Upload your products in NDJSON format

{
  "data": {
    "type": "batch",
    "id": "<batch_id>",
    "attributes": {
      "status": "uploaded",
      "errorCount": 1,
      "stages": {
        "upload": {
          "completedAt": "2022-11-25T15:40:10+01:00",
          "status": "warning",
          "successCount": 2,
          "errorCount": 1,
          "errors": [
            {
              "message": "Syntax error",
              "occurrences": 1,
              "example": {
                "lineNumber": 2,
                "value": "{\"id\":\"475-SHIRT-XL\",\"name\":\"Product 2\",\"company\":\"ACME Corp.\",\"price\":15\", \"size\":\"XL\"}"
              }
            }
          ]
        },
        "processing": null
      }
    }
  },
  "relationships": {
    "stream": {
      "data": {
        "type": "stream",
        "id": "<stream_id>"
      }
    }
  }
}

In this step, upload three products to your newly created Stream. For the chunked Stream, the product data should use the NDJSON format. Copy the request as in the example on the right. There is a syntax error in the request body, which is a part of the tutorial.

Replace the <stream_id>placeholder in the request URL with the Stream ID created in Step 1.

In the response, you can see the details about the status of your upload. The returned id attribute is what we refer to as a Batch ID. It’s a unique reference to your upload. Save the Batch ID in notes for later to get more information about the upload.

This initial response directly reports any validation errors. With the help of thestatus, successCount, and errorCount attributes, you can see if the upload is successful. Since we parse each product individually, partial successful uploads can occur. In Step 6, you can find a detailed explanation.

See Uploading data and API standards.

Step 4: Create a Stream API Data Source

Request 4: Create a Stream API Data Source

curl --location --request POST 'https://platform-api.productsup.io/platform/v2/sites/<site_id>/streams' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "import_type": 1,
  "description": "Stream API Tutorial - First Stream API Data Source",
  "stream_id": <stream_id>,
  "status": "active"
}'

Response 4: Create a Stream API Data Source

{
  "success": true,
  "Sources": [
    {
      "id": <data_source_id>,
      "site_id": <site_id>,
      "description": "Stream API Tutorial - First Stream API Data Source",
      "source": "",
      "import_type": 1,
      "import_id": 331,
      "status": "active",
      "settings": [
        "stream : <stream_id>"
      ]
    }
  ]
}

If you didn’t create a site in the platform or don’t have access to a created Site, you can skip Steps 4 and 5. They require some interaction with the site.

In this Step, you need to create a Steam API data source. With the help of the data source, the platform can import product data from a Stream into a site.

In the request body, you can change the descriptionattribute. The platform uses the description when listing data sources. You must submit a value to the stream_idattribute to link the site to the Stream.

See Stream API Data Sources for more information.

Step 5: Import your first products

Request 5: Import your first products

curl -X POST https://platform-api.productsup.io/platform/v2/process/<site_id> \
--header "Content-Type:application/json" \
--data-raw'{
  "action": "import"
}'

Response 5: Import your first products

{
  "success": true,
  "process_id": "<process_id>",
  "estimated_duration": 26.105,
  "message": "A new process has been triggered successfully!"
}

After configuring the data source, you can trigger an import process via the Platform API to import the Stream API data into your site. This API call fulfils the same purpose as the Import button in the platform.

Ensure to replace the <site_id> placeholder with the Site ID you are using in this tutorial.

See Processing data for more information.

Step 6: Check the status of your upload

Request 6: Check the status of your upload

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

Response 6: Check the status of your upload

{
  "data": {
    "type": "batch",
    "id": "<batch_id>",
    "attributes": {
      "status": "processed",
      "errorCount": 1,
      "stages": {
        "upload": {
          "completedAt": "2022-11-25T15:40:10+01:00",
          "status": "warning",
          "successCount": 2,
          "errorCount": 1,
          "errors": [
            {
              "message": "Syntax error",
              "occurrences": 1,
              "example": {
                "lineNumber": 2,
                "value": "{\"id\":\"475-SHIRT-XL\",\"name\":\"Product 2\",\"company\":\"ACME Corp.\",\"price\":15\", \"size\":\"XL\"}"
              }
            }
          ]
        },
        "processing": {
          "completedAt": "2022-11-25T15:50:45+01:00",
          "status": "success",
          "successCount": 2,
          "errorCount": 0,
          "errors": []
        }
      }
    },
    "relationships": {
      "stream": {
        "data": {
          "type": "stream",
          "id": "<stream_id>"
        }
      }
    }
  }
}

In this step, you can check your product upload status. The batch status endpoint lets you learn more about your Batch.

Replace the <stream_id> and <batch_id> parameters with the correct values.

In the response, you can see processed in the status attribute for the batch indicating the completion of the batch import to the platform. Previously, in Step 3, you could see the status uploaded that indicated the successful upload of the batch that precedes the import.

A general errorCountattribute lists the total number of errors occurred during both stages. Currently, we have two stages: upload and processing, which contain more information about the events during each stage.

Each stage contains the status attribute indicating the general status of all events during the stage. The succesCount and errorCount attributes contain the number of successfully or unsuccessfully imported products. The errors attribute shows details about the products and the reason for the failure. Only successfully imported products continue to the next stage.

See Batches for more information.

Stream API

Introduction

The Stream API is the latest addition to the APIs Productsup offers to its clients that follows JSON API standards. 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

Status Page

Our status page provides real-time information on system performance and security. You will find live and historical data on system performance. The Status page will also contain messages on any service interruptions.

You can subscribe on the page to updates and receive notifications via your preferred communication channel.

Status page

Authentication

Your Productsup main contact can support with getting Stream API Access. Additionally they can also be contacted for creating new / additional tokens and revoking tokens.

Example authentication request (actually lists streams)

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

Stream API authentication layer is set up based on the concept of PAT. The Productsup 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>

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.

Implementation recommendations

Compression support

Enable gzip compression with the following header

Content-Encoding: gzip

Curl option to enable gzip compression

--header 'Content-Encoding: gzip'

The Stream API supports gzip compression for product uploads to improve performance. Use the Content-Encoding header to specify gzip compression for request payloads. Gzip compression can significantly reduce the payload size, leading to shorter upload times and better performance.

See request body example 6 and 7 to learn how to use gzip compression with a product upload request with the two stream types.

Client header

We recommend using the User-Agent header to send additional information about your integration to the Stream API.

The default format of the User-Agent header looks as follows:

ProductName/Version (System Information) AdditionalDetails

ReactorNetty/1.1.23 Productsup/<INTEGRATION_NAME>
Go-http-client/2.0 Productsup/<INTEGRATION_NAME>
Java/21.0.3 Productsup/<INTEGRATION_NAME>
python-requests/2.31.0 Productsup/<INTEGRATION_NAME>

We recommend adding the integration specific name in the AdditionalDetails section of the User-Agent header. Use the format Productsup/<INTEGRATION_NAME>, where replace <INTEGRATION_NAME> with a desired name. You can append the string to the AdditionalDetails section. See right side for examples.

Streams

This section introduces a concept called Streams. Streams are spaces where we can receive ongoing flows of structured data. Using Streams gives our clients the following possibilities:

• Importing and merging data into a single site from different systems using multiple Streams.
• Importing data from a single Stream into multiple sites in order to reuse the data without uploading it multiple times.
• Allowing the clients to create and merge Streams by themselves.

Stream creation

You can create a maximum of 100 Streams per account. If you need more Streams, reach out to your Client Success Manager.

Stream naming

Stream names should be unique, and their length can be from 3 to 255 characters.

Stream deletion

If you delete a Stream via API, it remains in our system for 7 days. During this period, you can no longer access the data of the deleted Stream, but its name remains reserved. When 7 days have passed, the system completely deletes the Stream, and its name becomes available for new Streams.

Stream formats

Streams support different structured data types. For now, you can use the following formats for the input, but we may add more formats in the future: - Classic JSON - Newline Delimited JSON (NDJSON)

Stream types: Chunked & Referenced

The Stream API supports two Stream types to handle data:

• Chunked
• Referenced

Chunked type

The chunked type provides high throughput and upload speeds.

We maintain the following hard-limits on payloads:

• The maximum size of a single product is 1 MB.
  • The platform automatically rejects any product exceeding 1 MB.
  • You must split large data into chunks of up to 1 MB.
• The total payload size shouldn't exceed 200 MB, either uncompressed or compressed.

The chunked type supports the NDJSON format, which structure lets the platform keep the object deserialization simple and lets process more data.

Referenced type

The referenced type fits the clients who send extremely large quantities of data.

Your request payload sent compressed or uncompressed, can't be greater than 200 MB.

For now, the referenced type supports the classic JSON format only.

Which is the best type for your use case?

Answer the following questions to determine which Stream type is best for you.

• Do you plan to send single product updates? Single product updates mean the platform will send requests for individual products.

  If yes, use the chunked type.

• Do you plan to send frequent product updates? Frequent product updates mean that the platform pushes multiple updates per minute: single-product or batched updates.

  If yes, use the chunked type.

• Do you work with delta-supporting destinations? Some destinations, such as GMC or Facebook Marketplaces, support delta updates.

  If yes, use the chunked type. As we continuously improve our systems, our latest end-to-end delta functionality lets you achieve a near-real-time pipeline and a much smoother integration.

• Do you have a large catalog of over 10 million products and send delta updates?

  If yes, use the chunked type. The platform imports delta changes faster from the chunked Streams.

• Are you going to send only full catalog updates?

  If yes, continue with the following questions to get more precise recommendations:

  • Is your catalog size over 10 million products?

  If yes, use the referenced type. - Do you import your data no more than 1-2 times per day?

  If yes, use the referenced type.

If you don't have a definite answer, please use the chunked type.

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

Example: Create a Stream in your account

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

Example: Create a Stream in another account you have access to

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"
    }
  },
  "relationships": {
    "account": {
      "data": {
        "type": "account",
        "id": ACCOUNT_ID_OF_OTHER_ACCOUNT
      }
    }
  }
}'

When you create a Stream, you have two required attributes and one optional:

• name(required) is the arbitrary value you can use to identify your Stream.
  This attribute is also visible in the UI when you select a Stream in Data Sources.
• type (required) is a Stream type, chunked or referenced.
  See Stream types: chunked and referenced.
• relationships (optional) is an attribute that only lets you determine in which account you want to create a Stream. Apply this attribute only if you have access to multiple accounts. By default, the platform will create a Stream in your first or the only existing account.

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.

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

We support the following query parameters for traversing:

• page[offset] - The offset determines the start record.
• page[limit] - The limit determines the number of records to display.
  • We maintain from 1 to 10 Streams per page.

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

Due to technical limitations, it's impossible to change the Stream type. If you need to change the type, we recommend you create a new Stream with the correct type and remove the old Stream.

If you have access to multiple accounts, you can't move the existing Stream to another account. If you need to move the Stream to another account, we recommend you create a new Stream in the new account.

Remove Stream

Example: Remove a Stream

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

Remove Streams if you no longer need them, or if a client needs to switch between the type of Streams. When you delete a stream, you are deleting all contained data as well. If you removed a client(s) while switching 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.

Site Stream Data Sources

The data source management endpoint allows you to link your streams to sites programmatically. You can create Stream API datasources and link them to sites, update them, delete or get more information about existing links

The authentication for this endpoint is unified, i.e. the new Stream API Personal Access Token authentication can be used to access functionality from the Platform API.

For more information, see the Platform API Site Stream Data Sources documentation

Uploading data

See the chapter on Stream type for more information on the differences between both types and also payload recommendations.

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

Request body

Example 1: Chunked Stream - NDJSON with one product

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: Chunked Stream - 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: Referenced Stream - NDJSON with multiple products

curl --location --request POST 'https://stream-api.productsup.com/streams/224773/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 4: Referenced Stream - JSON with one product

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

Example 5: Referenced Stream - JSON with 3 products

curl --location --request POST 'https://stream-api.productsup.com/streams/224773/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

Example 6: Referenced Stream - JSON with compressed products

curl --location --request POST 'https://stream-api.productsup.com/streams/224773/products' \
--header 'Content-Type: application/json' \
--header 'Accept: application/vnd.api+json' \
--header 'Authorization: Bearer pup_token' \
--header 'Content-Encoding: gzip' \
--data-binary '@/path/to/compressed_file'

Example 7: Chunked Stream - JSON with compressed products

curl --location --request POST 'https://stream-api.productsup.com/streams/224773/products' \
--header 'Content-Type: application/x-ndjson' \
--header 'Accept: application/vnd.api+json' \
--header 'Authorization: Bearer pup_token' \
--header 'Content-Encoding: gzip' \
--data-binary '@/path/to/compressed_file'

The type of the Stream dictates the allowed payload format:

• Chunked Streams accept application/x-ndjson
• Referenced Streams accept application/json or application/x-ndjson

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

Productsup supports gzip compression for both types of Streams to improve performance further. Use the Content-Encoding header to specify gzip compression for request payloads.

Response depending from stream status

The stream status feature is essential for maintaining and protecting our system's performance. It lets our data source actively monitor stream status, enabling administrators and automated processes to manage streams and prevent potential system overload responsibly.

Product attribute requirements

To accommodate to our clients data sets, we don't enforce a specific standard set of attributes or naming conventions.

We recommend the following rules for naming and handling attributes:

• Ideally attributes are lowercase and do not contain any spaces or special characters.
• Nested JSON structures are not supported; we recommend either:
  • Flattening the object into multiple attributes
  • Merge all it's values by a separator character

• When you add new attributes in future requests:
  • New attributes horizontally expand existing data with empty values
• When attributes are not part of the upload anymore:
  • If any existing row has a value for that attribute, the attribute remains in existence.
  • Any new row uploaded without the attribute will have an empty value

ID-attribute tips

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.

Process data

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

• Import: import the data from all data sources into a site.
• Export: export the data for one or all configured channel(s).
• Combined: run an import and consecutively export for all channels.

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

Site and Process Relationship

• Each site can have only one process running at a time. You can queue one additional process for each site.
• Processes operate directly on sites rather than on Streams.

Data import from Streams to sites

• Although processes work with sites, you can set up a site to receive data from a Stream via a Data Source.
• When you initiate a data import process on a site linked to a Stream, the process includes all data from the Stream uploaded before the process start.
• The platform doesn't include any data uploaded to the Stream after the start of the import process in the current run. It will process it in the next scheduled run.

Additional information for Stream API users:

• A site should have a data source to import from your Stream.

See Platform API Process Data documentation for more information.

Enhance Stream API processing speed

Product updates

Large updates involving 5 million or more products take significant time to process. So, we advise updating your product data more frequently and on smaller scales. Frequent smaller updates are more manageable and lead to faster processing.

Full site runs

Full site runs that involve importing, processing, and exporting data require the Productsup platform to process all product updates in one go, which leads to prolonged processing times. Besides breaking down your product updates into smaller, more frequent increments, we advise using partial site runs that involve either importing or exporting data to maintain smoother operations and reduce processing times.

Continuous exports

Implementing continuous exports in the Productsup platform means that the system is constantly processing a part of product updates. We recommend running imports in between your exports to let the system handle your product updates incrementally, which ensures your product data is up-to-date and significantly speeds up your subsequent imports.

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:

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.

Invalid batch

Chunked type

Example : Empty Product Attributes of Chunked type

curl --location --request POST 'https://stream-api.productsup.com/streams/streamId/products' \
--header 'Content-Type: application/x-ndjson' \
--header 'Authorization: Bearer token' \
--data-raw '{}'

Example : Empty Payload line of Chunked type

curl --location --request POST 'https://stream-api.productsup.com/streams/streamId/products' \
--header 'Content-Type: application/x-ndjson' \
--header 'Authorization: Bearer token' \
--data-raw '  '

Example : Empty Payload of Chunked type

curl --location --request POST 'https://stream-api.productsup.com/streams/streamId/products' \
--header 'Content-Type: application/x-ndjson' \
--header 'Authorization: Bearer token' \
--data-raw ''

Referenced type

Example 1: Empty Payload of Referenced type

curl --location --request POST 'https://stream-api.productsup.com/streams/streamId/products' \
--header 'Content-Type: application/json' \
--header 'Accept: application/vnd.api+json' \
--header 'Authorization: Bearer token' \
--data-raw '[{ }]'

Example 2: Empty Payload of Referenced type

curl --location --request POST 'https://stream-api.productsup.com/streams/streamId/products' \
--header 'Content-Type: application/json' \
--header 'Accept: application/vnd.api+json' \
--header 'Authorization: Bearer token' \
--data-raw '[]'

Example 3: Empty Payload of Referenced type

curl --location --request POST 'https://stream-api.productsup.com/streams/streamId/products' \
--header 'Content-Type: application/json' \
--header 'Accept: application/vnd.api+json' \
--header 'Authorization: Bearer token' \
--data-raw '[  ]'

Example 4: Empty Payload of Referenced type

curl --location --request POST 'https://stream-api.productsup.com/streams/streamId/products' \
--header 'Content-Type: application/json' \
--header 'Accept: application/vnd.api+json' \
--header 'Authorization: Bearer token' \
--data-raw ''

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

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 setup

You don't need any special platform knowledge to set up an import with the Stream API. But if you need help, take the following steps.

Prerequisites

To set up the import with Stream API, you need to have:

• User access to the Productsup platform
• A site in the Productsup platform ready for data import
• The Stream ID and Stream name(s).

Set up an 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, enter Stream API and find Stream API Data Source.
4. Select Add to add the data source.
5. Give your data source a custom name, as desired, to identify it among multiple data sources.
6. Select Next and get to Data Source Configuration page.
7. Select the Stream you want to import from. You can use the label Stream to find it later.
8. Change the description, as needed.
9. Select Save and get back to the Data Sources page.
10. If your Stream already contains data, select Import in the upper-right corner to import the data.
11. View your imported data in Data View.

Empty data sources

By default, the platform doesn't perform the import if a data source is empty, as it leads to a failure. But certain API scenarios may need to import an empty data source. For example, you may need to purge all data. To import an empty data source, take the following steps:

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 Options.
5. Check the checkbox Allow this datasource to have no products.
6. Select Save Options.

To inactivate the import of an empty data source, repeat the steps above and, in the Step 6., uncheck the checkbox Allow this datasource to have no products.

Platform recommendations

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

Timeouts

If the Stream API takes more than 10 seconds to process an API request, it will terminate the request. You will receive a timeout response and a Server Error message.

Productsup reserves the right to change the timeout window at any time to protect the API's speed and reliability.

Retry and backoff mechanisms

We recommend implementing retries for the following response status codes:

• 5xx Server Errors.
• 249 Custom Error.
• 408 Request Timeout.
• 429 Too Many Requests. Implement response headers with rate-limiting for this status code.

Key implementation points

• Implement at least five retry attempts per originally failed request
• Use an exponential backoff mechanism

Reasons to use exponential backoff

Use the exponential backoff to:

• Avoid overloading the platform during error periods.
• Increase the likelihood of converting failed requests into successful ones.
• Have more effectiveness during error surges than with a simple fixed-delay mechanism, such as retrying every second.

Implementation reference

For PHP implementation, you can reference the exponentialDelay() method in Guzzle HTTP clients' RetryMiddleware class. We use this method in our internal integrations with great success.

Platform API

Introduction

The Platform API is a REST API that provides programmatic access to account management features such as managing projects and sites, listing site errors, triggering processes, and more.

Status Page

Our status page provides real-time information on system performance and security. You will find live and historical data on system performance. The Status page will also contain messages on any service interruptions.

You can subscribe on the page to updates and receive notifications via your preferred communication channel.

Status page

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/

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

Cursor Pagination

The API uses a cursor pagination mechanism. It supports three parameters to control the pagination and pagination is only supported for GET requests.

HTTP Request

Example of meta-attribute in the response that contains the pagination parameters

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

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

GET https://platform-api.productsup.io/platform/v2/....?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

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

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

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}

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

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

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

Cron entry

Our scheduling format consists of an optional timezone and one or more scheduling formats. The timezone, if needed, should be on first line of the format, if no timezone is given our default timezone will be used. All PHP timezones are supported.
One or more schedules can be set up per site. A newline character should be used as a separator between timezone and schedule and between each schedule.
In case any scheduling needs to be remove and empty value can be supplied.

Example formats with explanation

TZ=Europe/Berlin # This is the timezone
H 2,6,19,22 * * 2,4,6  # Run at 02:XX, 06:XX, 16:XX and 19:XX on every Tuesday, Thursday and Saturday
H * * * * # Run at a random minute, every hour, every day
1 3,8,21 */2 * * # Run at 03:01, 08:01 and 21:01 every second day

Value formatted for submission via API:

TZ=Europe/Berlin\nH 2,6,19,22 * * 2,4,6\nH * * * *\n1 3,8,21 */2 * *

The value H for the minute position indicates a random minute will be used. It has our preference to configure all schedule with this value. If we have many jobs starting at exactly the same minute, that can lead to bottlenecks in our system.

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", "import_schedule": "8 * * * *"}' \
    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,
        "import_schedule": "8 * * * *",
        "links": [...]
    }]
}

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.

See Tag endpoints for an example of managing tags.

Response fields

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.

Response fields

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}

Copy

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

curl --location --request POST 'https://platform-api.productsup.io/platform/v2/sites/1/copy' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: value' \
--data-raw '{
    "site_name": "example copy site",
    "project_id": "2",
    "copy_export": true,
    "copy_schedule_and_trigger": true,
    "copy_shared_setting": true
}' 

# result:
{
    "success": true,
    "Sites": [{
        "id": "2",
        "title": "example copy site",
        "created_at": "2023-07-27 12:54:52",
        "project_id": "2",
        "import_schedule": "8 * * * *",
        "links": [...]
    }]
}

Copy site

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

URL parameters

HTTP headers

Provide the inserted data as a JSON object.

Request body fields

Response fields

See response fields

Site fields

See site fields

Links fields and values

See link fields

Site tags

Site tag endpoints offer our clients more independence and flexibility by letting them manage and customize their Productsup sites with tags.

List tags

Example: List all tags for a site

curl --location 'http://platform-api.productsup.io/platform/v2/sites/<SITE_ID>/tags' \
--header 'X-Auth-Token: TOKEN'

Example: List a single site tag by tag ID

curl --location 'http://platform-api.productsup.io/platform/v2/sites/<SITE_ID>/tags/<TAG_ID>' \
--header 'X-Auth-Token: TOKEN'

You can either list all tags for a site or a specific site tag. To list all tags for a site, you need to provide the site_id. To list an individual site tag, you need to provide the tag_id.

Create a tag

Example: Create a tag

curl --location 'http://platform-api.productsup.io/platform/v2/sites/<SITE_ID>/tags' \
--header 'X-Auth-Token: TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "site_id": "<SITE_ID>",
  "key": "<TAG_KEY>",
  "value": "<TAG_VALUE>",
  "readonly": 0
}'

When you create a tag, you need to specify the following attributes: - site_id contains the site ID the tag relates to. - key contains the name of the tag. - value contains the value of the tag. - readonly shows whether the tag is editable in the platform UI. If a tag is read-only, end users can't edit it in the platform.

Delete a tag

Example: Delete a tag

curl --location --request DELETE 'http://platform-api.productsup.io/platform/v2/sites/<SITE_ID>/tags/<TAG_ID>' \
--header 'X-Auth-Token: TOKEN'

If you no longer need a tag, you can delete it by providing the site_id and the tag_id.

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

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",
            "datetime": "2003-11-15 00:00:00",
            "type": "Error",
            "classification": "medium",
            "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.

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",
            "pid": "47e6b828-3210-3568-8ec3-85ed3e2d944c",
            "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.

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.

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

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

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

The API supports this product read endpoint, but the technical characteristics of our infrastructure setup don't allow it to be a high-performing endpoint. We currently do not offer a high-performing product read endpoint. Depending on the complexity of the filter, the database size and the number of columns, requests can sometimes take a couple of minutes or more. In these cases, we ask you not to send concurrent requests. Send consecutive requests only.

Process data

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

• Import: import the data from all data sources into a site.
• Export: export the data for one or all configured channel(s).
• Combined: run an import and consecutively export for all channels.

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

Site and Process Relationship

• Each site can have only one process running at a time. You can queue one additional process for each site.
• Processes operate directly on sites rather than on Streams.

Data import from Streams to sites

• Although processes work with sites, you can set up a site to receive data from a Stream via a Data Source.
• When you initiate a data import process on a site linked to a Stream, the process includes all data from the Stream uploaded before the process start.
• The platform doesn't include any data uploaded to the Stream after the start of the import process in the current run. It will process it in the next scheduled run.

Post

Trigger a processing action on your site.

Triggering an action on your site

curl --location --request POST 'https://platform-api.productsup.io/platform/v2/process/<siteId>' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: accountId:yourToken' \
--data-raw '{"action": "import"}'

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

Action value explanation

Response body fields

Response status codes

Site Stream Data Sources

The data source management endpoint allows you to link your streams to sites programmatically. You can create Stream API datasources and link them to sites, update them, delete or get more information about existing links

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 datasources

List all stream datasources 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 status information

Datasource import type 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

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": "https://platform-api.productsup.io/platform/v2/sites/<siteId>/errors?pid=<pid>"
        },
        {
            "self": "https://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"
}

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:

Rate limiting

Different endpoints of the Platform API are subject to different rate limits. We enforce rate limits at an account and route level.

The Platform API applies the following rate limits to all requests coming from one account:

Rate limit HTTP headers

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

$ curl -I https://platform-api.productsup.io
HTTP/2 200
X-RateLimit-Limit: 5
X-Ratelimit-Remaining: 1
X-Ratelimit-Retry-After: 1651174223

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

HTTP/2 429
X-RateLimit-Limit: 5
X-Ratelimit-Remaining: 1
X-Ratelimit-Retry-After: 1651174223

{"success":false,"message":"Too many attempts."}

Retry and backoff mechanisms

We recommend implementing retries for the following response status codes:

• 5xx Server Errors.
• 249 Custom Error.
• 408 Request Timeout.
• 429 Too Many Requests. Implement response headers with rate-limiting for this status code.

Key implementation points

• Implement at least five retry attempts per originally failed request
• Use an exponential backoff mechanism

Reasons to use exponential backoff

Use the exponential backoff to:

• Avoid overloading the platform during error periods.
• Increase the likelihood of converting failed requests into successful ones.
• Have more effectiveness during error surges than with a simple fixed-delay mechanism, such as retrying every second.

Implementation reference

For PHP implementation, you can reference the exponentialDelay() method in Guzzle HTTP clients' RetryMiddleware class. We use this method in our internal integrations with great success.

Changelog

Introduction

This section is a record of all notable changes made to Stream API and Platform API.

Stream API changelog

Here are the recent changes introduced to the Stream API:

01/08/2024

• Supporting gzip compression to upload compressed file. See Compression for more intormation.

21/03/2024

• Clarified allowed payload formats for the Stream API when uploading data. Chunked Streams accept application/x-ndjson, and Referenced Streams accept application/json or application/x-ndjson.

08/01/2024

• The Batches API endpoint is now only available upon request. If you need access to it, reach out to your Client Success Manager.

29/11/2023

• Added a limit of 100 streams per account. If you need more streams, reach out to your Client Success Manager.

25/09/2023

• Released version 0.4 of the Open API definition file.

What's Changed

• Added enumerated possible response codes (e.g., 400, 422, 500) to all endpoints for improved error handling.
• Modified schema format and maximum values for the page[limit] and page[offset] query parameters on the get streams endpoint.
• Specified the maximum number of items found in the $.error.errors responses for all endpoints.
• Set a maximum length of 499900 bytes for the id attribute on the products upload endpoint. Any product with an id attribute exceeding this limit will be rejected.
• Updated the format and defined the maximum length for the createdAt and updatedAt properties in the streams endpoint response and the completedAt property in the batches endpoint response.
• Added the format, minimum, and maximum specifications for the successCount and errorCount properties in the batches endpoint response.
• Limited the maximum number of distinct errors that the batches endpoint response can return.

01/06/2023

• Added a status page link

18/05/2023

• Changed the status code from 400 to 422 when an "Empty Payload" error occurs for an uploaded batch on the /streams/{streamId}/products endpoint.
• Fixed a bug in the /streams/{streamId}/products endpoint response where the relationships object was incorrectly placed at the root path instead of being placed as a child of the data object.
• Changed Location to Content-Location in the header of the response that the POST /streams operation returns for a newly created stream.

⚠️ Deprecations:

• The relationships object found at the $.relationships path of the /streams/{streamId}/products endpoint's response is deprecated. Use $.data.relationships instead.
• The Location header found in the response of the POST /streams operation is deprecated. Use Content-Location instead.

31/03/2023

• Increased the rate limit for the "batches" endpoint to 100 requests per second per {streamId}. The documented rate limits are now enforced as strict limits. Crossing them causes throttling.

11/01/2023

• Changed "id" as a string in the OpenAPI spec.
• Fixed a bug with supporting the charset part of the Content-Type header.

Platform API changelog

Here are the recent changes introduced to the Platform API:

31/03/2025

• Updated documentation to represent sunsetted Platform API data write endpoints

02/09/2024

• Added tag endpoints. See tag endpoints for more information.

24/05/2024

• Exposed error "type" and "classification" in the site errors endpoint. See errors endpoint for more information.

05/09/2023

• Added a new API endpoint to copy sites. See copy site for more information.

23/05/2023

• Introduced new API rate limits for all endpoints. See rate limiting for more information.

01/06/2023

• Added status page link

15/02/2023

• Fixed the empty file creation handling when rows were written because of a one-hour delay between the last upload and the commit. See upload and commit rule for more information.

31/01/2023

• Fixed the issue with the products endpoint returning a response with an empty response body.

20/01/2023

• Exposed datetime in the site errors endpoint. See errors endpoint for more information.

10/01/2023

• Fixed a bug in deleteNotMatchingFeedHeadersIds.