Skip to main content
API docs by Redocly

topi Seller API (1.0.0)

Download OpenAPI specification:Download

Localization

Strings returned can be localized when the Accept-Language header is provided in the request. It should follow the RFC-2616 convention.

catalog

Topi catalog for sellers

Calculate pricing for a whole basket

Deprecated

Calculate pricing endpoint is being replaced by two other endpoints:

  • listRecommendedRentalPrices
  • cartRentalOverview

Please make sure to migrate to one of the above endpoints based on your use case.

Description

calculate the price for a product

Authorizations:
OAuth2Seller_header_Authorization
Request Body schema: application/json
required
required
Array of objects (BasketPricingRequest)

The pricing to request

Array
object (MoneyAmountWithOptionalTax)
identifier
string

unique identifier for this pricing request, used to keep track of items and prices in FE

object (MoneyAmountWithOptionalTax)
quantity
required
integer <int64>

Quantity of this product.

required
object (SellerProductReference)
Array of objects (PricingRequest)

Service products to be priced alongside this main product in the pricing calculation. Sublines enable sellers to request pricing for bundled service offerings, allowing for comprehensive cost calculations that include both the main product and its associated services.

    Business Rules:
    - Sublines are only valid for hardware and accessory main products
    - Each subline must reference a service-category product
    - Sublines inherit quantities from the parent product
    - Pricing engine calculates both individual subline costs and combined bundle totals
    - Rental durations and contract terms are synchronized across main line and sublines
    
    Example: Requesting pricing for a tablet (main product) with device setup (sublines)

Responses

Request samples

Content type
application/json
{
  • "pricing_requests": [
    ]
}

Response samples

Content type
application/json
{
  • "basket_total_pay_now": {
    },
  • "basket_total_rent": {
    },
  • "summaries": [
    ]
}

Get rental overview for products

Authorizations:
OAuth2Seller_header_Authorization
Request Body schema: application/json
required
required
Array of objects (RentalOverviewRequest)
Array
object (MoneyAmountWithOptionalTax)
object (MoneyAmountWithOptionalTax)
quantity
required
integer <int64>

Quantity of this product.

required
object (SellerProductReference)

Responses

Request samples

Content type
application/json
{
  • "products": [
    ]
}

Response samples

Content type
application/json
{
  • "can_checkout": false,
  • "currency": "EUR",
  • "product_prices": [
    ],
  • "total_rental_amount": 1,
  • "total_rental_summary": "Rent with topi from €123.45/month"
}

Check if products are supported

Checks whether the products with the given references are supported or not.

When using in the Sandbox

Returns the requested products with their available contract terms, depending on the combination of the supplied Source and Reference values:

  • To get a product with PayNow contract terms : The supplied source should be SAP with reference specified as 1234-5678.
  • To get a product with Rent contract terms : There are two ways to get this value either when the supplied source is SAP and the reference is 1111-1111 or with source set to B6 and reference specified as 2222-2222.
  • To get a product that is not topi supported: Specify the source as SAP and reference should be 8765-4321.

In other cases this method will return an empty array.

This method has been defined as POST because the size of the input values could grow fast.

Authorizations:
OAuth2Seller_header_Authorization
Request Body schema: application/json
required
required
Array of objects (SellerProductReference)

the ids for obtains the available contract terms.

Array
reference
required
string non-empty [a-zA-Z0-9._-]

The ID related with the source. This value should be unique for that source.

source
required
string non-empty

The seller internal source name for this reference type.

Responses

Request samples

Content type
application/json
{
  • "seller_product_references": [
    ]
}

Response samples

Content type
application/json
{
  • "products": [
    ]
}

Import products into the catalog

Add a batch of products to the catalog.

When using in the Sandbox

Use the following scenarios to get different fixtures:

  • Status "completed": Send a catalog with less than 10 products
  • Status "created": Send a catalog with 10 products or more
  • Status "failed": Send a product inside the catalog with the "source" or the "reference" in the "seller_product_reference" as empty string
Authorizations:
OAuth2Seller_header_Authorization
Request Body schema: application/json
required
required
Array of objects (AddProduct) non-empty

Product payload

Array (non-empty)
object (MoneyAmount)
description
string <= 2000 characters

Detailed description of the product.

Array of objects (ExtraProductDetails)

Additional details about the product, such as CPU, memory size, etc.

object (ProductImage)
is_active
required
boolean

Indicates if the product is currently active.

manufacturer
string

Name of the product's manufacturer.

required
object (MoneyAmountWithOptionalTax)
Array of objects (ProductStandardIdentifier)

List of standardized identifiers for the product, such as UPC, EAN, or ISBN.

Array of objects (ProductSellerCategory)

An array of categories provided by the seller for this product.

required
Array of objects (SellerProductReference) non-empty

An array of the seller's unique references for this product.

seller_product_type
string
Enum: "hardware" "software" "service" "hardware_built_to_order"

Type of the product, such as hardware, software, service, etc.

shop_product_description_url
string <uri>
subtitle
string

Subtitle of the product.

title
required
string

Title of the product.

Responses

Request samples

Content type
application/json
{
  • "products": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "739b63c2-9e58-4964-b38d-4ebb424de242",
  • "status": "started",
  • "summary": {
    }
}

Create a CSV import job

Creates a new CSV import job and returns the created import id and a pre-signed upload URL.

Upload flow

  1. Call POST /imports with the filename of your CSV file. The response contains the import id and an upload_url — a temporary link to upload the file to.
  2. Upload the file with an HTTP PUT request to upload_url. The request must include two headers: Content-Type: text/csv and x-goog-content-length-range: 0,262144000. Uploads without them are rejected. The file may be at most 250 MB.
  3. The file is then checked and processed in the background. Call GET /imports/{id} to follow progress. When some rows could not be imported, the response links to a downloadable CSV listing each failed row and the reason. If the file fails the initial check (for example a required column is missing), the import status becomes failed and the error field explains why.

