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

Get rental overview for products

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

Quantity of this product.

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

Responses

Response Schema: application/json
can_checkout
boolean

Indicates whether the entire collection of products can be checked out with topi or not. If there is an unsupported product, then this will be false

currency
string
Value: "EUR"
Array of objects (CartProductRentalOverview)
total_rental_amount
integer <int64>

Sum of all recommended net rental amounts. Only present when all supplied products have rental terms.

total_rental_summary
string

A string representing the minimum total rental amount for the entire topi basket, which can be directly rendered on the cart page.

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

Retrieve product categorization information

get categorisation information for populating frontend dropdowns

Authorizations:
OAuth2Seller_header_Authorization

Responses

Response Schema: application/json
Array
id
required
string
node_type
required
string

The kind of node, such as manufacturer, category, device.

children
Array of objects (CategorisationNode)

The value to return to the Backend from this node if chosen in frontend.

label
string

The label to display in the frontend.

parameter
string

The parameter to evaluate on, if the node is an evaluation node (nodetype = topLow).

threshold
integer <int64>

The tipping point from where the category goes from 'low' to 'top'.

value
string

The value to return to the Backend from this node if chosen in frontend.

Request samples 

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

Response samples

Content type
application/json
[
  • {
    }
]

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
source
required
string non-empty

The seller internal source name for this reference type.

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

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

Responses

Response Schema: application/json
required
Array of objects (ProductSummary)

Array of product summaries, detailing each product's specifications and available contract terms.

Array
required
object (SellerProductReference)
id
required
string <regexp> ^[0-9A-Za-z\-]+$

topi product's ID.

is_supported
required
boolean

Indicates whether the product is supported to be in a topi basket.

required
object (ContractTermsSummary)

Request samples

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

Response samples

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

Add a custom product

Add a single custom product to the catalog

Authorizations:
OAuth2Seller_header_Authorization
Request Body schema: application/json
required
required
object (CustomProduct)
title
required
string

Title of the product.

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

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

required
object (MoneyAmountWithOptionalGross)
manufacturer
required
string

Name of the product's manufacturer.

description
required
string <= 2000 characters

Detailed description of the product.

required
object (CategorisationIdentifiers)
object (MoneyAmountWithOptionalGross)
Array of objects (ProductStandardIdentifier)

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

Responses

Response Schema: application/json
id
required
string <regexp> ^[0-9A-Za-z\-]+$

The id of the import processing

status
required
string
Enum: "created" "started" "completed" "failed"

The current import status.

object (SummaryInfo)

Request samples

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

Response samples

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

Remove custom product

delete a single custom product from the catalog

Authorizations:
OAuth2Seller_header_Authorization
path Parameters
id
required
string
Example: abc123

The productId of the product to remove

Responses

Request samples 

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

Response samples

Content type
application/json
"abc123"

edit an out of catalog product

Edit an out of catalog product

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

topi ID for the product

Request Body schema: application/json
required
required
object (CustomProduct)
title
required
string

Title of the product.

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

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

required
object (MoneyAmountWithOptionalGross)
manufacturer
required
string

Name of the product's manufacturer.

description
required
string <= 2000 characters

Detailed description of the product.

required
object (CategorisationIdentifiers)
object (MoneyAmountWithOptionalGross)
Array of objects (ProductStandardIdentifier)

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

Responses

Response Schema: application/json
product_id
required
string <regexp> ^[0-9A-Za-z\-]+$

Product ID

required
object (MoneyAmount)
title
required
string

Title of the product.

required
Array of objects (SellerProductReference)

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

required
object (ContractTermsSummary)
reference
required
string

The product reference number that matches a search term.

origin
required
string

The origin of the product, 'manual','automatic' or 'central_catalog'.

manufacturer
required
string

The manufacturer of the product.

archived
boolean

Whether or not the product has been archived by the seller.

object (MoneyAmount)
object (CategorisationIdentifiers)
description
string

Detailed description of the product.

ean
string

The EAN code of the product.

mpn
string

The MPN code of the product.

pretty_id
string

The pretty id/reference that the seller filled. Can be a non-unique dummy id.

pricing_category
string

The pricing category of the product.

subtitle
string

Subtitle of the product.

Request samples

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

Response samples