A seller can have at most 5 imports running at the same time. Starting a sixth returns a TooManyRequests error — wait for an earlier import to finish and try again.

CSV format

The first line of the file must be a header row with column names. Column names are not case-sensitive and surrounding spaces are ignored; any column not listed below is simply skipped.

Re-uploading a product you imported before (same reference) updates that product instead of creating a duplicate. Leaving an optional cell empty on re-import keeps the product's existing value for that field.

Required columns

The import is rejected if any of these are missing from the header.

Column Description Format
title Product name shown to customers Non-empty text
reference Your product identifier(s) One or more values joined by |; count must match reference_source
reference_source Source/type of each reference (e.g. sku, ean) |-separated, same count as reference
is_active Whether the product is sellable true/false, 1/0, yes/no, y/n (case-insensitive)
price_gross Sale price incl. VAT Number > 0, must be >= price_net
price_net Sale price excl. VAT Number > 0

Optional columns

Column Description Format
currency Currency code, e.g. EUR Defaults to the seller currency if blank
manufacturer Brand / maker Text
subtitle Short tagline under the title Text
description Long product description Text, max 2000 characters
base_rental_price_gross Monthly rental price incl. VAT Number > 0, must be >= net if both set
base_rental_price_net Monthly rental price excl. VAT Number > 0
ean EAN barcode Text
mpn Manufacturer part number Text
image_url Product image Valid URL
seller_category_id Your category ID Text
seller_category_name Your category name Text
seller_category_parent_id Parent category ID Text
seller_product_type Product type One of hardware, software, service, hardware_built_to_order, or blank
shop_product_description_url Link to the product page on your shop Valid URL
extra_details Custom key/value attributes key=value pairs joined by |

Prices

  • Prices are written in whole currency units, not cents: 2499.00 means 2,499 euros.
  • price_gross (with VAT) must be greater than or equal to price_net (without VAT).
  • Both decimal styles are accepted: a point (1999.99) or a comma (1999,99) before the decimals. Thousands separators are also fine in either style: 1,234.56 and 1.234,56 both mean one thousand two hundred thirty-four euros and 56 cents.
  • One shape cannot be told apart: a value like 1,234 could mean 1.234 or 1234, so that row is rejected with an error. To avoid this, always write the cents explicitly — 1234.00 (or 1.234,00) for one thousand two hundred thirty-four euros, 1.23 (or 1,23) for one euro and 23 cents.

Notes

  • Multiple references: a product can carry several identifiers — pipe-separate them in reference (e.g. MBP14-001|0719726100000) with matching kinds in reference_source (e.g. sku|ean). The two columns must have an equal number of |-separated values.
  • Duplicate references within the same file are rejected per row; the rest of the file still imports.
  • A row that fails validation does not stop the import: valid rows still import, and every failed row is listed with its reason in the downloadable error CSV.

Example

title,reference,reference_source,is_active,price_gross,price_net,currency,manufacturer,seller_product_type,extra_details
Apple MacBook Pro 14,MBP14-001,sku,true,2499.00,2099.16,EUR,Apple,hardware,color=Space Black|warranty=24 months
Dell UltraSharp Monitor,DELL-U2724|0719726100000,sku|ean,1,649.00,545.38,EUR,Dell,hardware,resolution=3840x2160|panel=IPS
Authorizations:
OAuth2Seller_header_Authorization
Request Body schema: application/json
required
filename
string

The name of the CSV file to import

Responses

Request samples

Content type
application/json
{
  • "filename": "abc123"
}

Response samples

Content type
application/json
{}

Cancel a CSV import job

Cancels a CSV import job.

Only imports in pending, queued, and running status can be cancelled. Cancelling a completed or already-cancelled import returns an error.

Authorizations:
OAuth2Seller_header_Authorization
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The import job ID to cancel.

Responses

Request samples 

curl -X DELETE https://seller-api.topi.eu/v1/catalog/imports/{id} \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response samples

Content type
application/json
"abc123"

Get CSV import job details

Retrieves the details of a CSV import job.

Failure reporting

There are two distinct failure surfaces:

  • error — set when the import fails before any rows are processed, e.g. a required column is missing from the header, the uploaded file is not a valid CSV, or the upload has the wrong content type. The job status is failed, the row counters stay at 0, and no error CSV is produced. Fix the file and create a new import.
  • failed / errors_url — row-level failures during processing. The import keeps going; rows that failed are counted in failed and detailed in the downloadable CSV at errors_url. The error field stays empty in this case.
Authorizations:
OAuth2Seller_header_Authorization
path Parameters
id
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The import job ID.

Responses

Request samples 

curl -X GET https://seller-api.topi.eu/v1/catalog/imports/{id} \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response samples

Content type
application/json
{
  • "categorization": {
    },
  • "created_at": "1970-01-01T00:00:01Z",
  • "error": "abc123",
  • "errors_url": "https://example.com/foo",
  • "failed": 1,
  • "filename": "abc123",
  • "id": "739b63c2-9e58-4964-b38d-4ebb424de242",
  • "object_path": "https://example.com/foo",
  • "processed": 1,
  • "status": "queued",
  • "succeeded": 1,
  • "updated_at": "1970-01-01T00:00:01Z"
}

List recommended rental prices for products

Given a list of products, retrieve information about the recommended monthly rental price and term, if applicable, for each of the requested products.

Authorizations:
OAuth2Seller_header_Authorization
Request Body schema: application/json
required
required
Array of objects (PricingRequest)

List of product pricing to request.

Array
object (MoneyAmountWithOptionalTax)
object (MoneyAmountWithOptionalTax)
required
object (SellerProductReference)

Responses

Request samples

Content type
application/json
{
  • "pricing_requests": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Calculate pricing for a single product

Deprecated

Calculate pricing endpoint is being replaced by two other endpoints:

  • listRecommendedRentalPrices
  • cartRentalOverview

Please make sure to migrate to one of the above endpoints based on your use case.

Description

calculate the price for a product

Authorizations:
OAuth2Seller_header_Authorization
Request Body schema: application/json
required
required
object (PricingRequest)
object (MoneyAmountWithOptionalTax)
object (MoneyAmountWithOptionalTax)
required
object (SellerProductReference)

Responses

Request samples

Content type
application/json
{
  • "pricing_request": {
    }
}

Response samples

Content type
application/json
{
  • "available_contract_types": [
    ],
  • "is_supported": true,
  • "pay_now": {
    },
  • "rent": [
    ],
  • "sublines": [
    ],
  • "summary": "Rent with topi for €24.32/month"
}

Search products by term

get products that match a search term

Authorizations:
OAuth2Seller_header_Authorization
query Parameters
term
string
Example: term=abc123

The Seller Product Reference

Responses

Request samples 

curl -X GET https://seller-api.topi.eu/v1/catalog/products \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response samples

Content type
application/json
[
  • {
    }
]

Paginated product search by term, note: this method will not support any filtering, please refer to the POST endpoint for filtering.

get paginated products that match a search term, note: this method will not support any filtering.

Authorizations:
OAuth2Seller_header_Authorization
query Parameters
term
string
Example: term=abc123

The Seller Product Reference

limit
integer <int64>
Example: limit=1

the size of the page

page
integer <int64>
Example: page=1

the index of the page

Responses

Request samples 

curl -X GET https://seller-api.topi.eu/v1/catalog/products_paginated \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response samples

Content type
application/json
{
  • "limit": 1,
  • "page": 1,
  • "rows": [
    ],
  • "totalPages": 1,
  • "totalRows": 1
}

Paginated product search by term, filtering by provided options

get paginated products that match a search term and the provided filters

Authorizations:
OAuth2Seller_header_Authorization
query Parameters
term
string
Example: term=abc123

The Seller Product Reference

limit
integer <int64>
Example: limit=1

the size of the page

page
integer <int64>
Example: page=1

the index of the page

Request Body schema: application/json
required
filtering_logic
string
Enum: "AND" "OR"

The logic to use for filtering the products. Can be 'and' or 'or'.

Array of objects (FilteringOption)

Filtering options for the search

Responses

Request samples

Content type
application/json
{
  • "filtering_logic": "OR",
  • "filtering_options": [
    ]
}

Response samples

Content type
application/json
{
  • "limit": 1,
  • "page": 1,
  • "rows": [
    ],
  • "totalPages": 1,
  • "totalRows": 1
}

offer

Provides operations to handle offers for end-customers.

Webhooks

OfferUpdates

We will ping the URL provided whenever an offer has changed its status to: "accepted", "declined", "voided", "pending_review" or "expired".

Payload:

  • same as show offer
    • id: string
    • created_at: string <date-time>
    • status: string enum: "accepted" | "declined" | "pending_review" | "voided" | "expired"
    • checkout_redirect_url: string <uri>

List all offers (deprecated) Deprecated

Lists the offers created by the calling seller, with filters or query. (deprecated)

This method is deprecated. Please use List all offers with pagination instead.

Authorizations:
OAuth2Seller_header_Authorization
query Parameters
query
string
Examples:
  • query=status - default

Search query. It can be a string or a number or both

created_by
string
Example: created_by=sales-agent@example.com,anothergreatone@example.com

a comma-separated list of sales agents emails

partners_only
boolean
Example: partners_only=false

a boolean indicating whether to retrieve offers from partner sellers only

Responses

Request samples 

curl -X GET https://seller-api.topi.eu/v1/offers \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response samples

Content type
application/json
[
  • {
    }
]

Create an offer

Creates a topi offer.

Returns HTTP 200 plus basic information about the offer on success.

The request returns an HTTP Unprocessable Entity in the following scenarios:

  • When "lines" is an empty array.
  • When "lines" contains any products that are not available in the topi catalog
  • When the "seller_offer_reference" is reusing a value of an offer that is currently active

When using in the Sandbox

The following seller offer references are considered to be "active":

  • "ref-1234"

The following seller product references are considered to be available in the catalog:

  • {"source": "sap", "reference": "123"}
  • {"source": "sap", "reference": "456"}
  • {"source": "sku", "reference": "123abc"}

The following seller product references are considered to be available in the catalog but not supported:

  • {"source": "sku", "reference": "unsupported-1"}

The following shipping reference is considered to be available but not supported:

  • "unsupported-shipping-reference"
Authorizations:
OAuth2Seller_header_Authorization
Request Body schema: application/json
required
object (CustomerInfo)

Customer information

draft_offer_id
string

The ID of the draft offer from which an offer is being created

exit_redirect
string <uri>

URL to redirect to when something went wrong along the process. We will add the following parameters to the query string: offer_id, seller_offer_reference

expires_at
required
string <date-time>

Expiration date and time for the offer (UTC)

required
Array of objects (OfferLinePayload) non-empty

List of product lines

object

Metadata you can attach to and offer. You can store here any JSON information

object (SalesAgent)

Sales agent related to an offer

sales_channel
required
string
Enum: "telesales" "ecommerce" "in_store_pos"

Channel from where the offer is created

seller_offer_reference
required
string

Seller's own reference for the offer

object (ShippingInfo)

Shipping information

object (ShippingAddress)

Shipping Address. If the sales_channel is ecommerce, this field will be required

success_redirect
string <uri>

URL to redirect to when the user finishes the checkout in topi. We will add the following parameters to the query string: offer_id, seller_offer_reference, order_id

Responses

Request samples

Content type
application/json
{
  • "customer": {
    },
  • "draft_offer_id": "abc123",
  • "exit_redirect": "https://example.com/foo",
  • "expires_at": "1970-01-01T00:00:01Z",
  • "lines": [
    ],
  • "metadata": {
    },
  • "sales_agent": {
    },
  • "sales_channel": "ecommerce",
  • "seller_offer_reference": "ref-1234",
  • "shipping": {
    },
  • "shipping_address": {
    },
  • "success_redirect": "https://example.com/foo"
}

Response samples

Content type
application/json
{
  • "checkout_redirect_url": "https://example.com/foo",
  • "created_at": "1970-01-01T00:00:01Z",
  • "customer": {
    },
  • "expires_at": "1970-01-01T00:00:01Z",
  • "id": "739b63c2-9e58-4964-b38d-4ebb424de242",
  • "lines": [
    ],
  • "metadata": {
    },
  • "pricing_overview": {
    },
  • "sales_agent": {
    },
  • "sales_channel": "ecommerce",
  • "seller_offer_redirect_url": "https://example.com/foo",
  • "seller_offer_reference": "ref-1234",
  • "shipping": {
    },
  • "shipping_address": {
    },
  • "status": "voided"
}

Retrieve an offer

Returns a single offer.

When using in the Sandbox

Use the following ID's to get different fixtures. Remember that the URL must be encoded:

  • Status "created": "739b63c2-9e58-4964-b38d-4ebb424de242"
  • Status "voided": "ddd454b6-f23b-4f9c-a36d-74964766c3d6"
  • Status "expired": "3beec7f7-a258-4260-8713-6c2635e5eea5"
  • Status "accepted": "60412bcf-8213-4804-841e-f3c36ce46394"

Any other ID will return an HTTP 404 error.

Authorizations:
OAuth2Seller_header_Authorization
path Parameters
id
required
string <regexp> ^[0-9A-Za-z\-]+$
Example: 739b63c2-9e58-4964-b38d-4ebb424de242

topi offer ID

Responses

Request samples 

curl -X GET https://seller-api.topi.eu/v1/offers/{id} \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response samples

Content type
application/json
{
  • "checkout_redirect_url": "https://example.com/foo",
  • "created_at": "1970-01-01T00:00:01Z",
  • "customer": {
    },
  • "expires_at": "1970-01-01T00:00:01Z",
  • "id": "739b63c2-9e58-4964-b38d-4ebb424de242",
  • "lines": [
    ],
  • "metadata": {
    },
  • "pricing_overview": {
    },
  • "sales_agent": {
    },
  • "sales_channel": "ecommerce",
  • "seller_offer_redirect_url": "https://example.com/foo",
  • "seller_offer_reference": "ref-1234",
  • "shipping": {
    },
  • "shipping_address": {
    },
  • "status": "voided"
}

Edit an offer

Edits an offer by voiding it and creating a new offer superseding it with the provided details.

Note: Offer details will be replaced with the validated payload passed to this endpoint. Make sure to send the full offer details information.

Authorizations:
OAuth2Seller_header_Authorization
path Parameters
id
required
string <regexp> ^[0-9A-Za-z\-]+$
Example: 739b63c2-9e58-4964-b38d-4ebb424de242

Offer ID

Request Body schema: application/json
required
object (CustomerInfo)

Customer information

draft_offer_id
string

The ID of the draft offer from which an offer is being created

exit_redirect
string <uri>
expires_at
required
string <date-time>
required
Array of objects (OfferLinePayload) non-empty

List of product lines

object

Metadata you can attach to and offer. You can store here any JSON information

object (SalesAgent)

Sales agent related to an offer

sales_channel
required
string
Enum: "telesales" "ecommerce" "in_store_pos"
seller_offer_reference
required
string

Seller's own reference for the offer

object (ShippingInfo)

Shipping information

object (ShippingAddress)

Shipping Address. If the sales_channel is ecommerce, this field will be required

success_redirect
string <uri>

Responses

Request samples

Content type
application/json
{
  • "customer": {
    },
  • "draft_offer_id": "abc123",
  • "exit_redirect": "https://example.com/foo",
  • "expires_at": "1970-01-01T00:00:01Z",
  • "lines": [
    ],
  • "metadata": {
    },
  • "sales_agent": {
    },
  • "sales_channel": "ecommerce",
  • "seller_offer_reference": "ref-1234",
  • "shipping": {
    },
  • "shipping_address": {
    },
  • "success_redirect": "https://example.com/foo"
}

Response samples

Content type
application/json
{
  • "checkout_redirect_url": "https://example.com/foo",
  • "created_at": "1970-01-01T00:00:01Z",
  • "customer": {
    },
  • "expires_at": "1970-01-01T00:00:01Z",
  • "id": "739b63c2-9e58-4964-b38d-4ebb424de242",
  • "lines": [
    ],
  • "metadata": {
    },
  • "pricing_overview": {
    },
  • "sales_agent": {
    },
  • "sales_channel": "ecommerce",
  • "seller_offer_redirect_url": "https://example.com/foo",
  • "seller_offer_reference": "ref-1234",
  • "shipping": {
    },
  • "shipping_address": {
    },
  • "status": "voided"
}

Void an offer

Voids an offer. Optionally, marks an existing offer as superseding this one.

All offers can be voided except those with status accepted. A HTTP 402 Unprocesssable Entity error will be returned in this case.

If the superseding offer ID does not exist or has the same ID has the voided offer, HTTP 402 Unprocessable Entity will be returned.

When using in the Sandbox

You can use the following IDs to refer to different offer fixtures and test this endpoint. Remember that URL's must be encoded.

  • Status "created": "739b63c2-9e58-4964-b38d-4ebb424de242"
  • Status "voided": "ddd454b6-f23b-4f9c-a36d-74964766c3d6"
  • Status "expired": "3beec7f7-a258-4260-8713-6c2635e5eea5"
  • Status "accepted": "60412bcf-8213-4804-841e-f3c36ce46394"

Keep in mind that the Sandbox does not persist state. Even if you void an offer, subsequent calls to different API endpoints will yield the same results.

Authorizations:
OAuth2Seller_header_Authorization
path Parameters
id
required
string <regexp> ^[0-9A-Za-z\-]+$
Example: 739b63c2-9e58-4964-b38d-4ebb424de242

topi offer ID

Request Body schema: application/json
required
superseded_by_id
string <regexp> ^[0-9A-Za-z\-]+$

The topi offer ID of the offer that supersedes this voided one

Responses

Request samples

Content type
application/json
{
  • "superseded_by_id": "739b63c2-9e58-4964-b38d-4ebb424de242"
}

Response samples

Content type
application/json
{
  • "created_at": "1971-05-24T04:42:31Z"
}

List all offers with pagination

Lists the offers created by the calling seller, with pagination and filters. Supports offset-based pagination (page/limit) and range filters for efficient data traversal.

Recommended approach for paginating over all data: Use ID range filters with limit=100. The ID range filter (id_gt) works like cursor-based pagination, providing the most efficient way to iterate through the complete dataset. Pass the last ID from the previous page as id_gt to fetch the next batch.

Examples:

  • First page: ?limit=100
  • Next page: ?id_gt=&limit=100
  • Time-based sync: ?created_at_gt=&limit=100
Authorizations:
OAuth2Seller_header_Authorization
query Parameters
limit
integer <int64>
Example: limit=1

the size of the page

page
integer <int64>
Example: page=1

the index of the page

query
string
Examples:
  • query=status - default

Search query. It can be a string or a number or both

created_by
string
Example: created_by=sales-agent@example.com,anothergreatone@example.com

a comma-separated list of sales agents emails

partners_only
boolean
Example: partners_only=false

a boolean indicating whether to retrieve offers from partner sellers only

sort_by
string
Default: "created_at"
Enum: "created_at" "status" "expires_at"
Example: sort_by=status

Field to sort by

sort_order
string
Default: "asc"
Enum: "asc" "desc"
Example: sort_order=desc

Sort direction

id_gt
string <uuid>
Example: id_gt=550e8400-e29b-41d4-a716-446655440000

Filter: offer ID > value (UUID)

id_gte
string <uuid>
Example: id_gte=550e8400-e29b-41d4-a716-446655440000

Filter: offer ID >= value (UUID)

id_lt
string <uuid>
Example: id_lt=550e8400-e29b-41d4-a716-446655440000

Filter: offer ID < value (UUID)

id_lte
string <uuid>
Example: id_lte=550e8400-e29b-41d4-a716-446655440000

Filter: offer ID <= value (UUID)

created_at_gt
string <date-time>
Example: created_at_gt=2025-01-01T00:00:00Z

Filter: offer created_at > value (RFC3339)

created_at_gte
string <date-time>
Example: created_at_gte=2025-01-01T00:00:00Z

Filter: offer created_at >= value (RFC3339)

created_at_lt
string <date-time>
Example: created_at_lt=2025-12-31T23:59:59Z

Filter: offer created_at < value (RFC3339)

created_at_lte
string <date-time>
Example: created_at_lte=2025-12-31T23:59:59Z

Filter: offer created_at <= value (RFC3339)

Responses

Request samples 

curl -X GET https://seller-api.topi.eu/v1/offers/paginated \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response samples

Content type
application/json
{
  • "offers": [
    ],
  • "pagination": {
    }
}

Create an offer for a partner

Creates a topi offer.

Returns HTTP 200 plus basic information about the offer on success.

The request returns an HTTP Unprocessable Entity in the following scenarios:

  • When "lines" is an empty array.
  • When "lines" contains any products that are not available in the topi catalog
  • When the "seller_offer_reference" is reusing a value of an offer that is currently active

When using in the Sandbox

The following seller offer references are considered to be "active":

  • "ref-1234"

The following seller product references are considered to be available in the catalog:

  • {"source": "sap", "reference": "123"}
  • {"source": "sap", "reference": "456"}
  • {"source": "sku", "reference": "123abc"}

The following seller product references are considered to be available in the catalog but not supported:

  • {"source": "sku", "reference": "unsupported-1"}

The following shipping reference is considered to be available but not supported:

  • "unsupported-shipping-reference"
Authorizations:
OAuth2Seller_header_Authorization
Request Body schema: application/json
required
object (CustomerInfo)

Customer information

draft_offer_id
string

The ID of the draft offer from which an offer is being created

exit_redirect
string <uri>

URL to redirect to when something went wrong along the process. We will add the following parameters to the query string: offer_id, seller_offer_reference

expires_at
required
string <date-time>

Expiration date and time for the offer (UTC)

required
Array of objects (OfferLinePayload) non-empty

List of product lines

object

Metadata you can attach to and offer. You can store here any JSON information

required
object (SalesAgent)

Sales agent related to an offer

sales_channel
required
string
Enum: "telesales" "ecommerce" "in_store_pos"

Channel from where the offer is created

seller_offer_reference
required
string

Seller's own reference for the offer

object (ShippingInfo)

Shipping information

object (ShippingAddress)

Shipping Address. If the sales_channel is ecommerce, this field will be required

success_redirect
string <uri>

URL to redirect to when the user finishes the checkout in topi. We will add the following parameters to the query string: offer_id, seller_offer_reference, order_id

Responses

Request samples

Content type
application/json
{
  • "customer": {
    },
  • "draft_offer_id": "abc123",
  • "exit_redirect": "https://example.com/foo",
  • "expires_at": "1970-01-01T00:00:01Z",
  • "lines": [
    ],
  • "metadata": {
    },
  • "sales_agent": {
    },
  • "sales_channel": "ecommerce",
  • "seller_offer_reference": "ref-1234",
  • "shipping": {
    },
  • "shipping_address": {
    },
  • "success_redirect": "https://example.com/foo"
}

Response samples

Content type
application/json
{
  • "checkout_redirect_url": "https://example.com/foo",
  • "created_at": "1970-01-01T00:00:01Z",
  • "customer": {
    },
  • "expires_at": "1970-01-01T00:00:01Z",
  • "id": "739b63c2-9e58-4964-b38d-4ebb424de242",
  • "lines": [
    ],
  • "metadata": {
    },
  • "pricing_overview": {
    },
  • "sales_agent": {
    },
  • "sales_channel": "ecommerce",
  • "seller_offer_redirect_url": "https://example.com/foo",
  • "seller_offer_reference": "ref-1234",
  • "shipping": {
    },
  • "shipping_address": {
    },
  • "status": "voided"
}

Retrieve an offer by seller reference

Returns a single offer, fetched by the seller's own reference.

When using in the Sandbox

Use the following references to get different offer fixtures:

  • Status "created": "ref-created"
  • Status "voided": "ref-voided"
  • Status "expired": "ref-expired"
  • Status "accepted": "ref-accepted"

Any other ID will return an HTTP 404 error.

Authorizations:
OAuth2Seller_header_Authorization
path Parameters
seller_offer_reference
required
string
Example: ref-1234

Seller's own reference for the offer

Responses

Request samples 

curl -X GET https://seller-api.topi.eu/v1/offers/ref/{seller_offer_reference} \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response samples

Content type
application/json
{
  • "checkout_redirect_url": "https://example.com/foo",
  • "created_at": "1970-01-01T00:00:01Z",
  • "customer": {
    },
  • "expires_at": "1970-01-01T00:00:01Z",
  • "id": "739b63c2-9e58-4964-b38d-4ebb424de242",
  • "lines": [
    ],
  • "metadata": {
    },
  • "pricing_overview": {
    },
  • "sales_agent": {
    },
  • "sales_channel": "ecommerce",
  • "seller_offer_redirect_url": "https://example.com/foo",
  • "seller_offer_reference": "ref-1234",
  • "shipping": {
    },
  • "shipping_address": {
    },
  • "status": "voided"
}

Validate an offer

Validates the input for creating a topi offer. This endpoint does not create an offer. It can be used to check in advance if an offer can be created with certain products in the cart or if a shipping method is supported, etc.

Returns a HTTP 200 on success.

The request returns an HTTP Unprocessable Entity in the following scenarios:

  • When "lines" is an empty array.
  • When "lines" contains any products that are not available in the topi catalog
  • When the "seller_offer_reference" is reusing a value of an offer that is currently active

When using in the Sandbox

The following seller offer references are considered to be "active":

  • "ref-1234"

The following seller product references are considered to be available in the catalog:

  • {"source": "sap", "reference": "123"}
  • {"source": "sap", "reference": "456"}
  • {"source": "sku", "reference": "123abc"}

The following seller product references are considered to be available in the catalog but not supported:

  • {"source": "sku", "reference": "unsupported-1"}

The following shipping reference is considered to be available but not supported:

  • "unsupported-shipping-reference"
Authorizations:
OAuth2Seller_header_Authorization
Request Body schema: application/json
required
Accept-Language
string
object (CustomerInfo)

Customer information

draft_offer_id
string

The ID of the draft offer from which an offer is being created

exit_redirect
string <uri>

URL to redirect to when something went wrong along the process. We will add the following parameters to the query string: offer_id, seller_offer_reference

expires_at
required
string <date-time>

Expiration date and time for the offer (UTC)

required
Array of objects (OfferLinePayload) non-empty

List of product lines

object

Metadata you can attach to and offer. You can store here any JSON information

object (SalesAgent)

Sales agent related to an offer

sales_channel
required
string
Enum: "telesales" "ecommerce" "in_store_pos"

Channel from where the offer is created

seller_offer_reference
required
string

Seller's own reference for the offer

object (ShippingInfo)

Shipping information

object (ShippingAddress)

Shipping Address. If the sales_channel is ecommerce, this field will be required

success_redirect
string <uri>

URL to redirect to when the user finishes the checkout in topi. We will add the following parameters to the query string: offer_id, seller_offer_reference, order_id

Responses

Request samples

Content type
application/json
{
  • "Accept-Language": "abc123",
  • "customer": {
    },
  • "draft_offer_id": "abc123",
  • "exit_redirect": "https://example.com/foo",
  • "expires_at": "1970-01-01T00:00:01Z",
  • "lines": [
    ],
  • "metadata": {
    },
  • "sales_agent": {
    },
  • "sales_channel": "ecommerce",
  • "seller_offer_reference": "ref-1234",
  • "shipping": {
    },
  • "shipping_address": {
    },
  • "success_redirect": "https://example.com/foo"
}

Response samples

Content type
application/json
{
  • "pricing_overview": {
    }
}

order

Provides operations to handle orders for end-customers.

Webhooks

We will ping the URL provided whenever an order has changed its status to: "created", "partially_fulfilled", "completed", "canceled", or "rejected".

Payload:

  • Available fields:

    • id: string
    • assets: array of Asset
    • metadata: object
    • offer_id: string
    • seller_offer_reference: string
    • status: string enum
    • shipping_address: ShippingAddress

    ShippingAddress contains this fields:

    • name: string
    • line1: string
    • line2: string
    • postal_code: string
    • city: string
    • region: string
    • country_code: string

List all orders (deprecated) Deprecated

Returns a list of created orders, filterable by query or created_by. (deprecated)

This method is deprecated. Please use List all orders with pagination instead.

Authorizations:
OAuth2Seller_header_Authorization
query Parameters
query
string
Examples:
  • query=status - default

Search query. It can be a string or a number or both

created_by
string
Example: created_by=sales-agent@example.com,anothergreatone@example.com

a comma-separated list of sales agents emails

partners_only
boolean
Example: partners_only=false

a boolean indicating whether to retrieve orders from partner sellers only

Responses

Request samples 

curl -X GET https://seller-api.topi.eu/v1/orders \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response samples

Content type
application/json
{
  • "orders": [
    ]
}

Retrieve an order

Returns a single order.

When using in the Sandbox

Use the following ID's to get different fixtures. Remember that the URL must be encoded:

  • Status "created": "52c1e8ec-a592-48a9-b574-ab88b0937b38"
  • Status "confirmed": "aac1e833-3391-134a-c567-acd8b0937ad3"
  • Status "partially_fulfilled": "b3a64e36-6fa2-40a6-9402-e949c47feb87"
  • Status "completed": "aa6a50f4-c2d4-4961-9689-ebd0f0f92a9e"
  • Status "canceled": "17c45c3d-cd61-4e2f-a562-ff8f349067de"

Any other ID will return an HTTP 404 error.

Authorizations:
OAuth2Seller_header_Authorization
path Parameters
id
required
string <regexp> ^[0-9A-Za-z\-]+$
Example: 739b63c2-9e58-4964-b38d-4ebb424de242

topi order ID

Responses

Request samples 

curl -X GET https://seller-api.topi.eu/v1/orders/{id} \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response samples

Content type
application/json
{
  • "assets": [
    ],
  • "canceled_at": "1970-01-01T00:00:01Z",
  • "created_at": "1970-01-01T00:00:01Z",
  • "customer_info": {
    },
  • "id": "739b63c2-9e58-4964-b38d-4ebb424de242",
  • "metadata": {
    },
  • "offer_created_at": "1970-01-01T00:00:01Z",
  • "offer_id": "739b63c2-9e58-4964-b38d-4ebb424de242",
  • "order_lines": [
    ],
  • "sales_agent": {
    },
  • "seller_info": {
    },
  • "seller_offer_reference": "abc123",
  • "shipping_address": {
    },
  • "shipping_info": {
    },
  • "status": "confirmed",
  • "tracking_urls": [
    ]
}

Set metadata on an order

Sets arbitrary JSON metadata on an order.

Authorizations:
OAuth2Seller_header_Authorization
path Parameters
id
required
string <regexp> ^[0-9A-Za-z\-]+$
Example: 739b63c2-9e58-4964-b38d-4ebb424de242

topi order ID

Request Body schema: application/json
required
required
object

Metadata to attach. You can store any JSON information.

property name*
additional property
string <= 400 characters

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "assets": [
    ],
  • "id": "739b63c2-9e58-4964-b38d-4ebb424de242",
  • "metadata": {
    },
  • "offer_id": "739b63c2-9e58-4964-b38d-4ebb424de242",
  • "seller_offer_reference": "abc123",
  • "status": "confirmed"
}