Content type
application/json
{
  • "archived": false,
  • "available_contract_terms": {
    },
  • "base_rental_price": {
    },
  • "categorisation_identifiers": {
    },
  • "description": "abc123",
  • "ean": "abc123",
  • "list_price": {
    },
  • "manufacturer": "abc123",
  • "mpn": "abc123",
  • "origin": "abc123",
  • "pretty_id": "abc123",
  • "pricing_category": "abc123",
  • "product_id": "739b63c2-9e58-4964-b38d-4ebb424de242",
  • "reference": "abc123",
  • "seller_product_references": [
    ],
  • "subtitle": "abc123",
  • "title": "abc123"
}

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)
title
required
string

Title of the product.

required
Array of objects (SellerProductReference) non-empty

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

required
object (MoneyAmountWithOptionalTax)
is_active
required
boolean

Indicates if the product is currently active.

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

Name of the product's manufacturer.

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.

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.

Responses

Response Schema: application/json
id
required
string <regexp> ^[0-9A-Za-z\-]+$

The id of the import processing

status
required
string
Enum: "created" "started" "completed" "failed"

The current import status.

object (SummaryInfo)

Request samples

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

Response samples

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

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
required
object (SellerProductReference)
object (MoneyAmountWithOptionalTax)
object (MoneyAmountWithOptionalTax)

Responses

Response Schema: application/json
Array
required
object (SellerProductReference)
has_rental_terms
required
boolean

Does the product have rental terms.

currency
string
Value: "EUR"
monthly_rental_amount
integer <int64>

The Net monthly rental amount, in cents. This amount is exclusive of tax.

object (RentContractTerm)
summary
string

A string that can be directly rendered in the page about whether topi is available.

Request samples

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

Response samples

Content type
application/json
[
  • {
    }
]

parseOfferText catalog

Parse offer content provided as text

Authorizations:
OAuth2Seller_header_Authorization
Request Body schema: application/json
required
source_text
required
string

Responses

Response Schema: application/json
Array of objects (OfferParsinglineItem)

The line items contained within the uploaded pdf offer.

offer_reference
string

the seller-facing offer reference, most likely coming from the ERP system

Array of objects (OfferParsingUnproccesedItem)

The line items that could not be processed.

Request samples

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

Response samples

Content type
application/json
{
  • "line_items": [
    ],
  • "offer_reference": "abc123",
  • "unprocessed_items": [
    ]
}

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)
required
object (SellerProductReference)
object (MoneyAmountWithOptionalTax)
object (MoneyAmountWithOptionalTax)

Responses

Response Schema: application/json
summary
required
string

A string that can be rendered in the page about whether topi is available.

is_supported
required
boolean

Whether the product can be checked out through topi at all

available_contract_types
required
Array of strings
Items Enum: "pay_now" "rent"

The available ways in which this product can be checked out via topi.

object (PayNowContractTerm)
Array of objects (RentContractTerm)

Details of all rental options available for the product.

Array of objects (BaseCalculatePriceSummary)

Pricing summaries for each service item bundled with this main product. Sublines provide detailed pricing breakdown for individual services within a bundle.

    Business Rules:
    - Each subline summary contains complete pricing information for a service component
    - Sublines inherit contract terms and quantities from the parent product
    - Pricing calculations include both rental and purchase options where applicable
    - Sublines maintain separate pricing while contributing to bundle totals
    - Service-category validation ensures only appropriate products are included
    
    Example: Pricing summary for a smartphone bundle showing individual costs for screen protection service, and data migration service

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

Response Schema: application/json
Array
product_id
required
string <regexp> ^[0-9A-Za-z\-]+$

Product ID

required
object (MoneyAmount)
title
required
string

Title of the product.

required
Array of objects (SellerProductReference)

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

required
object (ContractTermsSummary)
reference
required
string

The product reference number that matches a search term.

origin
required
string

The origin of the product, 'manual','automatic' or 'central_catalog'.

manufacturer
required
string

The manufacturer of the product.

archived
boolean

Whether or not the product has been archived by the seller.

object (MoneyAmount)
description
string

Detailed description of the product.

ean
string

The EAN code of the product.

mpn
string

The MPN code of the product.

pretty_id
string