Confirm an order

Sets the status of an existing order to "confirmed". You can only accept orders that have been in the status "created" or "acknowledged".

Authorizations:
OAuth2Seller_header_Authorization
path Parameters
id
required
string <regexp> ^[0-9A-Za-z\-]+$
Example: 739b63c2-9e58-4964-b38d-4ebb424de242

topi order ID

Responses

Request samples 

curl -X POST https://seller-api.topi.eu/v1/orders/{id}/accept \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response samples

Content type
application/json
{
  • "assets": [
    ],
  • "id": "739b63c2-9e58-4964-b38d-4ebb424de242",
  • "metadata": {
    },
  • "offer_id": "739b63c2-9e58-4964-b38d-4ebb424de242",
  • "seller_offer_reference": "abc123",
  • "status": "confirmed"
}

Acknowledge an order

Sets the status of an existing order to "acknowledged". You can only acknowledge orders that have been in the status "created".

Authorizations:
OAuth2Seller_header_Authorization
path Parameters
id
required
string <regexp> ^[0-9A-Za-z\-]+$
Example: 739b63c2-9e58-4964-b38d-4ebb424de242

topi order ID

Responses

Request samples 

curl -X POST https://seller-api.topi.eu/v1/orders/{id}/acknowledge \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response samples

Content type
application/json
{
  • "assets": [
    ],
  • "id": "739b63c2-9e58-4964-b38d-4ebb424de242",
  • "metadata": {
    },
  • "offer_id": "739b63c2-9e58-4964-b38d-4ebb424de242",
  • "seller_offer_reference": "abc123",
  • "status": "confirmed"
}

Reject an order

Sets the status of an existing order to "rejected". You can only reject orders that have been in the status "created" or "acknowledged".

Authorizations:
OAuth2Seller_header_Authorization
path Parameters
id
required
string <regexp> ^[0-9A-Za-z\-]+$
Example: 739b63c2-9e58-4964-b38d-4ebb424de242

topi order ID

Responses

Request samples 

curl -X POST https://seller-api.topi.eu/v1/orders/{id}/reject \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response samples

Content type
application/json
{
  • "assets": [
    ],
  • "id": "739b63c2-9e58-4964-b38d-4ebb424de242",
  • "metadata": {
    },
  • "offer_id": "739b63c2-9e58-4964-b38d-4ebb424de242",
  • "seller_offer_reference": "abc123",
  • "status": "confirmed"
}

List all orders with pagination

Returns a list of created orders with pagination, filterable by query or created_by. Supports offset-based pagination (page/limit) and range filters for efficient data traversal.

Recommended approach for paginating over all data: Use ID range filters with limit=100. The ID range filter (id_gt) works like cursor-based pagination, providing the most efficient way to iterate through the complete dataset. Pass the last ID from the previous page as id_gt to fetch the next batch.

Examples:

  • First page: ?limit=100
  • Next page: ?id_gt=&limit=100
  • Time-based sync: ?created_at_gt=&limit=100