The pretty id/reference that the seller filled. Can be a non-unique dummy id.

pricing_category
string

The pricing category of the product.

subtitle
string

Subtitle of the product.

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

Response Schema: application/json
limit
integer <int64>

the size of the page

page
integer <int64>

the index of the page

Array of objects (SearchProductResult)

The products returned.

totalPages
integer <int64>

Total amount of pages available

totalRows
integer <int64>

The total amount of rows

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

Response Schema: application/json
limit
integer <int64>

the size of the page

page
integer <int64>

the index of the page

Array of objects (SearchProductResult)

The products returned.

totalPages
integer <int64>

Total amount of pages available

totalRows
integer <int64>

The total amount of rows

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
}

Get services for a seller

get services for a seller

Authorizations:
OAuth2Seller_header_Authorization
query Parameters
limit
integer <int64>
Default: 5
Example: limit=1

The number of services to return

Responses

Response Schema: application/json
Array
product_id
required
string <regexp> ^[0-9A-Za-z\-]+$

Product ID

required
object (MoneyAmount)
title
required
string

Title of the product.

required
Array of objects (SellerProductReference)

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

required
object (ContractTermsSummary)
reference
required
string

The product reference number that matches a search term.

origin
required
string

The origin of the product, 'manual','automatic' or 'central_catalog'.

manufacturer
required
string

The manufacturer of the product.

archived
boolean

Whether or not the product has been archived by the seller.

object (MoneyAmount)
description
string

Detailed description of the product.

ean
string

The EAN code of the product.

mpn
string

The MPN code of the product.

pretty_id
string

The pretty id/reference that the seller filled. Can be a non-unique dummy id.

pricing_category
string

The pricing category of the product.

subtitle
string

Subtitle of the product.

Request samples 

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

Response samples

Content type
application/json
[
  • {
    }
]

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

Lists the offers created by the calling seller, with filters or query

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

Response Schema: application/json
Array
id
required
string <regexp> ^[0-9A-Za-z\-]+$

topi offer ID

created_at
required
string <date-time>
expires_at
required
string <date-time>
checkout_redirect_url
required
string <uri>
seller_offer_redirect_url
required
string <uri>
status
required
string
Enum: "created" "voided" "accepted" "expired" "rejected" "pending_review" "declined"
required
object (CustomerInfo)

Customer information

seller_offer_reference
required
string

Seller's own reference for the offer

required
object (ShippingAddress)

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

required
Array of objects (OfferLineResult)

List of product lines

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

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

object (PricingOverview)

An Overview of the total price to pay by the user using topi.

object (SalesAgent)

Sales agent related to an offer

object (ShippingInfo)

Shipping information

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
seller_offer_reference
required
string

Seller's own reference for the offer

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

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

Channel from where the offer is created

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

object

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

object (SalesAgent)

Sales agent related to an 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

Response Schema: application/json
id
required
string <regexp> ^[0-9A-Za-z\-]+$

topi offer ID

created_at
required
string <date-time>
expires_at
required
string <date-time>
checkout_redirect_url
required
string <uri>
seller_offer_redirect_url
required
string <uri>
status
required
string
Enum: "created" "voided" "accepted" "expired" "rejected" "pending_review" "declined"
required
object (CustomerInfo)

Customer information

seller_offer_reference
required
string

Seller's own reference for the offer

required
object (ShippingAddress)

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

required
Array of objects (OfferLineResult)

List of product lines

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

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

object (PricingOverview)

An Overview of the total price to pay by the user using topi.

object (SalesAgent)

Sales agent related to an offer

object (ShippingInfo)

Shipping information

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

Response Schema: application/json
id
required
string <regexp> ^[0-9A-Za-z\-]+$

topi offer ID

created_at
required
string <date-time>
expires_at
required
string <date-time>
checkout_redirect_url
required
string <uri>
seller_offer_redirect_url
required
string <uri>
status
required
string
Enum: "created" "voided" "accepted" "expired" "rejected" "pending_review" "declined"
required
object (CustomerInfo)

Customer information

seller_offer_reference
required
string

Seller's own reference for the offer

required
object (ShippingAddress)

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

required
Array of objects (OfferLineResult)

List of product lines

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

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

object (PricingOverview)

An Overview of the total price to pay by the user using topi.