Authorizations:
OAuth2Seller_header_Authorization
query Parameters
limit
integer <int64>
Example: limit=1

the size of the page

page
integer <int64>
Example: page=1

the index of the page

query
string
Examples:
  • query=status - default

Search query. It can be a string or a number or both

created_by
string
Example: created_by=sales-agent@example.com,anothergreatone@example.com

a comma-separated list of sales agents emails

partners_only
boolean
Example: partners_only=false

a boolean indicating whether to retrieve orders from partner sellers only

sort_by
string
Default: "created_at"
Value: "created_at"
Example: sort_by=created_at

Field to sort by

sort_order
string
Default: "asc"
Enum: "asc" "desc"
Example: sort_order=desc

Sort direction

id_gt
string <uuid>
Example: id_gt=550e8400-e29b-41d4-a716-446655440000

Filter: order ID > value (UUID)

id_gte
string <uuid>
Example: id_gte=550e8400-e29b-41d4-a716-446655440000

Filter: order ID >= value (UUID)

id_lt
string <uuid>
Example: id_lt=550e8400-e29b-41d4-a716-446655440000

Filter: order ID < value (UUID)

id_lte
string <uuid>
Example: id_lte=550e8400-e29b-41d4-a716-446655440000

Filter: order ID <= value (UUID)

created_at_gt
string <date-time>
Example: created_at_gt=2025-01-01T00:00:00Z

Filter: order created_at > value (RFC3339)

created_at_gte
string <date-time>
Example: created_at_gte=2025-01-01T00:00:00Z

Filter: order created_at >= value (RFC3339)

created_at_lt
string <date-time>
Example: created_at_lt=2025-12-31T23:59:59Z

Filter: order created_at < value (RFC3339)

created_at_lte
string <date-time>
Example: created_at_lte=2025-12-31T23:59:59Z

Filter: order created_at <= value (RFC3339)

Responses

Request samples 

curl -X GET https://seller-api.topi.eu/v1/orders/paginated \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response samples

Content type
application/json
{
  • "orders": [
    ],
  • "pagination": {
    }
}

shipment

Assets without serial numbers

Some assets might not have a serial number (e.g. accessories). In order to send them with the shipment, explicitly pass an empty string "" as the serial_number for this asset.

Note, that every asset, that has a rent option, requires a serial number even if it has been directly purchased. The request will fail with an according message if such a serial number is missing.

Also note, that every item of an order has to be shipped for the order to be completed. This can be done in multiple shipments.

Create a shipment

Add shipment info for an order. Partial shipments are allowed and will update the order status to "partially_fulfilled". All items must have shipment info before an order is considered "completed".