object (SalesAgent)

Sales agent related to an offer

object (ShippingInfo)

Shipping information

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
seller_offer_reference
required
string

Seller's own reference for the offer

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

List of product lines

sales_channel
required
string
Enum: "telesales" "ecommerce" "in_store_pos"
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>
object

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

object (SalesAgent)

Sales agent related to an 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

Response Schema: application/json
id
required
string <regexp> ^[0-9A-Za-z\-]+$

topi offer ID

created_at
required
string <date-time>
expires_at
required
string <date-time>
checkout_redirect_url
required
string <uri>
seller_offer_redirect_url
required
string <uri>
status
required
string
Enum: "created" "voided" "accepted" "expired" "rejected" "pending_review" "declined"
required
object (CustomerInfo)

Customer information

seller_offer_reference
required
string

Seller's own reference for the offer

required
object (ShippingAddress)

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

required
Array of objects (OfferLineResult)

List of product lines

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

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

object (PricingOverview)

An Overview of the total price to pay by the user using topi.

object (SalesAgent)

Sales agent related to an offer

object (ShippingInfo)

Shipping information

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

Response Schema: application/json
id
required
string <regexp> ^[0-9A-Za-z\-]+$

topi offer ID

created_at
required
string <date-time>
expires_at
required
string <date-time>
checkout_redirect_url
required
string <uri>
seller_offer_redirect_url
required
string <uri>
status
required
string
Enum: "created" "voided" "accepted" "expired" "rejected" "pending_review" "declined"
required
object (CustomerInfo)

Customer information

seller_offer_reference
required
string

Seller's own reference for the offer

required
object (ShippingAddress)

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

required
Array of objects (OfferLineResult)

List of product lines

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

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

object (PricingOverview)

An Overview of the total price to pay by the user using topi.

object (SalesAgent)

Sales agent related to an offer

object (ShippingInfo)

Shipping information

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

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
required
object (SalesAgent)

Sales agent related to an offer

seller_offer_reference
required
string

Seller's own reference for the offer

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

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

Channel from where the offer is created

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

object

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

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

Response Schema: application/json
id
required
string <regexp> ^[0-9A-Za-z\-]+$

topi offer ID

created_at
required
string <date-time>
expires_at
required
string <date-time>
checkout_redirect_url
required
string <uri>
seller_offer_redirect_url
required
string <uri>
status
required
string
Enum: "created" "voided" "accepted" "expired" "rejected" "pending_review" "declined"
required
object (CustomerInfo)

Customer information

seller_offer_reference
required
string

Seller's own reference for the offer

required
object (ShippingAddress)

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

required
Array of objects (OfferLineResult)

List of product lines

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

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

object (PricingOverview)

An Overview of the total price to pay by the user using topi.

object (SalesAgent)

Sales agent related to an offer

object (ShippingInfo)

Shipping information

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

Response Schema: application/json
seller_offer_reference
required
string

Seller's own reference for the offer

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

topi offer ID

created_at
required
string <date-time>
expires_at
required
string <date-time>
checkout_redirect_url
required
string <uri>
seller_offer_redirect_url
required
string <uri>
status
required
string
Enum: "created" "voided" "accepted" "expired" "rejected" "pending_review" "declined"
required
object (CustomerInfo)

Customer information

required
object (ShippingAddress)

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

required
Array of objects (OfferLineResult)

List of product lines

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

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

object (PricingOverview)

An Overview of the total price to pay by the user using topi.

object (SalesAgent)

Sales agent related to an offer

object (ShippingInfo)

Shipping information

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
seller_offer_reference
required
string

Seller's own reference for the offer

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

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

Channel from where the offer is created

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

object

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

object (SalesAgent)

Sales agent related to an 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

Response Schema: application/json
required
object (PricingOverview)

An Overview of the total price to pay by the user using topi.

required
object (MoneyAmount)
required
object (MoneyAmount)
required
Array of objects (BreakdownLine)

Different lines with the different items that are important for the payment.

Array of objects (ItemSummary)

Price summary for each item: main line and sublines.

object (MoneyAmount)

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:

  • same as show order
    • id: string
    • assets: array of Asset
    • metadata: object
    • offer_id: string
    • seller_offer_reference: string
    • status: string enum