Authorizations:
OAuth2Seller_header_Authorization
Request Body schema: application/json
required
object

Metadata that you can attach to an order. You can store any JSON information.

order_id
required
string <regexp> ^[0-9A-Za-z\-]+$

topi order ID

required
Array of objects (SerialNumberByAsset)

The products' serial numbers to register

tracking_url
string <uri>

The tracking URL of the asset

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "order_id": "739b63c2-9e58-4964-b38d-4ebb424de242",
  • "serial_numbers": [
    ],
  • "tracking_url": "https://example.com/foo"
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "serial_numbers": [
    ],
  • "tracking_url": "https://example.com/foo"
}

shippingMethod

Provides operations to handle shipping-related tasks.

Get all shipping methods

Get all shipping methods

Authorizations:
OAuth2Seller_header_Authorization
query Parameters
page
integer <int64>
Default: 0
Example: page=0

Which page number to fetch (zero-indexed)

Responses

Request samples 

curl -X GET https://seller-api.topi.eu/v1/shipping-method \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Create shipping method

Creates a shipping method. This is global for all the offers.

Returns HTTP 200 plus basic information about the newly created shipping method.

The request returns an HTTP Unprocessable Entity when the provided "seller_shipping_method_reference" is not unique.

When using in the Sandbox

The following seller shipping method references are considered to be available and will make the API return an HTTP Unprocessable Entity error.

  • "Bridges"

Note: The sandbox will always return the same fixture regardless of the payload provided.

Authorizations:
OAuth2Seller_header_Authorization
Request Body schema: application/json
required
is_in_store_pickup
boolean

Is this shipping method in store pickup

name
string

Name for the shipping method.

seller_shipping_method_reference
required
string

Seller's own reference for this shipping method.

Responses

Request samples

Content type
application/json
{
  • "is_in_store_pickup": true,
  • "name": "United Parcel Service",
  • "seller_shipping_method_reference": "Sandbox Shipping Service"
}

Response samples

Content type
application/json
{
  • "id": "739b63c2-9e58-4964-b38d-4ebb424de242",
  • "is_in_store_pickup": true,
  • "name": "United Parcel Service",
  • "seller_shipping_method_reference": "Sandbox Shipping Service",
  • "supported": true
}