List all orders

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

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

Response Schema: application/json
Array of objects (OrderSummary)

an array with the orders requested

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

topi order ID

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

Reference to the topi offer ID

created_at
required
string <date-time>
agent_name
required
string

Agent owner of the order

seller_offer_reference
required
string

Agent owner of the order

status
required
string
Enum: "created" "confirmed" "acknowledged" "accepted" "partially_fulfilled" "completed" "canceled" "rejected"
company_name
required
string

name of the customer company

full_name
required
string

Full name of the customer

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

Response Schema: application/json
created_at
required
string <date-time>
offer_created_at
required
string <date-time>
required
object (CustomerInfo)

Customer information

required
object (ShippingAddress)

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

required
Array of objects (OrderLineItem)

A list of order lines in an order

tracking_urls
required
Array of strings

All the tracking urls

required
object (SellerInfo)
id
required
string <regexp> ^[0-9A-Za-z\-]+$

topi order ID

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

Reference to the topi offer ID

seller_offer_reference
required
string

Seller's own reference for this order

status
required
string
Enum: "created" "confirmed" "acknowledged" "accepted" "partially_fulfilled" "completed" "canceled" "rejected"
required
Array of objects (Asset)

A list of assets in an offer

canceled_at
string <date-time>
object

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

object (SalesAgent)

Sales agent related to an offer

object (ShippingInfo)

Shipping information

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

Response Schema: application/json
id
required
string <regexp> ^[0-9A-Za-z\-]+$

topi order ID

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

Reference to the topi offer ID

seller_offer_reference
required
string

Seller's own reference for this order

status
required
string
Enum: "created" "confirmed" "acknowledged" "accepted" "partially_fulfilled" "completed" "canceled" "rejected"
required
Array of objects (Asset)

A list of assets in an offer

object

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

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

Response Schema: application/json
id
required
string <regexp> ^[0-9A-Za-z\-]+$

topi order ID

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

Reference to the topi offer ID

seller_offer_reference
required
string

Seller's own reference for this order

status
required
string
Enum: "created" "confirmed" "acknowledged" "accepted" "partially_fulfilled" "completed" "canceled" "rejected"
required
Array of objects (Asset)

A list of assets in an offer

object

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

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

Response Schema: application/json
id
required
string <regexp> ^[0-9A-Za-z\-]+$

topi order ID

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

Reference to the topi offer ID

seller_offer_reference
required
string

Seller's own reference for this order

status
required
string
Enum: "created" "confirmed" "acknowledged" "accepted" "partially_fulfilled" "completed" "canceled" "rejected"
required
Array of objects (Asset)

A list of assets in an offer

object

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

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

Response Schema: application/json
id
required
string <regexp> ^[0-9A-Za-z\-]+$

topi order ID

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

Reference to the topi offer ID

seller_offer_reference
required
string

Seller's own reference for this order

status
required
string
Enum: "created" "confirmed" "acknowledged" "accepted" "partially_fulfilled" "completed" "canceled" "rejected"
required
Array of objects (Asset)

A list of assets in an offer

object

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

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

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
order_id
required
string <regexp> ^[0-9A-Za-z\-]+$

topi order ID

required
Array of objects (SerialNumberByAsset)

The products' serial numbers to register

object

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

tracking_url
string <uri>

The tracking URL of the asset

Responses

Response Schema: application/json
required
Array of objects (SerialNumberByAsset)

The products' serial numbers to register

object

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

tracking_url
string <uri>

The tracking URL of the asset

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

Response Schema: application/json
required
Array of objects (ShippingMethodResult)

Array of ShippingMethodResult

required
object (PageMetadata)

Metadata about the returned page

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
seller_shipping_method_reference
required
string

Seller's own reference for this shipping method.

is_in_store_pickup
boolean

Is this shipping method in store pickup

name
string

Name for the shipping method.

Responses

Response Schema: application/json
id
required
string <regexp> ^[0-9A-Za-z\-]+$

topi shipping method ID.

seller_shipping_method_reference
required
string

Seller's own reference for this shipping method.

supported
required
boolean

Supported shipping method.

is_in_store_pickup
boolean

Is this shipping method in store pickup

name
string

Name for the shipping method.

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
}