openapi: 3.0.3 info: title: topi Seller API description: > # Localization Strings returned can be localized when the _Accept-Language_ header is provided in the request. It should follow the [RFC-2616 convention](http://www.ietf.org/rfc/rfc2616.txt). version: 1.0.0 servers: - url: https://seller-api-sandbox.topi-sandbox.eu - url: https://seller-api.topi.eu - url: https://seller-api.topi-staging.eu - url: https://seller-api-sandbox.topi-sandbox-staging.eu paths: /v1/catalog/basket/pricing: post: tags: - catalog summary: Calculate pricing for a whole basket description: >- ## *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 operationId: catalog#calculateBasketPricing requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CalculateBasketPricingRequestBody' example: pricing_requests: - base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 identifier: abc123 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 quantity: 1 seller_product_reference: reference: 123ab-5343 source: sap sublines: - base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 seller_product_reference: reference: 123ab-5343 source: sap responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/CalculateBasketPricingResponseBody' example: basket_total_pay_now: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 basket_total_rent: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summaries: - available_contract_types: - rent default_tenure: 1 identifier: abc123 is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 pay_now_excluding_sublines: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 rent_excluding_sublines: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 sublines: - available_contract_types: - rent default_tenure: 1 identifier: abc123 is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summary: Rent with topi for €24.32/month total_pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 total_rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summary: Rent with topi for €24.32/month total_pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 total_rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '404': description: 'NotFound: Not Found response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '422': description: 'Unprocessable: Unprocessable Entity response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-catalog:read x-code-samples: - lang: curl label: cURL source: | curl -X POST https://seller-api.topi.eu/v1/catalog/basket/pricing \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "pricing_requests": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "identifier": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "quantity": 1, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "sublines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" } } ] } ] }' - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/catalog/basket/pricing', { method: 'POST', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ "pricing_requests": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "identifier": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "quantity": 1, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "sublines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" } } ] } ] }) }); const data = await response.json(); console.log(data); /v1/catalog/carts/rental-overview: post: tags: - catalog summary: Get rental overview for products operationId: catalog#cartRentalOverview requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CartRentalOverviewRequestBody' example: products: - base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 quantity: 1 seller_product_reference: reference: 123ab-5343 source: sap responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/CartRentalOverviewResult' example: can_checkout: false currency: EUR product_prices: - available_rental_terms: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 can_checkout: false currency: EUR has_rental_terms: false quantity: 1 seller_product_reference: reference: 123ab-5343 source: sap summary: Rent with topi from €23.45/month total_rental_amount: 1 total_rental_amount: 1 total_rental_summary: Rent with topi from €123.45/month '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 security: - OAuth2Seller_header_Authorization: - seller-catalog:read x-code-samples: - lang: curl label: cURL source: > curl -X POST https://seller-api.topi.eu/v1/catalog/carts/rental-overview \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "products": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "quantity": 1, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" } } ] }' - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/catalog/carts/rental-overview', { method: 'POST', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ "products": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "quantity": 1, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" } } ] }) }); const data = await response.json(); console.log(data); /v1/catalog/check-supported: post: tags: - catalog summary: Check if products are supported description: > 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. operationId: catalog#checkSupported requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CheckSupportedRequestBody' example: seller_product_references: - reference: 123ab-5343 source: sap responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/ProductsSummary' example: products: - available_contract_terms: can_pay_now: false can_rent: false rent: duration: 1 id: 739b63c2-9e58-4964-b38d-4ebb424de242 is_supported: false seller_product_reference: reference: 123ab-5343 source: sap '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 security: - OAuth2Seller_header_Authorization: - seller-catalog:read x-code-samples: - lang: curl label: cURL source: | curl -X POST https://seller-api.topi.eu/v1/catalog/check-supported \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "seller_product_references": [ { "reference": "123ab-5343", "source": "sap" } ] }' - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/catalog/check-supported', { method: 'POST', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ "seller_product_references": [ { "reference": "123ab-5343", "source": "sap" } ] }) }); const data = await response.json(); console.log(data); /v1/catalog/import: post: tags: - catalog summary: Import products into the catalog description: > 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` operationId: catalog#importCatalog requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ImportCatalogRequestBody' example: products: - base_rental_price: currency: EUR gross: 119000 net: 100000 description: aaa extra_details: - property: memory value: 16GB DDR5 image: url: https://example.com/foo is_active: false manufacturer: abc123 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 product_standard_identifiers: - id: 123ab-4567 identifier_type: EAN seller_categories: - id: abc123 name: abc123 parent_category_id: abc123 seller_product_references: - reference: 123ab-5343 source: sap - reference: 123ab-5343 source: sap seller_product_type: software shop_product_description_url: https://example.com/foo subtitle: abc123 title: abc123 - base_rental_price: currency: EUR gross: 119000 net: 100000 description: aaa extra_details: - property: memory value: 16GB DDR5 image: url: https://example.com/foo is_active: false manufacturer: abc123 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 product_standard_identifiers: - id: 123ab-4567 identifier_type: EAN seller_categories: - id: abc123 name: abc123 parent_category_id: abc123 seller_product_references: - reference: 123ab-5343 source: sap - reference: 123ab-5343 source: sap seller_product_type: software shop_product_description_url: https://example.com/foo subtitle: abc123 title: abc123 responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/ImportResult' example: id: 739b63c2-9e58-4964-b38d-4ebb424de242 status: started summary: sample_products_rejected: - error_code: unsupported_product error_description: the product type is not supported seller_product_reference: reference: 123ab-5343 source: sap total_products: 1 total_products_imported: 1 total_products_rejected: 1 '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '413': description: 'TooManyProducts: Request Entity Too Large response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '422': description: 'Unprocessable: Unprocessable Entity response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-catalog:edit x-code-samples: - lang: curl label: cURL source: | curl -X POST https://seller-api.topi.eu/v1/catalog/import \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "products": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "description": "aaa", "extra_details": [ { "property": "memory", "value": "16GB DDR5" } ], "image": { "url": "https://example.com/foo" }, "is_active": false, "manufacturer": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "product_standard_identifiers": [ { "id": "123ab-4567", "identifier_type": "EAN" } ], "seller_categories": [ { "id": "abc123", "name": "abc123", "parent_category_id": "abc123" } ], "seller_product_references": [ { "reference": "123ab-5343", "source": "sap" }, { "reference": "123ab-5343", "source": "sap" } ], "seller_product_type": "software", "shop_product_description_url": "https://example.com/foo", "subtitle": "abc123", "title": "abc123" }, { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "description": "aaa", "extra_details": [ { "property": "memory", "value": "16GB DDR5" } ], "image": { "url": "https://example.com/foo" }, "is_active": false, "manufacturer": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "product_standard_identifiers": [ { "id": "123ab-4567", "identifier_type": "EAN" } ], "seller_categories": [ { "id": "abc123", "name": "abc123", "parent_category_id": "abc123" } ], "seller_product_references": [ { "reference": "123ab-5343", "source": "sap" }, { "reference": "123ab-5343", "source": "sap" } ], "seller_product_type": "software", "shop_product_description_url": "https://example.com/foo", "subtitle": "abc123", "title": "abc123" } ] }' - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/catalog/import', { method: 'POST', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ "products": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "description": "aaa", "extra_details": [ { "property": "memory", "value": "16GB DDR5" } ], "image": { "url": "https://example.com/foo" }, "is_active": false, "manufacturer": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "product_standard_identifiers": [ { "id": "123ab-4567", "identifier_type": "EAN" } ], "seller_categories": [ { "id": "abc123", "name": "abc123", "parent_category_id": "abc123" } ], "seller_product_references": [ { "reference": "123ab-5343", "source": "sap" }, { "reference": "123ab-5343", "source": "sap" } ], "seller_product_type": "software", "shop_product_description_url": "https://example.com/foo", "subtitle": "abc123", "title": "abc123" }, { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "description": "aaa", "extra_details": [ { "property": "memory", "value": "16GB DDR5" } ], "image": { "url": "https://example.com/foo" }, "is_active": false, "manufacturer": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "product_standard_identifiers": [ { "id": "123ab-4567", "identifier_type": "EAN" } ], "seller_categories": [ { "id": "abc123", "name": "abc123", "parent_category_id": "abc123" } ], "seller_product_references": [ { "reference": "123ab-5343", "source": "sap" }, { "reference": "123ab-5343", "source": "sap" } ], "seller_product_type": "software", "shop_product_description_url": "https://example.com/foo", "subtitle": "abc123", "title": "abc123" } ] }) }); const data = await response.json(); console.log(data); /v1/catalog/imports: post: tags: - catalog summary: Create a CSV import job description: > 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 ```csv 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 ``` operationId: catalog#createImport requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateImportRequestBody' example: filename: abc123 responses: '201': description: Created response. content: application/json: schema: $ref: '#/components/schemas/CreateImportResult' example: id: 739b63c2-9e58-4964-b38d-4ebb424de242 upload_url: https://example.com/foo '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '429': description: 'TooManyRequests: Too Many Requests response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-catalog:edit x-code-samples: - lang: curl label: cURL source: | curl -X POST https://seller-api.topi.eu/v1/catalog/imports \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "filename": "abc123" }' - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/catalog/imports', { method: 'POST', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ "filename": "abc123" }) }); const data = await response.json(); console.log(data); /v1/catalog/imports/{id}: delete: tags: - catalog summary: Cancel a CSV import job description: >+ 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. operationId: catalog#cancelImport parameters: - name: id in: path description: The import job ID to cancel. required: true schema: type: string description: The import job ID to cancel. example: 550e8400-e29b-41d4-a716-446655440000 format: uuid example: 550e8400-e29b-41d4-a716-446655440000 responses: '200': description: OK response. '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '404': description: 'NotFound: Not Found response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '422': description: 'Unprocessable: Unprocessable Entity response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-catalog:edit x-code-samples: - lang: curl label: cURL source: | curl -X DELETE https://seller-api.topi.eu/v1/catalog/imports/{id} \ -H "Authorization: Bearer $ACCESS_TOKEN" - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/catalog/imports/{id}', { method: 'DELETE', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}` } }); const data = await response.json(); console.log(data); get: tags: - catalog summary: Get CSV import job details description: > 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. operationId: catalog#getImport parameters: - name: id in: path description: The import job ID. required: true schema: type: string description: The import job ID. example: 550e8400-e29b-41d4-a716-446655440000 format: uuid example: 550e8400-e29b-41d4-a716-446655440000 responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/CatalogImportJob' example: categorization: done: false pending: 1 supported: 1 to_be_reviewed: 1 total: 1 unsupported: 1 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' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '404': description: 'NotFound: Not Found response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-catalog:edit x-code-samples: - lang: curl label: cURL source: | curl -X GET https://seller-api.topi.eu/v1/catalog/imports/{id} \ -H "Authorization: Bearer $ACCESS_TOKEN" - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/catalog/imports/{id}', { method: 'GET', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}` } }); const data = await response.json(); console.log(data); /v1/catalog/list-recommended-rental-prices: post: tags: - catalog summary: List recommended rental prices for products description: >- Given a list of products, retrieve information about the recommended monthly rental price and term, if applicable, for each of the requested products. operationId: catalog#listRecommendedRentalPrices requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ListRecommendedRentalPricesRequestBody' example: pricing_requests: - base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 seller_product_reference: reference: 123ab-5343 source: sap responses: '200': description: OK response. content: application/json: schema: type: array items: $ref: '#/components/schemas/ProductRentalPricingDetails' example: - currency: EUR has_rental_terms: false monthly_rental_amount: 100000 monthly_rental_terms: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 seller_product_reference: reference: 123ab-5343 source: sap summary: Rent with topi from €23.45/month example: - currency: EUR has_rental_terms: false monthly_rental_amount: 100000 monthly_rental_terms: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 seller_product_reference: reference: 123ab-5343 source: sap summary: Rent with topi from €23.45/month '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 security: - OAuth2Seller_header_Authorization: - seller-catalog:read x-code-samples: - lang: curl label: cURL source: > curl -X POST https://seller-api.topi.eu/v1/catalog/list-recommended-rental-prices \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "pricing_requests": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" } } ] }' - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/catalog/list-recommended-rental-prices', { method: 'POST', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ "pricing_requests": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" } } ] }) }); const data = await response.json(); console.log(data); /v1/catalog/pricing: post: tags: - catalog summary: Calculate pricing for a single product description: >- ## *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 operationId: catalog#calculatePricing requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CalculatePricingRequestBody' example: pricing_request: base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 seller_product_reference: reference: 123ab-5343 source: sap responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/CalculatePriceSummary' example: available_contract_types: - rent is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 sublines: - available_contract_types: - rent is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summary: Rent with topi for €24.32/month summary: Rent with topi for €24.32/month '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '404': description: 'NotFound: Not Found response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '422': description: 'Unprocessable: Unprocessable Entity response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-catalog:read x-code-samples: - lang: curl label: cURL source: | curl -X POST https://seller-api.topi.eu/v1/catalog/pricing \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "pricing_request": { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" } } }' - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/catalog/pricing', { method: 'POST', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ "pricing_request": { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "price": { "currency": "EUR", "gross": 119000, "net": 100000, "tax_rate": 1900 }, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" } } }) }); const data = await response.json(); console.log(data); /v1/catalog/products: get: tags: - catalog summary: Search products by term description: get products that match a search term operationId: catalog#searchProducts parameters: - name: term in: query description: The Seller Product Reference allowEmptyValue: true schema: type: string description: The Seller Product Reference example: abc123 example: abc123 responses: '200': description: OK response. content: application/json: schema: type: array items: $ref: '#/components/schemas/SearchProductResult' example: - archived: false available_contract_terms: can_pay_now: false can_rent: false rent: duration: 1 base_rental_price: currency: EUR gross: 119000 net: 100000 description: abc123 ean: abc123 list_price: currency: EUR gross: 119000 net: 100000 manufacturer: abc123 mpn: abc123 origin: abc123 pretty_id: abc123 pricing_category: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 reference: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 example: - archived: false available_contract_terms: can_pay_now: false can_rent: false rent: duration: 1 base_rental_price: currency: EUR gross: 119000 net: 100000 description: abc123 ean: abc123 list_price: currency: EUR gross: 119000 net: 100000 manufacturer: abc123 mpn: abc123 origin: abc123 pretty_id: abc123 pricing_category: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 reference: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '404': description: 'NotFound: Not Found response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '422': description: 'Unprocessable: Unprocessable Entity response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-catalog:read x-code-samples: - lang: curl label: cURL source: | curl -X GET https://seller-api.topi.eu/v1/catalog/products \ -H "Authorization: Bearer $ACCESS_TOKEN" - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/catalog/products', { method: 'GET', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}` } }); const data = await response.json(); console.log(data); /v1/catalog/products_paginated: get: tags: - catalog summary: >- Paginated product search by term, note: this method will not support any filtering, please refer to the POST endpoint for filtering. description: >- get paginated products that match a search term, note: this method will not support any filtering. operationId: catalog#searchProductsPaginated parameters: - name: term in: query description: The Seller Product Reference allowEmptyValue: true schema: type: string description: The Seller Product Reference example: abc123 example: abc123 - name: limit in: query description: the size of the page allowEmptyValue: true schema: type: integer description: the size of the page example: 1 format: int64 example: 1 - name: page in: query description: the index of the page allowEmptyValue: true schema: type: integer description: the index of the page example: 1 format: int64 example: 1 responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/ProductPaginationResult' example: limit: 1 page: 1 rows: - archived: false available_contract_terms: can_pay_now: false can_rent: false rent: duration: 1 base_rental_price: currency: EUR gross: 119000 net: 100000 description: abc123 ean: abc123 list_price: currency: EUR gross: 119000 net: 100000 manufacturer: abc123 mpn: abc123 origin: abc123 pretty_id: abc123 pricing_category: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 reference: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 totalPages: 1 totalRows: 1 '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '404': description: 'NotFound: Not Found response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '422': description: 'Unprocessable: Unprocessable Entity response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-catalog:read x-code-samples: - lang: curl label: cURL source: > curl -X GET https://seller-api.topi.eu/v1/catalog/products_paginated \ -H "Authorization: Bearer $ACCESS_TOKEN" - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/catalog/products_paginated', { method: 'GET', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}` } }); const data = await response.json(); console.log(data); post: tags: - catalog summary: Paginated product search by term, filtering by provided options description: get paginated products that match a search term and the provided filters operationId: catalog#searchAndFilterProductsPaginated parameters: - name: term in: query description: The Seller Product Reference allowEmptyValue: true schema: type: string description: The Seller Product Reference example: abc123 example: abc123 - name: limit in: query description: the size of the page allowEmptyValue: true schema: type: integer description: the size of the page example: 1 format: int64 example: 1 - name: page in: query description: the index of the page allowEmptyValue: true schema: type: integer description: the index of the page example: 1 format: int64 example: 1 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchAndFilterProductsPaginatedRequestBody' example: filtering_logic: OR filtering_options: - operation: '>' property: abc123 value: abc123 responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/ProductPaginationResult' example: limit: 1 page: 1 rows: - archived: false available_contract_terms: can_pay_now: false can_rent: false rent: duration: 1 base_rental_price: currency: EUR gross: 119000 net: 100000 description: abc123 ean: abc123 list_price: currency: EUR gross: 119000 net: 100000 manufacturer: abc123 mpn: abc123 origin: abc123 pretty_id: abc123 pricing_category: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 reference: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 totalPages: 1 totalRows: 1 '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '404': description: 'NotFound: Not Found response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '422': description: 'Unprocessable: Unprocessable Entity response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-catalog:read x-code-samples: - lang: curl label: cURL source: > curl -X POST https://seller-api.topi.eu/v1/catalog/products_paginated \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "filtering_logic": "OR", "filtering_options": [ { "operation": ">", "property": "abc123", "value": "abc123" } ] }' - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/catalog/products_paginated', { method: 'POST', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ "filtering_logic": "OR", "filtering_options": [ { "operation": ">", "property": "abc123", "value": "abc123" } ] }) }); const data = await response.json(); console.log(data); /v1/offers: get: tags: - offer summary: List all offers (deprecated) description: >- Lists the offers created by the calling seller, with filters or query. (deprecated) This method is deprecated. Please use [List all offers with pagination](#/offer/listOffersPaginated) instead. operationId: offer#listOffers parameters: - name: query in: query description: Search query. It can be a string or a number or both allowEmptyValue: true schema: type: string description: Search query. It can be a string or a number or both example: status examples: default: summary: default value: status - name: created_by in: query description: a comma-separated list of sales agents emails allowEmptyValue: true schema: type: string description: a comma-separated list of sales agents emails example: sales-agent@example.com,anothergreatone@example.com example: sales-agent@example.com,anothergreatone@example.com - name: partners_only in: query description: >- a boolean indicating whether to retrieve offers from partner sellers only allowEmptyValue: true schema: type: boolean description: >- a boolean indicating whether to retrieve offers from partner sellers only example: false example: false responses: '200': description: OK response. content: application/json: schema: type: array items: $ref: '#/components/schemas/OfferResult' example: - checkout_redirect_url: https://example.com/foo created_at: '1970-01-01T00:00:01Z' customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 expires_at: '1970-01-01T00:00:01Z' id: 739b63c2-9e58-4964-b38d-4ebb424de242 lines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap sublines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' pricing_overview: breakdown: - amount: currency: EUR gross: 119000 net: 100000 title: Monthly (x36) tooltip: >- The first rent fee is included in the first payment. More details later, in topi checkout. instead_of_amount: currency: EUR gross: 119000 net: 100000 items_summaries: - identifier: abc123 pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 pay_now_excluding_sublines: pay_now_amount: currency: EUR gross: 119000 net: 100000 rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 rent_excluding_sublines: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 total_pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 total_rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 shipping_amount: currency: EUR gross: 119000 net: 100000 total_amount: currency: EUR gross: 119000 net: 100000 sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_redirect_url: https://example.com/foo seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria status: voided example: - checkout_redirect_url: https://example.com/foo created_at: '1970-01-01T00:00:01Z' customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 expires_at: '1970-01-01T00:00:01Z' id: 739b63c2-9e58-4964-b38d-4ebb424de242 lines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap sublines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' pricing_overview: breakdown: - amount: currency: EUR gross: 119000 net: 100000 title: Monthly (x36) tooltip: >- The first rent fee is included in the first payment. More details later, in topi checkout. instead_of_amount: currency: EUR gross: 119000 net: 100000 items_summaries: - identifier: abc123 pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 pay_now_excluding_sublines: pay_now_amount: currency: EUR gross: 119000 net: 100000 rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 rent_excluding_sublines: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 total_pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 total_rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 shipping_amount: currency: EUR gross: 119000 net: 100000 total_amount: currency: EUR gross: 119000 net: 100000 sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_redirect_url: https://example.com/foo seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria status: voided '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '404': description: 'NotFound: Not Found response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' deprecated: true security: - OAuth2Seller_header_Authorization: - seller-offer:read x-code-samples: - lang: curl label: cURL source: | curl -X GET https://seller-api.topi.eu/v1/offers \ -H "Authorization: Bearer $ACCESS_TOKEN" - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/offers', { method: 'GET', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}` } }); const data = await response.json(); console.log(data); post: tags: - offer summary: Create an offer description: > 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"` operationId: offer#create requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePayload2' example: customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 draft_offer_id: abc123 exit_redirect: https://example.com/foo expires_at: '1970-01-01T00:00:01Z' lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria success_redirect: https://example.com/foo responses: '201': description: Created response. content: application/json: schema: $ref: '#/components/schemas/OfferResult' example: checkout_redirect_url: https://example.com/foo created_at: '1970-01-01T00:00:01Z' customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 expires_at: '1970-01-01T00:00:01Z' id: 739b63c2-9e58-4964-b38d-4ebb424de242 lines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap sublines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' pricing_overview: breakdown: - amount: currency: EUR gross: 119000 net: 100000 title: Monthly (x36) tooltip: >- The first rent fee is included in the first payment. More details later, in topi checkout. instead_of_amount: currency: EUR gross: 119000 net: 100000 items_summaries: - identifier: abc123 pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 pay_now_excluding_sublines: pay_now_amount: currency: EUR gross: 119000 net: 100000 rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 rent_excluding_sublines: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 total_pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 total_rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 shipping_amount: currency: EUR gross: 119000 net: 100000 total_amount: currency: EUR gross: 119000 net: 100000 sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_redirect_url: https://example.com/foo seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria status: voided '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '422': description: >- CurrenciesMismatch: The offer and the cart have different currencies. content: application/json: schema: $ref: '#/components/schemas/UnprocessableOffer' examples: AlreadyCheckedOut: summary: AlreadyCheckedOut description: >- The offer cannot be edited as it was already checked out by the customer. value: message: Offer already checked out by the customer name: AlreadyCheckedOut Unprocessable with already active offer with same reference: summary: Unprocessable with already active offer with same reference description: There is already an active offer with the same reference. value: message: There is already an active offer with reference A123456 name: Unprocessable Unprocessable with no product lines: summary: Unprocessable with no product lines description: There are no product lines value: message: There are no product lines name: Unprocessable Unsupported Products: summary: Unsupported Products description: The following references are marked as unsupported by topi. value: message: >- The following references are marked as unsupported by topi. name: UnsupportedProducts references: - reference: unsupported-1 source: sap Unsupported shipping: summary: Unsupported shipping description: The selected shipping is not supported. value: message: Sandbox Shipping Service is not supported name: UnsupportedShipping '503': description: 'ServiceUnavailable: Service Unavailable response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-offer:edit x-code-samples: - lang: curl label: cURL source: | curl -X POST https://seller-api.topi.eu/v1/offers \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "customer": { "company": { "billing_address": { "city": "Munich", "country_code": "DE", "line1": "10 Downing Street", "line2": "Flat 42", "postal_code": "10243", "region": "Bavaria" }, "name": "Unicorn Corp", "tax_number": "123456789", "vat_number": "DE123456789" }, "customer_group": "education", "email": "alice@example.com", "full_name": "John Butler", "phone_number": "abc123" }, "draft_offer_id": "abc123", "exit_redirect": "https://example.com/foo", "expires_at": "1970-01-01T00:00:01Z", "lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "sub_lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "subtitle": "abc123", "title": "abc123" } ], "subtitle": "abc123", "title": "abc123" }, { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "sub_lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "subtitle": "abc123", "title": "abc123" } ], "subtitle": "abc123", "title": "abc123" } ], "metadata": { "affiliate_code": "123456" }, "sales_agent": { "email": "alice@example.com", "external_agent_id": "abc123", "name": "abc123", "phone": "abc123" }, "sales_channel": "ecommerce", "seller_offer_reference": "ref-1234", "shipping": { "is_in_store_pickup": false, "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "seller_shipping_reference": "Sandbox Shipping Service" }, "shipping_address": { "city": "Munich", "country_code": "DE", "line1": "10 Downing Street", "line2": "Flat 42", "postal_code": "10243", "recipient_name": "Felix Wolf", "region": "Bavaria" }, "success_redirect": "https://example.com/foo" }' - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/offers', { method: 'POST', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ "customer": { "company": { "billing_address": { "city": "Munich", "country_code": "DE", "line1": "10 Downing Street", "line2": "Flat 42", "postal_code": "10243", "region": "Bavaria" }, "name": "Unicorn Corp", "tax_number": "123456789", "vat_number": "DE123456789" }, "customer_group": "education", "email": "alice@example.com", "full_name": "John Butler", "phone_number": "abc123" }, "draft_offer_id": "abc123", "exit_redirect": "https://example.com/foo", "expires_at": "1970-01-01T00:00:01Z", "lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "sub_lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "subtitle": "abc123", "title": "abc123" } ], "subtitle": "abc123", "title": "abc123" }, { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "sub_lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "subtitle": "abc123", "title": "abc123" } ], "subtitle": "abc123", "title": "abc123" } ], "metadata": { "affiliate_code": "123456" }, "sales_agent": { "email": "alice@example.com", "external_agent_id": "abc123", "name": "abc123", "phone": "abc123" }, "sales_channel": "ecommerce", "seller_offer_reference": "ref-1234", "shipping": { "is_in_store_pickup": false, "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "seller_shipping_reference": "Sandbox Shipping Service" }, "shipping_address": { "city": "Munich", "country_code": "DE", "line1": "10 Downing Street", "line2": "Flat 42", "postal_code": "10243", "recipient_name": "Felix Wolf", "region": "Bavaria" }, "success_redirect": "https://example.com/foo" }) }); const data = await response.json(); console.log(data); /v1/offers/{id}: get: tags: - offer summary: Retrieve an offer description: > 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. operationId: offer#show parameters: - name: id in: path description: topi offer ID required: true schema: type: string description: topi offer ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ example: 739b63c2-9e58-4964-b38d-4ebb424de242 responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/OfferResult' example: checkout_redirect_url: https://example.com/foo created_at: '1970-01-01T00:00:01Z' customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 expires_at: '1970-01-01T00:00:01Z' id: 739b63c2-9e58-4964-b38d-4ebb424de242 lines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap sublines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' pricing_overview: breakdown: - amount: currency: EUR gross: 119000 net: 100000 title: Monthly (x36) tooltip: >- The first rent fee is included in the first payment. More details later, in topi checkout. instead_of_amount: currency: EUR gross: 119000 net: 100000 items_summaries: - identifier: abc123 pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 pay_now_excluding_sublines: pay_now_amount: currency: EUR gross: 119000 net: 100000 rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 rent_excluding_sublines: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 total_pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 total_rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 shipping_amount: currency: EUR gross: 119000 net: 100000 total_amount: currency: EUR gross: 119000 net: 100000 sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_redirect_url: https://example.com/foo seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria status: voided '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '404': description: 'NotFound: Not Found response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-offer:read x-code-samples: - lang: curl label: cURL source: | curl -X GET https://seller-api.topi.eu/v1/offers/{id} \ -H "Authorization: Bearer $ACCESS_TOKEN" - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/offers/{id}', { method: 'GET', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}` } }); const data = await response.json(); console.log(data); put: tags: - offer summary: Edit an offer description: > 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. operationId: offer#edit parameters: - name: id in: path description: Offer ID required: true schema: type: string description: Offer ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ example: 739b63c2-9e58-4964-b38d-4ebb424de242 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateOfferPayload' example: customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 draft_offer_id: abc123 exit_redirect: https://example.com/foo expires_at: '1970-01-01T00:00:01Z' lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria success_redirect: https://example.com/foo responses: '202': description: Accepted response. content: application/json: schema: $ref: '#/components/schemas/OfferResult' example: checkout_redirect_url: https://example.com/foo created_at: '1970-01-01T00:00:01Z' customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 expires_at: '1970-01-01T00:00:01Z' id: 739b63c2-9e58-4964-b38d-4ebb424de242 lines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap sublines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' pricing_overview: breakdown: - amount: currency: EUR gross: 119000 net: 100000 title: Monthly (x36) tooltip: >- The first rent fee is included in the first payment. More details later, in topi checkout. instead_of_amount: currency: EUR gross: 119000 net: 100000 items_summaries: - identifier: abc123 pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 pay_now_excluding_sublines: pay_now_amount: currency: EUR gross: 119000 net: 100000 rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 rent_excluding_sublines: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 total_pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 total_rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 shipping_amount: currency: EUR gross: 119000 net: 100000 total_amount: currency: EUR gross: 119000 net: 100000 sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_redirect_url: https://example.com/foo seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria status: voided '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '422': description: 'AlreadyCheckedOut: The offer is already checked out' content: application/json: schema: $ref: '#/components/schemas/UnprocessableOffer' examples: AlreadyCheckedOut: summary: AlreadyCheckedOut description: >- The offer cannot be edited as it was already checked out by the customer. value: message: Offer already checked out by the customer name: AlreadyCheckedOut Unprocessable with already active offer with same reference: summary: Unprocessable with already active offer with same reference description: There is already an active offer with the same reference. value: message: There is already an active offer with reference A123456 name: Unprocessable Unprocessable with no product lines: summary: Unprocessable with no product lines description: There are no product lines value: message: There are no product lines name: Unprocessable Unsupported Products: summary: Unsupported Products description: The following references are marked as unsupported by topi. value: message: >- The following references are marked as unsupported by topi. name: UnsupportedProducts references: - reference: unsupported-1 source: sap Unsupported shipping: summary: Unsupported shipping description: The selected shipping is not supported. value: message: Sandbox Shipping Service is not supported name: UnsupportedShipping '503': description: 'ServiceUnavailable: Service Unavailable response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-offer:edit x-code-samples: - lang: curl label: cURL source: | curl -X PUT https://seller-api.topi.eu/v1/offers/{id} \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "customer": { "company": { "billing_address": { "city": "Munich", "country_code": "DE", "line1": "10 Downing Street", "line2": "Flat 42", "postal_code": "10243", "region": "Bavaria" }, "name": "Unicorn Corp", "tax_number": "123456789", "vat_number": "DE123456789" }, "customer_group": "education", "email": "alice@example.com", "full_name": "John Butler", "phone_number": "abc123" }, "draft_offer_id": "abc123", "exit_redirect": "https://example.com/foo", "expires_at": "1970-01-01T00:00:01Z", "lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "sub_lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "subtitle": "abc123", "title": "abc123" } ], "subtitle": "abc123", "title": "abc123" }, { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "sub_lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "subtitle": "abc123", "title": "abc123" } ], "subtitle": "abc123", "title": "abc123" } ], "metadata": { "affiliate_code": "123456" }, "sales_agent": { "email": "alice@example.com", "external_agent_id": "abc123", "name": "abc123", "phone": "abc123" }, "sales_channel": "ecommerce", "seller_offer_reference": "ref-1234", "shipping": { "is_in_store_pickup": false, "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "seller_shipping_reference": "Sandbox Shipping Service" }, "shipping_address": { "city": "Munich", "country_code": "DE", "line1": "10 Downing Street", "line2": "Flat 42", "postal_code": "10243", "recipient_name": "Felix Wolf", "region": "Bavaria" }, "success_redirect": "https://example.com/foo" }' - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/offers/{id}', { method: 'PUT', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ "customer": { "company": { "billing_address": { "city": "Munich", "country_code": "DE", "line1": "10 Downing Street", "line2": "Flat 42", "postal_code": "10243", "region": "Bavaria" }, "name": "Unicorn Corp", "tax_number": "123456789", "vat_number": "DE123456789" }, "customer_group": "education", "email": "alice@example.com", "full_name": "John Butler", "phone_number": "abc123" }, "draft_offer_id": "abc123", "exit_redirect": "https://example.com/foo", "expires_at": "1970-01-01T00:00:01Z", "lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "sub_lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "subtitle": "abc123", "title": "abc123" } ], "subtitle": "abc123", "title": "abc123" }, { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "sub_lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "subtitle": "abc123", "title": "abc123" } ], "subtitle": "abc123", "title": "abc123" } ], "metadata": { "affiliate_code": "123456" }, "sales_agent": { "email": "alice@example.com", "external_agent_id": "abc123", "name": "abc123", "phone": "abc123" }, "sales_channel": "ecommerce", "seller_offer_reference": "ref-1234", "shipping": { "is_in_store_pickup": false, "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "seller_shipping_reference": "Sandbox Shipping Service" }, "shipping_address": { "city": "Munich", "country_code": "DE", "line1": "10 Downing Street", "line2": "Flat 42", "postal_code": "10243", "recipient_name": "Felix Wolf", "region": "Bavaria" }, "success_redirect": "https://example.com/foo" }) }); const data = await response.json(); console.log(data); /v1/offers/{id}/void: post: tags: - offer summary: Void an offer description: > 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. operationId: offer#void parameters: - name: id in: path description: topi offer ID required: true schema: type: string description: topi offer ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ example: 739b63c2-9e58-4964-b38d-4ebb424de242 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VoidRequestBody' example: superseded_by_id: 739b63c2-9e58-4964-b38d-4ebb424de242 responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/OfferResult' examples: A voided offer: summary: A voided offer value: created_at: '1971-05-24T04:42:31Z' '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '404': description: 'NotFound: Not Found response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '422': description: 'Unprocessable: Unprocessable Entity response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-offer:edit x-code-samples: - lang: curl label: cURL source: | curl -X POST https://seller-api.topi.eu/v1/offers/{id}/void \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "superseded_by_id": "739b63c2-9e58-4964-b38d-4ebb424de242" }' - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/offers/{id}/void', { method: 'POST', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ "superseded_by_id": "739b63c2-9e58-4964-b38d-4ebb424de242" }) }); const data = await response.json(); console.log(data); /v1/offers/paginated: get: tags: - offer summary: List all offers with pagination description: >- 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 operationId: offer#listOffersPaginated parameters: - name: limit in: query description: the size of the page allowEmptyValue: true schema: type: integer description: the size of the page example: 1 format: int64 example: 1 - name: page in: query description: the index of the page allowEmptyValue: true schema: type: integer description: the index of the page example: 1 format: int64 example: 1 - name: query in: query description: Search query. It can be a string or a number or both allowEmptyValue: true schema: type: string description: Search query. It can be a string or a number or both example: status examples: default: summary: default value: status - name: created_by in: query description: a comma-separated list of sales agents emails allowEmptyValue: true schema: type: string description: a comma-separated list of sales agents emails example: sales-agent@example.com,anothergreatone@example.com example: sales-agent@example.com,anothergreatone@example.com - name: partners_only in: query description: >- a boolean indicating whether to retrieve offers from partner sellers only allowEmptyValue: true schema: type: boolean description: >- a boolean indicating whether to retrieve offers from partner sellers only example: false example: false - name: sort_by in: query description: Field to sort by allowEmptyValue: true schema: type: string description: Field to sort by default: created_at example: status enum: - created_at - status - expires_at example: status - name: sort_order in: query description: Sort direction allowEmptyValue: true schema: type: string description: Sort direction default: asc example: desc enum: - asc - desc example: desc - name: id_gt in: query description: 'Filter: offer ID > value (UUID)' allowEmptyValue: true schema: type: string description: 'Filter: offer ID > value (UUID)' example: 550e8400-e29b-41d4-a716-446655440000 format: uuid example: 550e8400-e29b-41d4-a716-446655440000 - name: id_gte in: query description: 'Filter: offer ID >= value (UUID)' allowEmptyValue: true schema: type: string description: 'Filter: offer ID >= value (UUID)' example: 550e8400-e29b-41d4-a716-446655440000 format: uuid example: 550e8400-e29b-41d4-a716-446655440000 - name: id_lt in: query description: 'Filter: offer ID < value (UUID)' allowEmptyValue: true schema: type: string description: 'Filter: offer ID < value (UUID)' example: 550e8400-e29b-41d4-a716-446655440000 format: uuid example: 550e8400-e29b-41d4-a716-446655440000 - name: id_lte in: query description: 'Filter: offer ID <= value (UUID)' allowEmptyValue: true schema: type: string description: 'Filter: offer ID <= value (UUID)' example: 550e8400-e29b-41d4-a716-446655440000 format: uuid example: 550e8400-e29b-41d4-a716-446655440000 - name: created_at_gt in: query description: 'Filter: offer created_at > value (RFC3339)' allowEmptyValue: true schema: type: string description: 'Filter: offer created_at > value (RFC3339)' example: '2025-01-01T00:00:00Z' format: date-time example: '2025-01-01T00:00:00Z' - name: created_at_gte in: query description: 'Filter: offer created_at >= value (RFC3339)' allowEmptyValue: true schema: type: string description: 'Filter: offer created_at >= value (RFC3339)' example: '2025-01-01T00:00:00Z' format: date-time example: '2025-01-01T00:00:00Z' - name: created_at_lt in: query description: 'Filter: offer created_at < value (RFC3339)' allowEmptyValue: true schema: type: string description: 'Filter: offer created_at < value (RFC3339)' example: '2025-12-31T23:59:59Z' format: date-time example: '2025-12-31T23:59:59Z' - name: created_at_lte in: query description: 'Filter: offer created_at <= value (RFC3339)' allowEmptyValue: true schema: type: string description: 'Filter: offer created_at <= value (RFC3339)' example: '2025-12-31T23:59:59Z' format: date-time example: '2025-12-31T23:59:59Z' responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/OfferListResult' example: offers: - checkout_redirect_url: https://example.com/foo created_at: '1970-01-01T00:00:01Z' customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 expires_at: '1970-01-01T00:00:01Z' id: 739b63c2-9e58-4964-b38d-4ebb424de242 lines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap sublines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' pricing_overview: breakdown: - amount: currency: EUR gross: 119000 net: 100000 title: Monthly (x36) tooltip: >- The first rent fee is included in the first payment. More details later, in topi checkout. instead_of_amount: currency: EUR gross: 119000 net: 100000 items_summaries: - identifier: abc123 pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 pay_now_excluding_sublines: pay_now_amount: currency: EUR gross: 119000 net: 100000 rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 rent_excluding_sublines: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 total_pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 total_rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 shipping_amount: currency: EUR gross: 119000 net: 100000 total_amount: currency: EUR gross: 119000 net: 100000 sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_redirect_url: https://example.com/foo seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria status: voided pagination: page: 1 page_size: 1 total_count: 1 total_pages: 1 '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '404': description: 'NotFound: Not Found response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-offer:read x-code-samples: - lang: curl label: cURL source: | curl -X GET https://seller-api.topi.eu/v1/offers/paginated \ -H "Authorization: Bearer $ACCESS_TOKEN" - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/offers/paginated', { method: 'GET', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}` } }); const data = await response.json(); console.log(data); /v1/offers/partners: post: tags: - offer summary: Create an offer for a partner description: > 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"` operationId: offer#createForPartner requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePayloadWithMandatorySalesAgent2' example: customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 draft_offer_id: abc123 exit_redirect: https://example.com/foo expires_at: '1970-01-01T00:00:01Z' lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria success_redirect: https://example.com/foo responses: '201': description: Created response. content: application/json: schema: $ref: '#/components/schemas/OfferResult' example: checkout_redirect_url: https://example.com/foo created_at: '1970-01-01T00:00:01Z' customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 expires_at: '1970-01-01T00:00:01Z' id: 739b63c2-9e58-4964-b38d-4ebb424de242 lines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap sublines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' pricing_overview: breakdown: - amount: currency: EUR gross: 119000 net: 100000 title: Monthly (x36) tooltip: >- The first rent fee is included in the first payment. More details later, in topi checkout. instead_of_amount: currency: EUR gross: 119000 net: 100000 items_summaries: - identifier: abc123 pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 pay_now_excluding_sublines: pay_now_amount: currency: EUR gross: 119000 net: 100000 rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 rent_excluding_sublines: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 total_pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 total_rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 shipping_amount: currency: EUR gross: 119000 net: 100000 total_amount: currency: EUR gross: 119000 net: 100000 sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_redirect_url: https://example.com/foo seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria status: voided '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '422': description: >- CurrenciesMismatch: The offer and the cart have different currencies. content: application/json: schema: $ref: '#/components/schemas/UnprocessableOffer' examples: AlreadyCheckedOut: summary: AlreadyCheckedOut description: >- The offer cannot be edited as it was already checked out by the customer. value: message: Offer already checked out by the customer name: AlreadyCheckedOut Unprocessable with already active offer with same reference: summary: Unprocessable with already active offer with same reference description: There is already an active offer with the same reference. value: message: There is already an active offer with reference A123456 name: Unprocessable Unprocessable with no product lines: summary: Unprocessable with no product lines description: There are no product lines value: message: There are no product lines name: Unprocessable Unsupported Products: summary: Unsupported Products description: The following references are marked as unsupported by topi. value: message: >- The following references are marked as unsupported by topi. name: UnsupportedProducts references: - reference: unsupported-1 source: sap Unsupported shipping: summary: Unsupported shipping description: The selected shipping is not supported. value: message: Sandbox Shipping Service is not supported name: UnsupportedShipping '503': description: 'ServiceUnavailable: Service Unavailable response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-offer:edit x-code-samples: - lang: curl label: cURL source: | curl -X POST https://seller-api.topi.eu/v1/offers/partners \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "customer": { "company": { "billing_address": { "city": "Munich", "country_code": "DE", "line1": "10 Downing Street", "line2": "Flat 42", "postal_code": "10243", "region": "Bavaria" }, "name": "Unicorn Corp", "tax_number": "123456789", "vat_number": "DE123456789" }, "customer_group": "education", "email": "alice@example.com", "full_name": "John Butler", "phone_number": "abc123" }, "draft_offer_id": "abc123", "exit_redirect": "https://example.com/foo", "expires_at": "1970-01-01T00:00:01Z", "lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "sub_lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "subtitle": "abc123", "title": "abc123" } ], "subtitle": "abc123", "title": "abc123" }, { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "sub_lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "subtitle": "abc123", "title": "abc123" } ], "subtitle": "abc123", "title": "abc123" } ], "metadata": { "affiliate_code": "123456" }, "sales_agent": { "email": "alice@example.com", "external_agent_id": "abc123", "name": "abc123", "phone": "abc123" }, "sales_channel": "ecommerce", "seller_offer_reference": "ref-1234", "shipping": { "is_in_store_pickup": false, "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "seller_shipping_reference": "Sandbox Shipping Service" }, "shipping_address": { "city": "Munich", "country_code": "DE", "line1": "10 Downing Street", "line2": "Flat 42", "postal_code": "10243", "recipient_name": "Felix Wolf", "region": "Bavaria" }, "success_redirect": "https://example.com/foo" }' - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/offers/partners', { method: 'POST', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ "customer": { "company": { "billing_address": { "city": "Munich", "country_code": "DE", "line1": "10 Downing Street", "line2": "Flat 42", "postal_code": "10243", "region": "Bavaria" }, "name": "Unicorn Corp", "tax_number": "123456789", "vat_number": "DE123456789" }, "customer_group": "education", "email": "alice@example.com", "full_name": "John Butler", "phone_number": "abc123" }, "draft_offer_id": "abc123", "exit_redirect": "https://example.com/foo", "expires_at": "1970-01-01T00:00:01Z", "lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "sub_lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "subtitle": "abc123", "title": "abc123" } ], "subtitle": "abc123", "title": "abc123" }, { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "sub_lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "subtitle": "abc123", "title": "abc123" } ], "subtitle": "abc123", "title": "abc123" } ], "metadata": { "affiliate_code": "123456" }, "sales_agent": { "email": "alice@example.com", "external_agent_id": "abc123", "name": "abc123", "phone": "abc123" }, "sales_channel": "ecommerce", "seller_offer_reference": "ref-1234", "shipping": { "is_in_store_pickup": false, "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "seller_shipping_reference": "Sandbox Shipping Service" }, "shipping_address": { "city": "Munich", "country_code": "DE", "line1": "10 Downing Street", "line2": "Flat 42", "postal_code": "10243", "recipient_name": "Felix Wolf", "region": "Bavaria" }, "success_redirect": "https://example.com/foo" }) }); const data = await response.json(); console.log(data); /v1/offers/ref/{seller_offer_reference}: get: tags: - offer summary: Retrieve an offer by seller reference description: | 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. operationId: offer#showByReference parameters: - name: seller_offer_reference in: path description: Seller's own reference for the offer required: true schema: type: string description: Seller's own reference for the offer example: ref-1234 example: ref-1234 responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/OfferWithReferenceResult' example: checkout_redirect_url: https://example.com/foo created_at: '1970-01-01T00:00:01Z' customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 expires_at: '1970-01-01T00:00:01Z' id: 739b63c2-9e58-4964-b38d-4ebb424de242 lines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap sublines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' pricing_overview: breakdown: - amount: currency: EUR gross: 119000 net: 100000 title: Monthly (x36) tooltip: >- The first rent fee is included in the first payment. More details later, in topi checkout. instead_of_amount: currency: EUR gross: 119000 net: 100000 items_summaries: - identifier: abc123 pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 pay_now_excluding_sublines: pay_now_amount: currency: EUR gross: 119000 net: 100000 rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 rent_excluding_sublines: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 total_pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 total_rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 shipping_amount: currency: EUR gross: 119000 net: 100000 total_amount: currency: EUR gross: 119000 net: 100000 sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_redirect_url: https://example.com/foo seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria status: voided '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '404': description: 'NotFound: Not Found response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-offer:read x-code-samples: - lang: curl label: cURL source: > curl -X GET https://seller-api.topi.eu/v1/offers/ref/{seller_offer_reference} \ -H "Authorization: Bearer $ACCESS_TOKEN" - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/offers/ref/{seller_offer_reference}', { method: 'GET', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}` } }); const data = await response.json(); console.log(data); /v1/offers/validate: post: tags: - offer summary: Validate an offer description: > 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"` operationId: offer#validate requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ValidateRequestBody' example: Accept-Language: abc123 customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 draft_offer_id: abc123 exit_redirect: https://example.com/foo expires_at: '1970-01-01T00:00:01Z' lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria success_redirect: https://example.com/foo responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/ValidateResult' example: pricing_overview: breakdown: - amount: currency: EUR gross: 119000 net: 100000 title: Monthly (x36) tooltip: >- The first rent fee is included in the first payment. More details later, in topi checkout. instead_of_amount: currency: EUR gross: 119000 net: 100000 items_summaries: - identifier: abc123 pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 pay_now_excluding_sublines: pay_now_amount: currency: EUR gross: 119000 net: 100000 rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 rent_excluding_sublines: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 total_pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 total_rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 shipping_amount: currency: EUR gross: 119000 net: 100000 total_amount: currency: EUR gross: 119000 net: 100000 '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '422': description: >- CurrenciesMismatch: The offer and the cart have different currencies. content: application/json: schema: $ref: '#/components/schemas/UnprocessableOffer' examples: AlreadyCheckedOut: summary: AlreadyCheckedOut description: >- The offer cannot be edited as it was already checked out by the customer. value: message: Offer already checked out by the customer name: AlreadyCheckedOut Unprocessable with already active offer with same reference: summary: Unprocessable with already active offer with same reference description: There is already an active offer with the same reference. value: message: There is already an active offer with reference A123456 name: Unprocessable Unprocessable with no product lines: summary: Unprocessable with no product lines description: There are no product lines value: message: There are no product lines name: Unprocessable Unsupported Products: summary: Unsupported Products description: The following references are marked as unsupported by topi. value: message: >- The following references are marked as unsupported by topi. name: UnsupportedProducts references: - reference: unsupported-1 source: sap Unsupported shipping: summary: Unsupported shipping description: The selected shipping is not supported. value: message: Sandbox Shipping Service is not supported name: UnsupportedShipping security: - OAuth2Seller_header_Authorization: - seller-offer:edit x-code-samples: - lang: curl label: cURL source: | curl -X POST https://seller-api.topi.eu/v1/offers/validate \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "Accept-Language": "abc123", "customer": { "company": { "billing_address": { "city": "Munich", "country_code": "DE", "line1": "10 Downing Street", "line2": "Flat 42", "postal_code": "10243", "region": "Bavaria" }, "name": "Unicorn Corp", "tax_number": "123456789", "vat_number": "DE123456789" }, "customer_group": "education", "email": "alice@example.com", "full_name": "John Butler", "phone_number": "abc123" }, "draft_offer_id": "abc123", "exit_redirect": "https://example.com/foo", "expires_at": "1970-01-01T00:00:01Z", "lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "sub_lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "subtitle": "abc123", "title": "abc123" } ], "subtitle": "abc123", "title": "abc123" }, { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "sub_lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "subtitle": "abc123", "title": "abc123" } ], "subtitle": "abc123", "title": "abc123" } ], "metadata": { "affiliate_code": "123456" }, "sales_agent": { "email": "alice@example.com", "external_agent_id": "abc123", "name": "abc123", "phone": "abc123" }, "sales_channel": "ecommerce", "seller_offer_reference": "ref-1234", "shipping": { "is_in_store_pickup": false, "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "seller_shipping_reference": "Sandbox Shipping Service" }, "shipping_address": { "city": "Munich", "country_code": "DE", "line1": "10 Downing Street", "line2": "Flat 42", "postal_code": "10243", "recipient_name": "Felix Wolf", "region": "Bavaria" }, "success_redirect": "https://example.com/foo" }' - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/offers/validate', { method: 'POST', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ "Accept-Language": "abc123", "customer": { "company": { "billing_address": { "city": "Munich", "country_code": "DE", "line1": "10 Downing Street", "line2": "Flat 42", "postal_code": "10243", "region": "Bavaria" }, "name": "Unicorn Corp", "tax_number": "123456789", "vat_number": "DE123456789" }, "customer_group": "education", "email": "alice@example.com", "full_name": "John Butler", "phone_number": "abc123" }, "draft_offer_id": "abc123", "exit_redirect": "https://example.com/foo", "expires_at": "1970-01-01T00:00:01Z", "lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "sub_lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "subtitle": "abc123", "title": "abc123" } ], "subtitle": "abc123", "title": "abc123" }, { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "sub_lines": [ { "base_rental_price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "bundle_index": "abc123", "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "product_id": "abc123", "quantity": 2, "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "subtitle": "abc123", "title": "abc123" } ], "subtitle": "abc123", "title": "abc123" } ], "metadata": { "affiliate_code": "123456" }, "sales_agent": { "email": "alice@example.com", "external_agent_id": "abc123", "name": "abc123", "phone": "abc123" }, "sales_channel": "ecommerce", "seller_offer_reference": "ref-1234", "shipping": { "is_in_store_pickup": false, "price": { "currency": "EUR", "gross": 119000, "net": 100000 }, "seller_shipping_reference": "Sandbox Shipping Service" }, "shipping_address": { "city": "Munich", "country_code": "DE", "line1": "10 Downing Street", "line2": "Flat 42", "postal_code": "10243", "recipient_name": "Felix Wolf", "region": "Bavaria" }, "success_redirect": "https://example.com/foo" }) }); const data = await response.json(); console.log(data); /v1/orders: get: tags: - order summary: List all orders (deprecated) description: >- Returns a list of created orders, filterable by `query` or `created_by`. (deprecated) This method is deprecated. Please use [List all orders with pagination](#/order/getBySellerPaginated) instead. operationId: order#getBySeller parameters: - name: query in: query description: Search query. It can be a string or a number or both allowEmptyValue: true schema: type: string description: Search query. It can be a string or a number or both example: status examples: default: summary: default value: status - name: created_by in: query description: a comma-separated list of sales agents emails allowEmptyValue: true schema: type: string description: a comma-separated list of sales agents emails example: sales-agent@example.com,anothergreatone@example.com example: sales-agent@example.com,anothergreatone@example.com - name: partners_only in: query description: >- a boolean indicating whether to retrieve orders from partner sellers only allowEmptyValue: true schema: type: boolean description: >- a boolean indicating whether to retrieve orders from partner sellers only example: false example: false responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/OrdersSummary' example: orders: - agent_name: abc123 company_name: abc123 created_at: '1970-01-01T00:00:01Z' full_name: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 offer_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_offer_reference: abc123 status: confirmed '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 deprecated: true security: - OAuth2Seller_header_Authorization: - seller-order:read x-code-samples: - lang: curl label: cURL source: | curl -X GET https://seller-api.topi.eu/v1/orders \ -H "Authorization: Bearer $ACCESS_TOKEN" - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/orders', { method: 'GET', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}` } }); const data = await response.json(); console.log(data); /v1/orders/{id}: get: tags: - order summary: Retrieve an order description: > 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. operationId: order#show parameters: - name: id in: path description: topi order ID required: true schema: type: string description: topi order ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ example: 739b63c2-9e58-4964-b38d-4ebb424de242 responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/FullOrderResult' example: assets: - id: 739b63c2-9e58-4964-b38d-4ebb424de242 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_product_references: - reference: 123ab-5343 source: sap serial_number: BA-3456786-334-9 status: shipped title: Pro Laptop 64GB tracking_url: abc123 canceled_at: '1970-01-01T00:00:01Z' created_at: '1970-01-01T00:00:01Z' customer_info: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 metadata: tracking_number: '123456' offer_created_at: '1970-01-01T00:00:01Z' offer_id: 739b63c2-9e58-4964-b38d-4ebb424de242 order_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 contract_type: rent duration: 6 monthly_price: currency: EUR gross: 119000 net: 100000 pretty_id: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 quantity: 1 selected_first_party_services: - additional_values: accessory_type: experiment_charger id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_price: currency: EUR gross: 119000 net: 100000 type: topi_replace seller_product_references: - reference: 123ab-5343 source: sap sublines: - base_rental_price: currency: EUR gross: 119000 net: 100000 contract_type: rent duration: 6 monthly_price: currency: EUR gross: 119000 net: 100000 pretty_id: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 quantity: 1 selected_first_party_services: - additional_values: accessory_type: experiment_charger id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_price: currency: EUR gross: 119000 net: 100000 type: topi_replace seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 unit_price: currency: EUR gross: 119000 net: 100000 subtitle: abc123 title: abc123 unit_price: currency: EUR gross: 119000 net: 100000 sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 seller_info: address: city: abc123 country_code: DE line1: abc123 line2: aaa postal_code: abc123 region: abc123 capability_add_custom_products: false capability_anonymized_pricing: false capability_anonymous_ecom_offer_creation: false capability_bundles: false capability_chatbot_id: abc123 capability_dual_pricing: false capability_hide_buy_now: false capability_international_shipment: false currency: abc123 email: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 logo_url: abc123 name: abc123 parent_seller_id: abc123 pdf_reader_assistant_id: abc123 pretty_name: abc123 product_reference_source: abc123 seller_offer_reference: abc123 shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria shipping_info: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service status: confirmed tracking_urls: - abc123 '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '404': description: 'NotFound: Not Found response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-order:read x-code-samples: - lang: curl label: cURL source: | curl -X GET https://seller-api.topi.eu/v1/orders/{id} \ -H "Authorization: Bearer $ACCESS_TOKEN" - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/orders/{id}', { method: 'GET', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}` } }); const data = await response.json(); console.log(data); patch: tags: - order summary: Set metadata on an order description: Sets arbitrary JSON metadata on an order. operationId: order#setMetadata parameters: - name: id in: path description: topi order ID required: true schema: type: string description: topi order ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ example: 739b63c2-9e58-4964-b38d-4ebb424de242 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SetMetadataRequestBody' example: metadata: tracking_number: '123456' responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/OrderResult' example: assets: - id: 739b63c2-9e58-4964-b38d-4ebb424de242 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_product_references: - reference: 123ab-5343 source: sap serial_number: BA-3456786-334-9 status: shipped title: Pro Laptop 64GB tracking_url: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 metadata: tracking_number: '123456' offer_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_offer_reference: abc123 status: confirmed '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '404': description: 'NotFound: Not Found response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-order:edit x-code-samples: - lang: curl label: cURL source: | curl -X PATCH https://seller-api.topi.eu/v1/orders/{id} \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "metadata": { "tracking_number": "123456" } }' - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/orders/{id}', { method: 'PATCH', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ "metadata": { "tracking_number": "123456" } }) }); const data = await response.json(); console.log(data); /v1/orders/{id}/accept: post: tags: - order summary: Confirm an order description: >- Sets the status of an existing order to "confirmed". You can only accept orders that have been in the status "created" or "acknowledged". operationId: order#acceptOrder parameters: - name: id in: path description: topi order ID required: true schema: type: string description: topi order ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ example: 739b63c2-9e58-4964-b38d-4ebb424de242 responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/OrderResult' example: assets: - id: 739b63c2-9e58-4964-b38d-4ebb424de242 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_product_references: - reference: 123ab-5343 source: sap serial_number: BA-3456786-334-9 status: shipped title: Pro Laptop 64GB tracking_url: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 metadata: tracking_number: '123456' offer_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_offer_reference: abc123 status: confirmed '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '404': description: 'NotFound: Not Found response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '422': description: 'InvalidStatus: Unprocessable Entity response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-order:edit x-code-samples: - lang: curl label: cURL source: | curl -X POST https://seller-api.topi.eu/v1/orders/{id}/accept \ -H "Authorization: Bearer $ACCESS_TOKEN" - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/orders/{id}/accept', { method: 'POST', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}` } }); const data = await response.json(); console.log(data); /v1/orders/{id}/acknowledge: post: tags: - order summary: Acknowledge an order description: >- Sets the status of an existing order to "acknowledged". You can only acknowledge orders that have been in the status "created". operationId: order#acknowledgeOrder parameters: - name: id in: path description: topi order ID required: true schema: type: string description: topi order ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ example: 739b63c2-9e58-4964-b38d-4ebb424de242 responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/OrderResult' example: assets: - id: 739b63c2-9e58-4964-b38d-4ebb424de242 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_product_references: - reference: 123ab-5343 source: sap serial_number: BA-3456786-334-9 status: shipped title: Pro Laptop 64GB tracking_url: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 metadata: tracking_number: '123456' offer_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_offer_reference: abc123 status: confirmed '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '404': description: 'NotFound: Not Found response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '422': description: 'InvalidStatus: Unprocessable Entity response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-order:edit x-code-samples: - lang: curl label: cURL source: | curl -X POST https://seller-api.topi.eu/v1/orders/{id}/acknowledge \ -H "Authorization: Bearer $ACCESS_TOKEN" - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/orders/{id}/acknowledge', { method: 'POST', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}` } }); const data = await response.json(); console.log(data); /v1/orders/{id}/reject: post: tags: - order summary: Reject an order description: >- Sets the status of an existing order to "rejected". You can only reject orders that have been in the status "created" or "acknowledged". operationId: order#rejectOrder parameters: - name: id in: path description: topi order ID required: true schema: type: string description: topi order ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ example: 739b63c2-9e58-4964-b38d-4ebb424de242 responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/OrderResult' example: assets: - id: 739b63c2-9e58-4964-b38d-4ebb424de242 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_product_references: - reference: 123ab-5343 source: sap serial_number: BA-3456786-334-9 status: shipped title: Pro Laptop 64GB tracking_url: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 metadata: tracking_number: '123456' offer_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_offer_reference: abc123 status: confirmed '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '404': description: 'NotFound: Not Found response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '422': description: 'InvalidStatus: Unprocessable Entity response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-order:edit x-code-samples: - lang: curl label: cURL source: | curl -X POST https://seller-api.topi.eu/v1/orders/{id}/reject \ -H "Authorization: Bearer $ACCESS_TOKEN" - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/orders/{id}/reject', { method: 'POST', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}` } }); const data = await response.json(); console.log(data); /v1/orders/paginated: get: tags: - order summary: List all orders with pagination description: >- 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 operationId: order#getBySellerPaginated parameters: - name: limit in: query description: the size of the page allowEmptyValue: true schema: type: integer description: the size of the page example: 1 format: int64 example: 1 - name: page in: query description: the index of the page allowEmptyValue: true schema: type: integer description: the index of the page example: 1 format: int64 example: 1 - name: query in: query description: Search query. It can be a string or a number or both allowEmptyValue: true schema: type: string description: Search query. It can be a string or a number or both example: status examples: default: summary: default value: status - name: created_by in: query description: a comma-separated list of sales agents emails allowEmptyValue: true schema: type: string description: a comma-separated list of sales agents emails example: sales-agent@example.com,anothergreatone@example.com example: sales-agent@example.com,anothergreatone@example.com - name: partners_only in: query description: >- a boolean indicating whether to retrieve orders from partner sellers only allowEmptyValue: true schema: type: boolean description: >- a boolean indicating whether to retrieve orders from partner sellers only example: false example: false - name: sort_by in: query description: Field to sort by allowEmptyValue: true schema: type: string description: Field to sort by default: created_at example: created_at enum: - created_at example: created_at - name: sort_order in: query description: Sort direction allowEmptyValue: true schema: type: string description: Sort direction default: asc example: desc enum: - asc - desc example: desc - name: id_gt in: query description: 'Filter: order ID > value (UUID)' allowEmptyValue: true schema: type: string description: 'Filter: order ID > value (UUID)' example: 550e8400-e29b-41d4-a716-446655440000 format: uuid example: 550e8400-e29b-41d4-a716-446655440000 - name: id_gte in: query description: 'Filter: order ID >= value (UUID)' allowEmptyValue: true schema: type: string description: 'Filter: order ID >= value (UUID)' example: 550e8400-e29b-41d4-a716-446655440000 format: uuid example: 550e8400-e29b-41d4-a716-446655440000 - name: id_lt in: query description: 'Filter: order ID < value (UUID)' allowEmptyValue: true schema: type: string description: 'Filter: order ID < value (UUID)' example: 550e8400-e29b-41d4-a716-446655440000 format: uuid example: 550e8400-e29b-41d4-a716-446655440000 - name: id_lte in: query description: 'Filter: order ID <= value (UUID)' allowEmptyValue: true schema: type: string description: 'Filter: order ID <= value (UUID)' example: 550e8400-e29b-41d4-a716-446655440000 format: uuid example: 550e8400-e29b-41d4-a716-446655440000 - name: created_at_gt in: query description: 'Filter: order created_at > value (RFC3339)' allowEmptyValue: true schema: type: string description: 'Filter: order created_at > value (RFC3339)' example: '2025-01-01T00:00:00Z' format: date-time example: '2025-01-01T00:00:00Z' - name: created_at_gte in: query description: 'Filter: order created_at >= value (RFC3339)' allowEmptyValue: true schema: type: string description: 'Filter: order created_at >= value (RFC3339)' example: '2025-01-01T00:00:00Z' format: date-time example: '2025-01-01T00:00:00Z' - name: created_at_lt in: query description: 'Filter: order created_at < value (RFC3339)' allowEmptyValue: true schema: type: string description: 'Filter: order created_at < value (RFC3339)' example: '2025-12-31T23:59:59Z' format: date-time example: '2025-12-31T23:59:59Z' - name: created_at_lte in: query description: 'Filter: order created_at <= value (RFC3339)' allowEmptyValue: true schema: type: string description: 'Filter: order created_at <= value (RFC3339)' example: '2025-12-31T23:59:59Z' format: date-time example: '2025-12-31T23:59:59Z' responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/OrdersSummaryPaginated' example: orders: - agent_name: abc123 company_name: abc123 created_at: '1970-01-01T00:00:01Z' full_name: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 offer_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_offer_reference: abc123 status: confirmed pagination: page: 1 page_size: 1 total_count: 1 total_pages: 1 '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 security: - OAuth2Seller_header_Authorization: - seller-order:read x-code-samples: - lang: curl label: cURL source: | curl -X GET https://seller-api.topi.eu/v1/orders/paginated \ -H "Authorization: Bearer $ACCESS_TOKEN" - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/orders/paginated', { method: 'GET', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}` } }); const data = await response.json(); console.log(data); /v1/shipment: post: tags: - shipment summary: Create a shipment description: >- 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". operationId: shipment#create requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRequestBody' example: metadata: tracking_number: '123456' order_id: 739b63c2-9e58-4964-b38d-4ebb424de242 serial_numbers: - seller_product_reference: reference: 123ab-5343 source: sap serial_number: BA-3456786-334-9 tracking_url: https://example.com/foo responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/Shipment' example: metadata: tracking_number: '123456' serial_numbers: - seller_product_reference: reference: 123ab-5343 source: sap serial_number: BA-3456786-334-9 tracking_url: https://example.com/foo '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '404': description: 'NotFound: Not Found response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-shipment:edit x-code-samples: - lang: curl label: cURL source: | curl -X POST https://seller-api.topi.eu/v1/shipment \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "metadata": { "tracking_number": "123456" }, "order_id": "739b63c2-9e58-4964-b38d-4ebb424de242", "serial_numbers": [ { "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "serial_number": "BA-3456786-334-9" } ], "tracking_url": "https://example.com/foo" }' - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/shipment', { method: 'POST', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ "metadata": { "tracking_number": "123456" }, "order_id": "739b63c2-9e58-4964-b38d-4ebb424de242", "serial_numbers": [ { "seller_product_reference": { "reference": "123ab-5343", "source": "sap" }, "serial_number": "BA-3456786-334-9" } ], "tracking_url": "https://example.com/foo" }) }); const data = await response.json(); console.log(data); /v1/shipping-method: get: tags: - shippingMethod summary: Get all shipping methods description: Get all shipping methods operationId: shippingMethod#getShippingMethods parameters: - name: page in: query description: Which page number to fetch (zero-indexed) allowEmptyValue: true schema: type: integer description: Which page number to fetch (zero-indexed) default: 0 example: 0 format: int64 example: 0 responses: '200': description: OK response. content: application/json: schema: $ref: '#/components/schemas/PaginatedShippingMethodResult' example: data: - id: 739b63c2-9e58-4964-b38d-4ebb424de242 is_in_store_pickup: true name: United Parcel Service seller_shipping_method_reference: Sandbox Shipping Service supported: true pagination: has_more: false page: 0 '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 security: - OAuth2Seller_header_Authorization: - seller-shipping-method:read x-code-samples: - lang: curl label: cURL source: | curl -X GET https://seller-api.topi.eu/v1/shipping-method \ -H "Authorization: Bearer $ACCESS_TOKEN" - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/shipping-method', { method: 'GET', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}` } }); const data = await response.json(); console.log(data); /v1/shipping-method/method: post: tags: - shippingMethod summary: Create shipping method description: > 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. operationId: shippingMethod#create requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateShippingMethodPayload' example: is_in_store_pickup: true name: United Parcel Service seller_shipping_method_reference: Sandbox Shipping Service responses: '201': description: Created response. content: application/json: schema: $ref: '#/components/schemas/ShippingMethodResult' example: id: 739b63c2-9e58-4964-b38d-4ebb424de242 is_in_store_pickup: true name: United Parcel Service seller_shipping_method_reference: Sandbox Shipping Service supported: true '400': description: 'BadRequest: Bad Request response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' '401': description: 'Unauthorized: Unauthorized response.' content: application/json: schema: type: string example: abc123 example: abc123 '403': description: 'InvalidScopes: Forbidden response.' content: application/json: schema: type: string example: abc123 example: abc123 '422': description: 'Unprocessable: Unprocessable Entity response.' content: application/vnd.goa.error: schema: $ref: '#/components/schemas/Error' security: - OAuth2Seller_header_Authorization: - seller-shipping-method:edit x-code-samples: - lang: curl label: cURL source: | curl -X POST https://seller-api.topi.eu/v1/shipping-method/method \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "is_in_store_pickup": true, "name": "United Parcel Service", "seller_shipping_method_reference": "Sandbox Shipping Service" }' - lang: javascript label: JavaScript (fetch) source: > const response = await fetch('https://seller-api.topi.eu/v1/shipping-method/method', { method: 'POST', headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ "is_in_store_pickup": true, "name": "United Parcel Service", "seller_shipping_method_reference": "Sandbox Shipping Service" }) }); const data = await response.json(); console.log(data); components: schemas: AddCustomProductRequestBody: type: object properties: product: $ref: '#/components/schemas/CustomProduct' example: product: CategorisationIdentifiers: category: macbook device: macbook_pro_13 manufacturer: apple price: currency: EUR gross: 119000 net: 100000 base_rental_price: currency: EUR gross: 119000 net: 100000 description: aaa manufacturer: abc123 price: currency: EUR gross: 119000 net: 100000 product_standard_identifiers: - id: 123ab-4567 identifier_type: EAN reference: 123ab-5343 title: abc123 required: - product AddProduct: type: object properties: base_rental_price: $ref: '#/components/schemas/MoneyAmount' description: type: string description: Detailed description of the product. example: aaa maxLength: 2000 extra_details: type: array items: $ref: '#/components/schemas/ExtraProductDetails' description: Additional details about the product, such as CPU, memory size, etc. example: - property: memory value: 16GB DDR5 image: $ref: '#/components/schemas/ProductImage' is_active: type: boolean description: Indicates if the product is currently active. example: false manufacturer: type: string description: Name of the product's manufacturer. example: abc123 price: $ref: '#/components/schemas/MoneyAmountWithOptionalTax' product_standard_identifiers: type: array items: $ref: '#/components/schemas/ProductStandardIdentifier' description: >- List of standardized identifiers for the product, such as UPC, EAN, or ISBN. example: - id: 123ab-4567 identifier_type: EAN seller_categories: type: array items: $ref: '#/components/schemas/ProductSellerCategory' description: An array of categories provided by the seller for this product. example: - id: abc123 name: abc123 parent_category_id: abc123 seller_product_references: type: array items: $ref: '#/components/schemas/SellerProductReference' description: An array of the seller's unique references for this product. example: - reference: 123ab-5343 source: sap - reference: 123ab-5343 source: sap minItems: 1 seller_product_type: type: string description: Type of the product, such as hardware, software, service, etc. example: software enum: - hardware - software - service - hardware_built_to_order shop_product_description_url: type: string example: https://example.com/foo format: uri subtitle: type: string description: Subtitle of the product. example: abc123 title: type: string description: Title of the product. example: abc123 example: base_rental_price: currency: EUR gross: 119000 net: 100000 description: aaa extra_details: - property: memory value: 16GB DDR5 image: url: https://example.com/foo is_active: false manufacturer: abc123 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 product_standard_identifiers: - id: 123ab-4567 identifier_type: EAN seller_categories: - id: abc123 name: abc123 parent_category_id: abc123 seller_product_references: - reference: 123ab-5343 source: sap - reference: 123ab-5343 source: sap seller_product_type: software shop_product_description_url: https://example.com/foo subtitle: abc123 title: abc123 required: - title - seller_product_references - price - is_active Address: type: object properties: city: type: string description: City example: abc123 country_code: type: string description: ISO 3166-1 alpha-2 example: DE line1: type: string description: First line (street, number, etc.) example: abc123 line2: type: string description: Second line (flat number, etc.) example: aaa maxLength: 40 postal_code: type: string description: Postal code example: abc123 region: type: string description: Region, county, province, etc. example: abc123 example: city: abc123 country_code: DE line1: abc123 line2: aaa postal_code: abc123 region: abc123 required: - line1 - postal_code - city - country_code Asset: type: object properties: id: type: string description: asset ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ product_id: type: string description: product id inside the topi catalog example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ seller_product_references: type: array items: $ref: '#/components/schemas/SellerProductReference' description: All seller's own references for this asset example: - reference: 123ab-5343 source: sap serial_number: type: string description: This is an id that identifies this asset as unique example: BA-3456786-334-9 status: type: string example: shipped enum: - created - shipped - returned - completed - rejected title: type: string description: The name of the asset example: Pro Laptop 64GB tracking_url: type: string description: the tracking url of this specific asset example: abc123 description: An item included in an order example: id: 739b63c2-9e58-4964-b38d-4ebb424de242 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_product_references: - reference: 123ab-5343 source: sap serial_number: BA-3456786-334-9 status: shipped title: Pro Laptop 64GB tracking_url: abc123 required: - id - product_id - title - seller_product_references - status BaseBasketPriceSummary: type: object properties: available_contract_types: type: array items: type: string description: Different contracts type example: rent enum: - pay_now - rent description: >- The available ways in which this product can be checked out via topi. example: - rent default_tenure: type: integer description: The default tenure for the product. example: 1 format: int64 identifier: type: string description: >- unique identifier for this pricing request, used to keep track of items and prices in FE example: abc123 is_supported: type: boolean description: Whether the product can be checked out through topi at all example: true pay_now: $ref: '#/components/schemas/PayNowContractTerm' rent: type: array items: $ref: '#/components/schemas/RentContractTerm' description: Details of all rental options available for the product. example: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summary: type: string description: >- A string that can be rendered in the page about whether topi is available. example: Rent with topi for €24.32/month total_pay_now: $ref: '#/components/schemas/PayNowContractTerm' total_rent: type: array items: $ref: '#/components/schemas/RentContractTerm' description: >- The total rent price for the item including sublines multiplied by the quantity example: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 example: available_contract_types: - rent default_tenure: 1 identifier: abc123 is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summary: Rent with topi for €24.32/month total_pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 total_rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 required: - summary - is_supported - available_contract_types - default_tenure BaseCalculatePriceSummary: type: object properties: available_contract_types: type: array items: type: string description: Different contracts type example: rent enum: - pay_now - rent description: >- The available ways in which this product can be checked out via topi. example: - rent is_supported: type: boolean description: Whether the product can be checked out through topi at all example: true pay_now: $ref: '#/components/schemas/PayNowContractTerm' rent: type: array items: $ref: '#/components/schemas/RentContractTerm' description: Details of all rental options available for the product. example: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summary: type: string description: >- A string that can be rendered in the page about whether topi is available. example: Rent with topi for €24.32/month example: available_contract_types: - rent is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summary: Rent with topi for €24.32/month required: - summary - is_supported - available_contract_types BaseOrderLineItem: type: object properties: base_rental_price: $ref: '#/components/schemas/MoneyAmount' contract_type: type: string description: Different contracts type example: rent enum: - pay_now - rent duration: type: integer description: The duration in months example: 6 enum: - 0 - 6 - 12 - 24 - 30 - 36 - 48 format: int64 monthly_price: $ref: '#/components/schemas/MoneyAmount' pretty_id: type: string description: The pretty ID of the product example: abc123 product_id: type: string description: Product ID inside Topi catalog example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ quantity: type: integer description: Amount of products example: 1 format: int64 selected_first_party_services: type: array items: $ref: '#/components/schemas/FirstPartyService' description: Available first party services for the product example: - additional_values: accessory_type: experiment_charger id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_price: currency: EUR gross: 119000 net: 100000 type: topi_replace seller_product_references: type: array items: $ref: '#/components/schemas/SellerProductReference' description: Partner's own reference for this product example: - reference: 123ab-5343 source: sap subtitle: type: string description: The product subtitle example: abc123 title: type: string description: The product name example: abc123 unit_price: $ref: '#/components/schemas/MoneyAmount' example: base_rental_price: currency: EUR gross: 119000 net: 100000 contract_type: rent duration: 6 monthly_price: currency: EUR gross: 119000 net: 100000 pretty_id: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 quantity: 1 selected_first_party_services: - additional_values: accessory_type: experiment_charger id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_price: currency: EUR gross: 119000 net: 100000 type: topi_replace seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 unit_price: currency: EUR gross: 119000 net: 100000 required: - quantity - title - subtitle - seller_product_references - monthly_price - contract_type - duration - selected_first_party_services BasketPriceSummary: type: object properties: available_contract_types: type: array items: type: string description: Different contracts type example: rent enum: - pay_now - rent description: >- The available ways in which this product can be checked out via topi. example: - rent default_tenure: type: integer description: The default tenure for the product. example: 1 format: int64 identifier: type: string description: >- unique identifier for this pricing request, used to keep track of items and prices in FE example: abc123 is_supported: type: boolean description: Whether the product can be checked out through topi at all example: true pay_now: $ref: '#/components/schemas/PayNowContractTerm' pay_now_excluding_sublines: $ref: '#/components/schemas/PayNowContractTerm' rent: type: array items: $ref: '#/components/schemas/RentContractTerm' description: Details of all rental options available for the product. example: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 rent_excluding_sublines: type: array items: $ref: '#/components/schemas/RentContractTerm' description: The unit rental price for the item excluding sublines example: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 sublines: type: array items: $ref: '#/components/schemas/BaseBasketPriceSummary' description: "Comprehensive pricing summaries for each service item included in this product bundle.\n\t\tSublines provide detailed pricing information for all service components.\n\t\t\n\t\tBusiness Rules:\n\t\t- Contains complete pricing details for each service including rental\n\t\t- Sublines automatically inherit quantity and contract duration from parent product\n\t\t- Pricing calculations support both inclusive and exclusive subline totals\n\t\t- Each subline maintains individual pricing while contributing to overall bundle cost\n\t\t- Service validation ensures only appropriate products are included as sublines\n\t\t\n\t\tExample: Complete pricing breakdown for a laptop bundle showing detailed costs for software installation, data migration, and setup services" example: - available_contract_types: - rent default_tenure: 1 identifier: abc123 is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summary: Rent with topi for €24.32/month total_pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 total_rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summary: type: string description: >- A string that can be rendered in the page about whether topi is available. example: Rent with topi for €24.32/month total_pay_now: $ref: '#/components/schemas/PayNowContractTerm' total_rent: type: array items: $ref: '#/components/schemas/RentContractTerm' description: >- The total rent price for the item including sublines multiplied by the quantity example: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 example: available_contract_types: - rent default_tenure: 1 identifier: abc123 is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 pay_now_excluding_sublines: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 rent_excluding_sublines: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 sublines: - available_contract_types: - rent default_tenure: 1 identifier: abc123 is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summary: Rent with topi for €24.32/month total_pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 total_rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summary: Rent with topi for €24.32/month total_pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 total_rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 required: - summary - is_supported - available_contract_types - default_tenure BasketPricingRequest: type: object properties: base_rental_price: $ref: '#/components/schemas/MoneyAmountWithOptionalTax' identifier: type: string description: >- unique identifier for this pricing request, used to keep track of items and prices in FE example: abc123 price: $ref: '#/components/schemas/MoneyAmountWithOptionalTax' quantity: type: integer description: Quantity of this product. example: 1 format: int64 seller_product_reference: $ref: '#/components/schemas/SellerProductReference' sublines: type: array items: $ref: '#/components/schemas/PricingRequest' description: "Service products to be priced alongside this main product in the pricing calculation.\n\t\tSublines enable sellers to request pricing for bundled service offerings, allowing for comprehensive cost calculations that include both the main product and its associated services.\n\t\t\n\t\tBusiness Rules:\n\t\t- Sublines are only valid for hardware and accessory main products\n\t\t- Each subline must reference a service-category product\n\t\t- Sublines inherit quantities from the parent product\n\t\t- Pricing engine calculates both individual subline costs and combined bundle totals\n\t\t- Rental durations and contract terms are synchronized across main line and sublines\n\t\t\n\t\tExample: Requesting pricing for a tablet (main product) with device setup (sublines)" example: - base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 seller_product_reference: reference: 123ab-5343 source: sap example: base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 identifier: abc123 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 quantity: 1 seller_product_reference: reference: 123ab-5343 source: sap sublines: - base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 seller_product_reference: reference: 123ab-5343 source: sap required: - quantity - seller_product_reference BrandingConfiguration: type: object properties: info_hub_url: type: string description: Url for the info hub to display, if any example: abc123 logo_url: type: string description: Url for the logo to display, if any example: abc123 example: info_hub_url: abc123 logo_url: abc123 BreakdownLine: type: object properties: amount: $ref: '#/components/schemas/MoneyAmount' title: type: string description: The title about the payment item example: Monthly (x36) tooltip: type: string description: The subtitle to show about description for this item example: >- The first rent fee is included in the first payment. More details later, in topi checkout. description: Items that are important for the payment example: amount: currency: EUR gross: 119000 net: 100000 title: Monthly (x36) tooltip: >- The first rent fee is included in the first payment. More details later, in topi checkout. required: - title - amount CalculateBasketPricingRequestBody: type: object properties: pricing_requests: type: array items: $ref: '#/components/schemas/BasketPricingRequest' description: The pricing to request example: - base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 identifier: abc123 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 quantity: 1 seller_product_reference: reference: 123ab-5343 source: sap sublines: - base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 seller_product_reference: reference: 123ab-5343 source: sap example: pricing_requests: - base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 identifier: abc123 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 quantity: 1 seller_product_reference: reference: 123ab-5343 source: sap sublines: - base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 seller_product_reference: reference: 123ab-5343 source: sap required: - pricing_requests CalculateBasketPricingResponseBody: type: object properties: basket_total_pay_now: $ref: '#/components/schemas/MoneyAmountWithRequiredTax' basket_total_rent: $ref: '#/components/schemas/MoneyAmountWithRequiredTax' summaries: type: array items: $ref: '#/components/schemas/BasketPriceSummary' description: Array of price summaries for each product in the basket example: - available_contract_types: - rent default_tenure: 1 identifier: abc123 is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 pay_now_excluding_sublines: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 rent_excluding_sublines: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 sublines: - available_contract_types: - rent default_tenure: 1 identifier: abc123 is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summary: Rent with topi for €24.32/month total_pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 total_rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summary: Rent with topi for €24.32/month total_pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 total_rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 example: basket_total_pay_now: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 basket_total_rent: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summaries: - available_contract_types: - rent default_tenure: 1 identifier: abc123 is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 pay_now_excluding_sublines: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 rent_excluding_sublines: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 sublines: - available_contract_types: - rent default_tenure: 1 identifier: abc123 is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summary: Rent with topi for €24.32/month total_pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 total_rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summary: Rent with topi for €24.32/month total_pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 total_rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 CalculatePriceSummary: type: object properties: available_contract_types: type: array items: type: string description: Different contracts type example: rent enum: - pay_now - rent description: >- The available ways in which this product can be checked out via topi. example: - rent is_supported: type: boolean description: Whether the product can be checked out through topi at all example: true pay_now: $ref: '#/components/schemas/PayNowContractTerm' rent: type: array items: $ref: '#/components/schemas/RentContractTerm' description: Details of all rental options available for the product. example: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 sublines: type: array items: $ref: '#/components/schemas/BaseCalculatePriceSummary' description: "Pricing summaries for each service item bundled with this main product.\n\t\tSublines provide detailed pricing breakdown for individual services within a bundle.\n\t\t\n\t\tBusiness Rules:\n\t\t- Each subline summary contains complete pricing information for a service component\n\t\t- Sublines inherit contract terms and quantities from the parent product\n\t\t- Pricing calculations include both rental and purchase options where applicable\n\t\t- Sublines maintain separate pricing while contributing to bundle totals\n\t\t- Service-category validation ensures only appropriate products are included\n\t\t\n\t\tExample: Pricing summary for a smartphone bundle showing individual costs for screen protection service, and data migration service" example: - available_contract_types: - rent is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summary: Rent with topi for €24.32/month summary: type: string description: >- A string that can be rendered in the page about whether topi is available. example: Rent with topi for €24.32/month example: available_contract_types: - rent is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 sublines: - available_contract_types: - rent is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summary: Rent with topi for €24.32/month summary: Rent with topi for €24.32/month required: - summary - is_supported - available_contract_types CalculatePricingRequestBody: type: object properties: pricing_request: $ref: '#/components/schemas/PricingRequest' example: pricing_request: base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 seller_product_reference: reference: 123ab-5343 source: sap required: - pricing_request CartProductRentalOverview: type: object properties: available_rental_terms: type: array items: $ref: '#/components/schemas/RentContractTerm' description: >- All of the various rental terms topi can provide for this product. Only populated when the product has rental terms. example: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 can_checkout: type: boolean description: Whether or not this product can be checked out with topi. example: false currency: type: string description: >- Currency code, see ISO 4127 (https://www.iso.org/iso-4217-currency-codes.html) (supported: EUR, GBP, USD) example: EUR has_rental_terms: type: boolean description: Whether or not this product has rental terms. example: false quantity: type: integer description: The selected quantity of this product included in the seller's cart. example: 1 format: int64 seller_product_reference: $ref: '#/components/schemas/SellerProductReference' summary: type: string description: >- A string that can be directly rendered in the page describing how this product can be rented through topi. Only populated when the product has rental terms. example: Rent with topi from €23.45/month total_rental_amount: type: integer description: >- The total net rental amount for the product. Only populated when the product has rental terms. example: 1 format: int64 example: available_rental_terms: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 can_checkout: false currency: EUR has_rental_terms: false quantity: 1 seller_product_reference: reference: 123ab-5343 source: sap summary: Rent with topi from €23.45/month total_rental_amount: 1 required: - seller_product_reference - has_rental_terms - quantity CartRentalOverviewRequestBody: type: object properties: products: type: array items: $ref: '#/components/schemas/RentalOverviewRequest' example: - base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 quantity: 1 seller_product_reference: reference: 123ab-5343 source: sap example: products: - base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 quantity: 1 seller_product_reference: reference: 123ab-5343 source: sap required: - products CartRentalOverviewResult: type: object properties: can_checkout: type: boolean description: >- 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 example: false currency: type: string description: >- Currency code, see ISO 4127 (https://www.iso.org/iso-4217-currency-codes.html) (supported: EUR, GBP, USD) example: EUR product_prices: type: array items: $ref: '#/components/schemas/CartProductRentalOverview' example: - available_rental_terms: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 can_checkout: false currency: EUR has_rental_terms: false quantity: 1 seller_product_reference: reference: 123ab-5343 source: sap summary: Rent with topi from €23.45/month total_rental_amount: 1 total_rental_amount: type: integer description: >- Sum of all recommended net rental amounts. Only present when all supplied products have rental terms. example: 1 format: int64 total_rental_summary: type: string description: >- A string representing the minimum total rental amount for the entire topi basket, which can be directly rendered on the cart page. example: Rent with topi from €123.45/month example: can_checkout: false currency: EUR product_prices: - available_rental_terms: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 can_checkout: false currency: EUR has_rental_terms: false quantity: 1 seller_product_reference: reference: 123ab-5343 source: sap summary: Rent with topi from €23.45/month total_rental_amount: 1 total_rental_amount: 1 total_rental_summary: Rent with topi from €123.45/month CatalogImportCategorization: type: object properties: done: type: boolean description: >- True once total > 0 and pending == 0. Mirrors the import.status flip from `ingested` to `completed`. example: false pending: type: integer description: >- Products still in to_be_categorized (async pipeline hasn't reached them yet). example: 1 format: int64 supported: type: integer description: Products successfully categorised (review_status = supported). example: 1 format: int64 to_be_reviewed: type: integer description: Products where the categoriser was uncertain — manual review needed. example: 1 format: int64 total: type: integer description: Total products linked to this import. example: 1 format: int64 unsupported: type: integer description: Products explicitly marked unsupported by the categoriser. example: 1 format: int64 description: >- Per-import categorisation progress. Populated once products from the import are in the database (status >= ingested). While the import is still processing CSV rows the counts will lag behind the final totals; treat them as best-effort snapshots. The pipeline runs asynchronously after ingestion: products start in 'to_be_categorized' (counted as pending) and move to either 'supported' (counted as supported) or 'to_be_reviewed' (LLM judge was uncertain — needs human review). example: done: false pending: 1 supported: 1 to_be_reviewed: 1 total: 1 unsupported: 1 required: - total - pending - supported - to_be_reviewed - unsupported - done CatalogImportJob: type: object properties: categorization: $ref: '#/components/schemas/CatalogImportCategorization' created_at: type: string description: ISO 8601 timestamp when the import job was created. example: '1970-01-01T00:00:01Z' format: date-time error: type: string description: >- Reason the import failed before row processing started (e.g. a required column is missing), populated when status is 'failed'. Row-level failures are reported via 'failed' and 'errors_url' instead. example: abc123 errors_url: type: string description: >- Pre-signed URL to download a CSV file containing rows that failed, populated once the import has finished. example: https://example.com/foo format: uri failed: type: integer description: Number of rows that failed to import. example: 1 format: int64 filename: type: string description: The original filename of the uploaded CSV. example: abc123 id: type: string description: The import job ID. example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ object_path: type: string description: The object path in the storage where the uploaded CSV is located. example: https://example.com/foo format: uri processed: type: integer description: Total number of rows processed so far. example: 1 format: int64 status: type: string description: >- Current status of the import job. - pending: job created, waiting for the seller to upload the CSV. - queued: CSV uploaded, header validated, waiting for a worker. - running: worker is reading rows in chunks and writing them to the DB. - ingested: every row has landed in the DB; async categorisation pipeline is running. - completed: all products have been categorised (no more 'to_be_categorized'). - failed: job hit an unrecoverable error. See the 'error' field. - cancelled: seller cancelled the job via DELETE /imports/:id. example: queued enum: - pending - queued - running - ingested - completed - failed - cancelled succeeded: type: integer description: Number of rows successfully imported. example: 1 format: int64 updated_at: type: string description: ISO 8601 timestamp when the import job was last updated. example: '1970-01-01T00:00:01Z' format: date-time example: categorization: done: false pending: 1 supported: 1 to_be_reviewed: 1 total: 1 unsupported: 1 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' required: - id - status - filename - object_path - processed - succeeded - failed - created_at - updated_at CategorisationIdentifiers: type: object properties: category: type: string description: the category of the product example: macbook device: type: string description: the device of the product example: macbook_pro_13 manufacturer: type: string description: The manufacturer of the product example: apple price: $ref: '#/components/schemas/MoneyAmountWithOptionalGross' example: category: macbook device: macbook_pro_13 manufacturer: apple price: currency: EUR gross: 119000 net: 100000 required: - manufacturer - category - price CategorisationNode: type: object properties: children: type: array items: $ref: '#/components/schemas/CategorisationNode' description: >- The value to return to the Backend from this node if chosen in frontend. example: - children: - {} id: abc123 label: abc123 node_type: abc123 parameter: abc123 threshold: 1 value: abc123 id: type: string example: abc123 label: type: string description: The label to display in the frontend. example: abc123 node_type: type: string description: The kind of node, such as manufacturer, category, device. example: abc123 parameter: type: string description: >- The parameter to evaluate on, if the node is an evaluation node (nodetype = topLow). example: abc123 threshold: type: integer description: The tipping point from where the category goes from 'low' to 'top'. example: 1 format: int64 value: type: string description: >- The value to return to the Backend from this node if chosen in frontend. example: abc123 example: children: - children: - {} id: abc123 label: abc123 node_type: abc123 parameter: abc123 threshold: 1 value: abc123 id: abc123 label: abc123 node_type: abc123 parameter: abc123 threshold: 1 value: abc123 required: - id - node_type CheckSupportedRequestBody: type: object properties: seller_product_references: type: array items: $ref: '#/components/schemas/SellerProductReference' description: the ids for obtains the available contract terms. example: - reference: 123ab-5343 source: sap example: seller_product_references: - reference: 123ab-5343 source: sap required: - seller_product_references CommonPortalAgent: type: object properties: email: type: string description: E-mail example: alice@example.com format: email external_agent_id: type: string description: >- Id number used to identify the sales agent in the seller's internal system example: abc123 name: type: string description: Name of the agent example: abc123 phone: type: string description: Phone number example: abc123 seller_id: type: string description: Seller ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ seller_store_id: type: string description: Id number used to identify the store a PoS agent is operating from example: abc123 description: A sales agent that can login into seller portal example: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 seller_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_store_id: abc123 required: - name - phone - email CompanyInfo: type: object properties: billing_address: $ref: '#/components/schemas/PostalAddress' name: type: string description: Name of the company example: Unicorn Corp minLength: 3 tax_number: type: string description: Tax Identification Number example: '123456789' vat_number: type: string description: VAT registration number example: DE123456789 description: Information about the customer company example: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 ContractTerm: type: object properties: id: type: string description: The internal Id for the contract term example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ description: Basic information regarding contract terms. example: id: 739b63c2-9e58-4964-b38d-4ebb424de242 ContractTerms: type: object properties: pay_now: $ref: '#/components/schemas/PayNowContractTerm' rent: $ref: '#/components/schemas/RentContractTerm' example: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 ContractTermsSummary: type: object properties: can_pay_now: type: boolean description: Indicates whether pay now contract term option is available. example: false can_rent: type: boolean description: Indicates whether rent contract term option is available. example: false rent: $ref: '#/components/schemas/ProductRentContract' example: can_pay_now: false can_rent: false rent: duration: 1 required: - can_pay_now - can_rent CreateImportRequestBody: type: object properties: filename: type: string description: The name of the CSV file to import example: abc123 example: filename: abc123 CreateImportResult: type: object properties: id: type: string description: The import job ID. example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ upload_url: type: string description: The upload url in the storage where the uploaded CSV is located. example: https://example.com/foo format: uri example: id: 739b63c2-9e58-4964-b38d-4ebb424de242 upload_url: https://example.com/foo required: - id - upload_url CreateOfferPayload: type: object properties: customer: $ref: '#/components/schemas/CustomerInfo' draft_offer_id: type: string description: The ID of the draft offer from which an offer is being created example: abc123 exit_redirect: type: string example: https://example.com/foo format: uri expires_at: type: string example: '1970-01-01T00:00:01Z' format: date-time lines: type: array items: $ref: '#/components/schemas/OfferLinePayload' description: List of product lines example: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 minItems: 1 metadata: type: object description: >- Metadata you can attach to and offer. You can store here any JSON information example: affiliate_code: '123456' additionalProperties: type: string example: aaa maxLength: 400 sales_agent: $ref: '#/components/schemas/SalesAgent' sales_channel: type: string example: ecommerce enum: - telesales - ecommerce - in_store_pos seller_offer_reference: type: string description: Seller's own reference for the offer example: ref-1234 shipping: $ref: '#/components/schemas/ShippingInfo' shipping_address: $ref: '#/components/schemas/ShippingAddress' success_redirect: type: string example: https://example.com/foo format: uri description: Payload to create an offer example: customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 draft_offer_id: abc123 exit_redirect: https://www.example.com?lorem=ipsum expires_at: '1970-01-01T00:00:01Z' lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria success_redirect: https://www.example.com?lorem=ipsum required: - seller_offer_reference - expires_at - lines - sales_channel CreatePayload: type: object properties: customer: $ref: '#/components/schemas/CustomerInfo' draft_offer_id: type: string description: The ID of the draft offer from which an offer is being created example: abc123 exit_redirect: type: string example: https://example.com/foo format: uri expires_at: type: string example: '1970-01-01T00:00:01Z' format: date-time lines: type: array items: $ref: '#/components/schemas/OfferLinePayload' description: List of product lines example: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 minItems: 1 metadata: type: object description: >- Metadata you can attach to and offer. You can store here any JSON information example: affiliate_code: '123456' additionalProperties: type: string example: aaa maxLength: 400 oauth_token: type: string description: OAuth2 access token used to perform authorization example: abc123 sales_agent: $ref: '#/components/schemas/SalesAgent' sales_channel: type: string example: ecommerce enum: - telesales - ecommerce - in_store_pos seller_offer_reference: type: string description: Seller's own reference for the offer example: ref-1234 shipping: $ref: '#/components/schemas/ShippingInfo' shipping_address: $ref: '#/components/schemas/ShippingAddress' success_redirect: type: string example: https://example.com/foo format: uri example: customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 draft_offer_id: abc123 exit_redirect: https://www.example.com?lorem=ipsum expires_at: '1970-01-01T00:00:01Z' lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' oauth_token: abc123 sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria success_redirect: https://www.example.com?lorem=ipsum required: - oauth_token - seller_offer_reference - expires_at - lines - sales_channel CreatePayload2: type: object properties: customer: $ref: '#/components/schemas/CustomerInfo' draft_offer_id: type: string description: The ID of the draft offer from which an offer is being created example: abc123 exit_redirect: type: string description: >- 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` example: https://example.com/foo format: uri expires_at: type: string description: Expiration date and time for the offer (UTC) example: '1970-01-01T00:00:01Z' format: date-time lines: type: array items: $ref: '#/components/schemas/OfferLinePayload' description: List of product lines example: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 minItems: 1 metadata: type: object description: >- Metadata you can attach to and offer. You can store here any JSON information example: affiliate_code: '123456' additionalProperties: type: string example: aaa maxLength: 400 sales_agent: $ref: '#/components/schemas/SalesAgent' sales_channel: type: string description: Channel from where the offer is created example: ecommerce enum: - telesales - ecommerce - in_store_pos seller_offer_reference: type: string description: Seller's own reference for the offer example: ref-1234 shipping: $ref: '#/components/schemas/ShippingInfo' shipping_address: $ref: '#/components/schemas/ShippingAddress' success_redirect: type: string description: >- 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` example: https://example.com/foo format: uri example: customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 draft_offer_id: abc123 exit_redirect: https://example.com/foo expires_at: '1970-01-01T00:00:01Z' lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria success_redirect: https://example.com/foo required: - seller_offer_reference - expires_at - lines - sales_channel CreatePayloadWithMandatorySalesAgent: type: object properties: customer: $ref: '#/components/schemas/CustomerInfo' draft_offer_id: type: string description: The ID of the draft offer from which an offer is being created example: abc123 exit_redirect: type: string example: https://example.com/foo format: uri expires_at: type: string example: '1970-01-01T00:00:01Z' format: date-time lines: type: array items: $ref: '#/components/schemas/OfferLinePayload' description: List of product lines example: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 minItems: 1 metadata: type: object description: >- Metadata you can attach to and offer. You can store here any JSON information example: affiliate_code: '123456' additionalProperties: type: string example: aaa maxLength: 400 oauth_token: type: string description: OAuth2 access token used to perform authorization example: abc123 sales_agent: $ref: '#/components/schemas/SalesAgent' sales_channel: type: string example: ecommerce enum: - telesales - ecommerce - in_store_pos seller_offer_reference: type: string description: Seller's own reference for the offer example: ref-1234 shipping: $ref: '#/components/schemas/ShippingInfo' shipping_address: $ref: '#/components/schemas/ShippingAddress' success_redirect: type: string example: https://example.com/foo format: uri example: customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 draft_offer_id: abc123 exit_redirect: https://www.example.com?lorem=ipsum expires_at: '1970-01-01T00:00:01Z' lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' oauth_token: abc123 sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria success_redirect: https://www.example.com?lorem=ipsum required: - sales_agent - oauth_token - seller_offer_reference - expires_at - lines - sales_channel CreatePayloadWithMandatorySalesAgent2: type: object properties: customer: $ref: '#/components/schemas/CustomerInfo' draft_offer_id: type: string description: The ID of the draft offer from which an offer is being created example: abc123 exit_redirect: type: string description: >- 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` example: https://example.com/foo format: uri expires_at: type: string description: Expiration date and time for the offer (UTC) example: '1970-01-01T00:00:01Z' format: date-time lines: type: array items: $ref: '#/components/schemas/OfferLinePayload' description: List of product lines example: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 minItems: 1 metadata: type: object description: >- Metadata you can attach to and offer. You can store here any JSON information example: affiliate_code: '123456' additionalProperties: type: string example: aaa maxLength: 400 sales_agent: $ref: '#/components/schemas/SalesAgent' sales_channel: type: string description: Channel from where the offer is created example: ecommerce enum: - telesales - ecommerce - in_store_pos seller_offer_reference: type: string description: Seller's own reference for the offer example: ref-1234 shipping: $ref: '#/components/schemas/ShippingInfo' shipping_address: $ref: '#/components/schemas/ShippingAddress' success_redirect: type: string description: >- 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` example: https://example.com/foo format: uri example: customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 draft_offer_id: abc123 exit_redirect: https://example.com/foo expires_at: '1970-01-01T00:00:01Z' lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria success_redirect: https://example.com/foo required: - sales_agent - seller_offer_reference - expires_at - lines - sales_channel CreateRequestBody: type: object properties: metadata: type: object description: >- Metadata that you can attach to an order. You can store any JSON information. example: tracking_number: '123456' additionalProperties: type: string example: aaa maxLength: 400 order_id: type: string description: topi order ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ serial_numbers: type: array items: $ref: '#/components/schemas/SerialNumberByAsset' description: The products' serial numbers to register example: - seller_product_reference: reference: 123ab-5343 source: sap serial_number: BA-3456786-334-9 tracking_url: type: string description: The tracking URL of the asset example: https://example.com/foo format: uri example: metadata: tracking_number: '123456' order_id: 739b63c2-9e58-4964-b38d-4ebb424de242 serial_numbers: - seller_product_reference: reference: 123ab-5343 source: sap serial_number: BA-3456786-334-9 tracking_url: https://example.com/foo required: - order_id - serial_numbers CreateShippingMethodPayload: type: object properties: is_in_store_pickup: type: boolean description: Is this shipping method in store pickup example: true name: type: string description: Name for the shipping method. example: United Parcel Service seller_shipping_method_reference: type: string description: Seller's own reference for this shipping method. example: Sandbox Shipping Service example: is_in_store_pickup: true name: United Parcel Service seller_shipping_method_reference: Sandbox Shipping Service required: - seller_shipping_method_reference CursorPageMetadata: type: object properties: has_more: type: boolean description: Whether there are more pages default: false example: false description: Metadata about the returned page example: has_more: false required: - has_more CursorPagePayload: type: object properties: ending_before: type: string description: >- A cursor to use in pagination. It will be the ending point of the list and will not be included in the results. example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ limit: type: integer description: How many results to return per page. default: 0 example: 10 format: int64 minimum: 0 page: type: integer description: Which page number to fetch (zero-indexed) default: 0 example: 0 format: int64 starting_after: type: string description: >- A cursor to use in pagination. It will be the starting point of the list and will not be included in the results. example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ example: ending_before: 739b63c2-9e58-4964-b38d-4ebb424de242 limit: 10 page: 0 starting_after: 739b63c2-9e58-4964-b38d-4ebb424de242 CustomProduct: type: object properties: CategorisationIdentifiers: $ref: '#/components/schemas/CategorisationIdentifiers' base_rental_price: $ref: '#/components/schemas/MoneyAmountWithOptionalGross' description: type: string description: Detailed description of the product. example: aaa maxLength: 2000 manufacturer: type: string description: Name of the product's manufacturer. example: abc123 price: $ref: '#/components/schemas/MoneyAmountWithOptionalGross' product_standard_identifiers: type: array items: $ref: '#/components/schemas/ProductStandardIdentifier' description: >- List of standardized identifiers for the product, such as UPC, EAN, or ISBN. example: - id: 123ab-4567 identifier_type: EAN reference: type: string description: >- The ID related with the source. This value should be unique for that source. example: 123ab-5343 pattern: '[a-zA-Z0-9._-]' minLength: 1 title: type: string description: Title of the product. example: abc123 example: CategorisationIdentifiers: category: macbook device: macbook_pro_13 manufacturer: apple price: currency: EUR gross: 119000 net: 100000 base_rental_price: currency: EUR gross: 119000 net: 100000 description: aaa manufacturer: abc123 price: currency: EUR gross: 119000 net: 100000 product_standard_identifiers: - id: 123ab-4567 identifier_type: EAN reference: 123ab-5343 title: abc123 required: - title - reference - price - manufacturer - description - CategorisationIdentifiers CustomerInfo: type: object properties: company: $ref: '#/components/schemas/CompanyInfo' customer_group: type: string description: The name of the customer group if the customer is assigned to any. example: education email: type: string description: Customer e-mail that will be used to retrieve the offer example: alice@example.com format: email full_name: type: string description: The full name of the person doing the checkout operation. example: John Butler phone_number: type: string description: Phone number associated to the offer. example: abc123 description: Customer information example: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 DashboardResponseBody: type: object properties: url: type: string description: The url to the seller metrics dashboard example: abc123 example: url: abc123 required: - url Error: type: object properties: fault: type: boolean description: Is the error a server-side fault? example: false id: type: string description: >- ID is a unique identifier for this particular occurrence of the problem. example: 123abc message: type: string description: >- Message is a human-readable explanation specific to this occurrence of the problem. example: parameter 'p' must be an integer name: type: string description: Name is the name of this class of errors. example: bad_request temporary: type: boolean description: Is the error temporary? example: false timeout: type: boolean description: Is the error a timeout? example: false example: fault: false id: 123abc message: parameter 'p' must be an integer name: bad_request temporary: false timeout: false required: - name - id - message - temporary - timeout - fault EventPayload: type: object properties: deliveryAttempt: type: integer description: The number of times the service has attempted to deliver a message. example: 1 format: int64 message: $ref: '#/components/schemas/MessagePayload' subscription: type: string description: The subscription name. example: abc123 description: This is the message payload from the PubSub topic. example: deliveryAttempt: 1 message: attributes: abc123: abc123 data: abc123 messageId: abc123 orderingKey: abc123 publishTime: abc123 subscription: abc123 ExtraProductDetails: type: object properties: property: type: string description: Name of the property. example: abc123 value: type: string example: abc123 example: property: memory value: 16GB DDR5 required: - property - value FilteringOption: type: object properties: operation: type: string description: the operation to filter on e.g > example: '>' enum: - < - '>' - '=' - '!=' - <= - '>=' - contains - does not contain property: type: string description: the property to filter on e.g title example: abc123 value: type: string description: the value to match example: abc123 description: option for filtering products on the backend example: operation: '>' property: abc123 value: abc123 required: - property - operation - value FirstPartyService: type: object properties: additional_values: $ref: '#/components/schemas/FirstPartyServiceAdditionalValues' id: type: string description: The internal Id for the first party service example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ monthly_price: $ref: '#/components/schemas/MoneyAmount' type: type: string example: topi_replace enum: - topi_repair - topi_replace - demo_first_party_service - topi_accessory - topi_data_deletion_certificate - topi_care_plus_synaxon - topi_care_plus_michaelag description: Info for first party service example: additional_values: accessory_type: experiment_charger id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_price: currency: EUR gross: 119000 net: 100000 type: topi_replace required: - id - type - monthly_price FirstPartyServiceAdditionalValues: type: object properties: accessory_type: type: string description: >- if the first party service is an accessory, this value is the kind of the accessory example: experiment_charger description: Additional values for specific first party types. example: accessory_type: experiment_charger FullOrderResult: type: object properties: assets: type: array items: $ref: '#/components/schemas/Asset' description: A list of assets in an offer example: - id: 739b63c2-9e58-4964-b38d-4ebb424de242 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_product_references: - reference: 123ab-5343 source: sap serial_number: BA-3456786-334-9 status: shipped title: Pro Laptop 64GB tracking_url: abc123 canceled_at: type: string example: '1970-01-01T00:00:01Z' format: date-time created_at: type: string example: '1970-01-01T00:00:01Z' format: date-time customer_info: $ref: '#/components/schemas/CustomerInfo' id: type: string description: topi order ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ metadata: type: object description: >- Metadata you can attach to and order. You can store here any JSON information example: tracking_number: '123456' additionalProperties: type: string example: aaa maxLength: 400 offer_created_at: type: string example: '1970-01-01T00:00:01Z' format: date-time offer_id: type: string description: Reference to the topi offer ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ order_lines: type: array items: $ref: '#/components/schemas/OrderLineItem' description: A list of order lines in an order example: - base_rental_price: currency: EUR gross: 119000 net: 100000 contract_type: rent duration: 6 monthly_price: currency: EUR gross: 119000 net: 100000 pretty_id: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 quantity: 1 selected_first_party_services: - additional_values: accessory_type: experiment_charger id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_price: currency: EUR gross: 119000 net: 100000 type: topi_replace seller_product_references: - reference: 123ab-5343 source: sap sublines: - base_rental_price: currency: EUR gross: 119000 net: 100000 contract_type: rent duration: 6 monthly_price: currency: EUR gross: 119000 net: 100000 pretty_id: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 quantity: 1 selected_first_party_services: - additional_values: accessory_type: experiment_charger id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_price: currency: EUR gross: 119000 net: 100000 type: topi_replace seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 unit_price: currency: EUR gross: 119000 net: 100000 subtitle: abc123 title: abc123 unit_price: currency: EUR gross: 119000 net: 100000 sales_agent: $ref: '#/components/schemas/SalesAgent' seller_info: $ref: '#/components/schemas/SellerInfo' seller_offer_reference: type: string description: Seller's own reference for this order example: abc123 shipping_address: $ref: '#/components/schemas/ShippingAddress' shipping_info: $ref: '#/components/schemas/ShippingInfo' status: type: string example: confirmed enum: - created - confirmed - acknowledged - accepted - partially_fulfilled - completed - canceled - rejected tracking_urls: type: array items: type: string example: abc123 description: All the tracking urls example: - abc123 description: Full information about an order example: assets: - id: 739b63c2-9e58-4964-b38d-4ebb424de242 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_product_references: - reference: 123ab-5343 source: sap serial_number: BA-3456786-334-9 status: shipped title: Pro Laptop 64GB tracking_url: abc123 canceled_at: '1970-01-01T00:00:01Z' created_at: '1970-01-01T00:00:01Z' customer_info: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 metadata: tracking_number: '123456' offer_created_at: '1970-01-01T00:00:01Z' offer_id: 739b63c2-9e58-4964-b38d-4ebb424de242 order_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 contract_type: rent duration: 6 monthly_price: currency: EUR gross: 119000 net: 100000 pretty_id: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 quantity: 1 selected_first_party_services: - additional_values: accessory_type: experiment_charger id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_price: currency: EUR gross: 119000 net: 100000 type: topi_replace seller_product_references: - reference: 123ab-5343 source: sap sublines: - base_rental_price: currency: EUR gross: 119000 net: 100000 contract_type: rent duration: 6 monthly_price: currency: EUR gross: 119000 net: 100000 pretty_id: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 quantity: 1 selected_first_party_services: - additional_values: accessory_type: experiment_charger id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_price: currency: EUR gross: 119000 net: 100000 type: topi_replace seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 unit_price: currency: EUR gross: 119000 net: 100000 subtitle: abc123 title: abc123 unit_price: currency: EUR gross: 119000 net: 100000 sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 seller_info: address: city: abc123 country_code: DE line1: abc123 line2: aaa postal_code: abc123 region: abc123 capability_add_custom_products: false capability_anonymized_pricing: false capability_anonymous_ecom_offer_creation: false capability_bundles: false capability_chatbot_id: abc123 capability_dual_pricing: false capability_hide_buy_now: false capability_international_shipment: false currency: abc123 email: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 logo_url: abc123 name: abc123 parent_seller_id: abc123 pdf_reader_assistant_id: abc123 pretty_name: abc123 product_reference_source: abc123 seller_offer_reference: abc123 shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria shipping_info: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service status: confirmed tracking_urls: - abc123 required: - created_at - offer_created_at - customer_info - shipping_address - order_lines - tracking_urls - seller_info - id - offer_id - seller_offer_reference - status - assets GetServiceResult: type: object properties: archived: type: boolean description: Whether or not the product has been archived by the seller. example: false available_contract_terms: $ref: '#/components/schemas/ContractTermsSummary' base_rental_price: $ref: '#/components/schemas/MoneyAmount' description: type: string description: Detailed description of the product. example: abc123 ean: type: string description: The EAN code of the product. example: abc123 list_price: $ref: '#/components/schemas/MoneyAmount' manufacturer: type: string description: The manufacturer of the product. example: abc123 mpn: type: string description: The MPN code of the product. example: abc123 origin: type: string description: >- The origin of the product, 'manual','automatic' or 'central_catalog'. example: abc123 pretty_id: type: string description: >- The pretty id/reference that the seller filled. Can be a non-unique dummy id. example: abc123 pricing_category: type: string description: The pricing category of the product. example: abc123 product_id: type: string description: Product ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ reference: type: string description: The product reference number that matches a search term. example: abc123 seller_product_references: type: array items: $ref: '#/components/schemas/SellerProductReference' description: An array of the seller's unique references for this product. example: - reference: 123ab-5343 source: sap subtitle: type: string description: Subtitle of the product. example: abc123 title: type: string description: Title of the product. example: abc123 example: archived: false available_contract_terms: can_pay_now: false can_rent: false rent: duration: 1 base_rental_price: currency: EUR gross: 119000 net: 100000 description: abc123 ean: abc123 list_price: currency: EUR gross: 119000 net: 100000 manufacturer: abc123 mpn: abc123 origin: abc123 pretty_id: abc123 pricing_category: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 reference: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 required: - product_id - list_price - title - seller_product_references - available_contract_terms - reference - origin - manufacturer Headroom: type: object properties: expected_residual_value_ratio: type: number description: Expected residual value ratio for this tenure example: 1 format: double headroom_ratio: type: number description: Headroom ratio applied to this product for this tenure example: 1 format: double is_default: type: boolean description: Whether this tenure is the default tenure example: false tenure: type: integer description: The tenure in months (6, 12, 24, or 36) example: 1 format: int64 example: expected_residual_value_ratio: 1 headroom_ratio: 1 is_default: false tenure: 1 required: - is_default - tenure - headroom_ratio - expected_residual_value_ratio IDPayload: type: object properties: id: type: integer description: Metabase identifier example: 1 format: int64 example: id: 1 required: - id ImportCatalogRequestBody: type: object properties: products: type: array items: $ref: '#/components/schemas/AddProduct' description: Product payload example: - base_rental_price: currency: EUR gross: 119000 net: 100000 description: aaa extra_details: - property: memory value: 16GB DDR5 image: url: https://example.com/foo is_active: false manufacturer: abc123 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 product_standard_identifiers: - id: 123ab-4567 identifier_type: EAN seller_categories: - id: abc123 name: abc123 parent_category_id: abc123 seller_product_references: - reference: 123ab-5343 source: sap - reference: 123ab-5343 source: sap seller_product_type: software shop_product_description_url: https://example.com/foo subtitle: abc123 title: abc123 - base_rental_price: currency: EUR gross: 119000 net: 100000 description: aaa extra_details: - property: memory value: 16GB DDR5 image: url: https://example.com/foo is_active: false manufacturer: abc123 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 product_standard_identifiers: - id: 123ab-4567 identifier_type: EAN seller_categories: - id: abc123 name: abc123 parent_category_id: abc123 seller_product_references: - reference: 123ab-5343 source: sap - reference: 123ab-5343 source: sap seller_product_type: software shop_product_description_url: https://example.com/foo subtitle: abc123 title: abc123 minItems: 1 example: products: - base_rental_price: currency: EUR gross: 119000 net: 100000 description: aaa extra_details: - property: memory value: 16GB DDR5 image: url: https://example.com/foo is_active: false manufacturer: abc123 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 product_standard_identifiers: - id: 123ab-4567 identifier_type: EAN seller_categories: - id: abc123 name: abc123 parent_category_id: abc123 seller_product_references: - reference: 123ab-5343 source: sap - reference: 123ab-5343 source: sap seller_product_type: software shop_product_description_url: https://example.com/foo subtitle: abc123 title: abc123 - base_rental_price: currency: EUR gross: 119000 net: 100000 description: aaa extra_details: - property: memory value: 16GB DDR5 image: url: https://example.com/foo is_active: false manufacturer: abc123 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 product_standard_identifiers: - id: 123ab-4567 identifier_type: EAN seller_categories: - id: abc123 name: abc123 parent_category_id: abc123 seller_product_references: - reference: 123ab-5343 source: sap - reference: 123ab-5343 source: sap seller_product_type: software shop_product_description_url: https://example.com/foo subtitle: abc123 title: abc123 required: - products ImportResult: type: object properties: id: type: string description: The id of the import processing example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ status: type: string description: The current import status. example: started enum: - created - started - completed - failed summary: $ref: '#/components/schemas/SummaryInfo' example: id: 739b63c2-9e58-4964-b38d-4ebb424de242 status: started summary: sample_products_rejected: - error_code: unsupported_product error_description: the product type is not supported seller_product_reference: reference: 123ab-5343 source: sap total_products: 1 total_products_imported: 1 total_products_rejected: 1 required: - id - status ItemSummary: type: object properties: identifier: type: string description: Identifier of the item. example: abc123 pay_now: $ref: '#/components/schemas/PayNow' pay_now_excluding_sublines: $ref: '#/components/schemas/PayNow' rent: type: array items: $ref: '#/components/schemas/Rent' description: The unit rent amount per item for all rental durations. example: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 rent_excluding_sublines: type: array items: $ref: '#/components/schemas/Rent' description: >- The unit rent amount per item for all rental durations for main line only. example: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 total_pay_now: $ref: '#/components/schemas/PayNow' total_rent: type: array items: $ref: '#/components/schemas/Rent' description: The total rent amount per item for all rental durations. example: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 example: identifier: abc123 pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 pay_now_excluding_sublines: pay_now_amount: currency: EUR gross: 119000 net: 100000 rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 rent_excluding_sublines: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 total_pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 total_rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 required: - identifier - rent - pay_now - total_rent - total_pay_now - rent_excluding_sublines - pay_now_excluding_sublines ListRecommendedRentalPricesRequestBody: type: object properties: pricing_requests: type: array items: $ref: '#/components/schemas/PricingRequest' description: List of product pricing to request. example: - base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 seller_product_reference: reference: 123ab-5343 source: sap example: pricing_requests: - base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 seller_product_reference: reference: 123ab-5343 source: sap required: - pricing_requests MessagePayload: type: object properties: attributes: type: object description: Attributes of the message. example: abc123: abc123 additionalProperties: type: string example: abc123 data: type: string description: Base64 data body. example: abc123 messageId: type: string description: The message ID. example: abc123 orderingKey: type: string description: The ordering key of the message. example: abc123 publishTime: type: string description: The time at which the message was published. example: abc123 example: attributes: abc123: abc123 data: abc123 messageId: abc123 orderingKey: abc123 publishTime: abc123 required: - data MoneyAmount: type: object properties: currency: type: string description: >- Currency code, see ISO 4127 (https://www.iso.org/iso-4217-currency-codes.html) (supported: EUR, GBP, USD) example: EUR gross: type: integer description: Gross amount of money, expressed in the minor unit for the currency example: 119000 format: int64 net: type: integer description: Net amount of money, expressed in the minor unit for the currency example: 100000 format: int64 example: currency: EUR gross: 119000 net: 100000 required: - gross - net - currency MoneyAmountWithOptionalGross: type: object properties: currency: type: string description: >- Currency code, see ISO 4127 (https://www.iso.org/iso-4217-currency-codes.html) (supported: EUR, GBP, USD) example: EUR gross: type: integer description: Gross amount of money, expressed in the minor unit for the currency example: 119000 format: int64 net: type: integer description: Net amount of money, expressed in the minor unit for the currency example: 100000 format: int64 example: currency: EUR gross: 119000 net: 100000 required: - net - currency MoneyAmountWithOptionalTax: type: object properties: currency: type: string description: >- Currency code, see ISO 4127 (https://www.iso.org/iso-4217-currency-codes.html) (supported: EUR, GBP, USD) example: EUR gross: type: integer description: Gross amount of money, expressed in the minor unit for the currency example: 119000 format: int64 net: type: integer description: Net amount of money, expressed in the minor unit for the currency example: 100000 format: int64 tax_rate: type: integer description: >- Tax rate, expressed in the the rate multiplied by 10,000. Example for 21.5%: `0.215 * 10000 = 2150` example: 1900 format: int64 example: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 required: - gross - net - currency MoneyAmountWithRequiredTax: type: object properties: currency: type: string description: >- Currency code, see ISO 4127 (https://www.iso.org/iso-4217-currency-codes.html) (supported: EUR, GBP, USD) example: EUR gross: type: integer description: Gross amount of money, expressed in the minor unit for the currency example: 119000 format: int64 net: type: integer description: Net amount of money, expressed in the minor unit for the currency example: 100000 format: int64 tax_rate: type: integer description: >- Tax rate, expressed in the the rate multiplied by 10,000. Example for 21.5%: `0.215 * 10000 = 2150` example: 1900 format: int64 example: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 required: - tax_rate - gross - net - currency MoneyValue: type: object properties: amount: type: integer description: money amount, expressed in the minor unit for the currency example: 34000 format: int64 currency: type: string description: >- Currency code, see ISO 4127 (https://www.iso.org/iso-4217-currency-codes.html) (supported: EUR, GBP, USD) example: EUR example: amount: 34000 currency: EUR required: - amount - currency NewPortalAgent: type: object properties: email: type: string description: E-mail example: alice@example.com format: email external_agent_id: type: string description: >- Id number used to identify the sales agent in the seller's internal system example: abc123 name: type: string description: Name of the agent example: abc123 phone: type: string description: Phone number example: abc123 seller_id: type: string description: Seller ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ seller_store_id: type: string description: Id number used to identify the store a PoS agent is operating from example: abc123 topi_relevant: type: boolean description: >- Whether the user is relevant for driving topi GMV, this allows us to opt out users that are managers or are not expected to do much sales from reporting. default: true example: false example: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 seller_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_store_id: abc123 topi_relevant: false required: - name - phone - email NewPortalBulkAgents: type: object properties: new_agents: type: array items: $ref: '#/components/schemas/CommonPortalAgent' description: List con agents to add. example: - email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 seller_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_store_id: abc123 example: new_agents: - email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 seller_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_store_id: abc123 OauthPayload: type: object properties: oauth_token: type: string description: OAuth2 access token used to perform authorization example: abc123 example: oauth_token: abc123 required: - oauth_token OfferLine: type: object properties: base_rental_price: $ref: '#/components/schemas/MoneyAmountWithOptionalGross' bundle_index: type: string description: the bundle_index to group the product lines to example: abc123 price: $ref: '#/components/schemas/MoneyAmountWithOptionalGross' product_id: type: string description: the topi id of the product example: abc123 quantity: type: integer description: How many units of the product example: 2 format: int64 minimum: 1 maximum: 10000 seller_product_reference: $ref: '#/components/schemas/SellerProductReference' subtitle: type: string description: The product subtitle example: abc123 title: type: string description: The product name example: abc123 example: base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 required: - quantity - price - seller_product_reference - title OfferLinePayload: type: object properties: base_rental_price: $ref: '#/components/schemas/MoneyAmountWithOptionalGross' bundle_index: type: string description: the bundle_index to group the product lines to example: abc123 price: $ref: '#/components/schemas/MoneyAmountWithOptionalGross' product_id: type: string description: the topi id of the product example: abc123 quantity: type: integer description: How many units of the product example: 2 format: int64 minimum: 1 maximum: 10000 seller_product_reference: $ref: '#/components/schemas/SellerProductReference' sub_lines: type: array items: $ref: '#/components/schemas/SubLinePayload' description: >- Optional list of service lines that are attached to this offer line. Only applicable for hardware and accessories. example: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: type: string description: The product subtitle example: abc123 title: type: string description: The product name example: abc123 description: A product line within an offer example: base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 required: - quantity - price - seller_product_reference - title OfferLineResult: type: object properties: applied_discount_id: type: string description: The ID of any discount applied to the offer line example: abc123 available_contract_terms: $ref: '#/components/schemas/ContractTerms' base_rental_price: $ref: '#/components/schemas/MoneyAmount' bundle_id: type: string description: The id of the bundle to which this product belongs to example: abc123 id: type: string description: topi offerline ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ origin: type: string description: >- The origin of the product, 'manual','automatic' or 'central_catalog'. example: abc123 pretty_id: type: string description: The pretty ID of the product example: abc123 price: $ref: '#/components/schemas/MoneyAmount' pricing_category: type: string description: >- The pricing category of the product, e.g. 'hardware', 'accessory', 'service' example: abc123 product_id: type: string description: The internal topi id of the product which this line is based upon example: abc123 quantity: type: integer description: How many units of the product example: 2 format: int64 minimum: 1 selected_contract_type: type: string description: Selected contract type example: abc123 seller_product_references: type: array items: $ref: '#/components/schemas/SellerProductReference' description: Seller's own reference for the product example: - reference: 123ab-5343 source: sap sublines: type: array items: $ref: '#/components/schemas/OfferLineResultBase' description: "Service items bundled with this offer line from the seller's perspective.\n\t\tSublines represent additional services or components that sellers can attach to their hardware or accessory products to create comprehensive product offerings.\n\t\t\n\t\tBusiness Rules:\n\t\t- Only hardware and accessory products can have sublines attached\n\t\t- Sublines must be service-category products from the seller's catalog\n\t\t- Sublines automatically inherit quantity and contract terms from the parent line\n\t\t- Each subline maintains a parent-child relationship for tracking and pricing\n\t\t- Sellers can manage sublines independently while maintaining bundle integrity\n\t\t\n\t\tExample: A laptop (main line) with setup service, and software installation (sublines)" example: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: type: string description: The product subtitle example: abc123 title: type: string description: The product name example: abc123 example: applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap sublines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 required: - id - quantity - price - seller_product_references - title - origin - pricing_category OfferLineResultBase: type: object properties: applied_discount_id: type: string description: The ID of any discount applied to the offer line example: abc123 available_contract_terms: $ref: '#/components/schemas/ContractTerms' base_rental_price: $ref: '#/components/schemas/MoneyAmount' bundle_id: type: string description: The id of the bundle to which this product belongs to example: abc123 id: type: string description: topi offerline ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ origin: type: string description: >- The origin of the product, 'manual','automatic' or 'central_catalog'. example: abc123 pretty_id: type: string description: The pretty ID of the product example: abc123 price: $ref: '#/components/schemas/MoneyAmount' pricing_category: type: string description: >- The pricing category of the product, e.g. 'hardware', 'accessory', 'service' example: abc123 product_id: type: string description: The internal topi id of the product which this line is based upon example: abc123 quantity: type: integer description: How many units of the product example: 2 format: int64 minimum: 1 selected_contract_type: type: string description: Selected contract type example: abc123 seller_product_references: type: array items: $ref: '#/components/schemas/SellerProductReference' description: Seller's own reference for the product example: - reference: 123ab-5343 source: sap subtitle: type: string description: The product subtitle example: abc123 title: type: string description: The product name example: abc123 description: A product line within an offer example: applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 required: - id - quantity - price - seller_product_references - title - origin - pricing_category OfferListResult: type: object properties: offers: type: array items: $ref: '#/components/schemas/OfferResult' description: The list of offers example: - checkout_redirect_url: >- http://www.topi-sandbox.eu/offer/739b63c2-9e58-4964-b38d-4ebb424de242%2Fv1?token=abcd created_at: '1970-01-01T00:00:01Z' customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 expires_at: '1970-01-01T00:00:01Z' id: 739b63c2-9e58-4964-b38d-4ebb424de242 lines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap sublines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' pricing_overview: breakdown: - amount: currency: EUR gross: 119000 net: 100000 title: Monthly (x36) tooltip: >- The first rent fee is included in the first payment. More details later, in topi checkout. instead_of_amount: currency: EUR gross: 119000 net: 100000 items_summaries: - identifier: abc123 pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 pay_now_excluding_sublines: pay_now_amount: currency: EUR gross: 119000 net: 100000 rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 rent_excluding_sublines: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 total_pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 total_rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 shipping_amount: currency: EUR gross: 119000 net: 100000 total_amount: currency: EUR gross: 119000 net: 100000 sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_redirect_url: >- http://www.seller.topi.eu/offer/739b63c2-9e58-4964-b38d-4ebb424de242%2Fv1 seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria status: voided pagination: $ref: '#/components/schemas/PaginationMetadata' description: List of offers with pagination metadata example: offers: - checkout_redirect_url: >- http://www.topi-sandbox.eu/offer/739b63c2-9e58-4964-b38d-4ebb424de242%2Fv1?token=abcd created_at: '1970-01-01T00:00:01Z' customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 expires_at: '1970-01-01T00:00:01Z' id: 739b63c2-9e58-4964-b38d-4ebb424de242 lines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap sublines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' pricing_overview: breakdown: - amount: currency: EUR gross: 119000 net: 100000 title: Monthly (x36) tooltip: >- The first rent fee is included in the first payment. More details later, in topi checkout. instead_of_amount: currency: EUR gross: 119000 net: 100000 items_summaries: - identifier: abc123 pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 pay_now_excluding_sublines: pay_now_amount: currency: EUR gross: 119000 net: 100000 rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 rent_excluding_sublines: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 total_pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 total_rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 shipping_amount: currency: EUR gross: 119000 net: 100000 total_amount: currency: EUR gross: 119000 net: 100000 sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_redirect_url: >- http://www.seller.topi.eu/offer/739b63c2-9e58-4964-b38d-4ebb424de242%2Fv1 seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria status: voided pagination: page: 1 page_size: 1 total_count: 1 total_pages: 1 required: - offers - pagination OfferParsingResult: type: object properties: line_items: type: array items: $ref: '#/components/schemas/OfferParsinglineItem' description: The line items contained within the uploaded pdf offer. example: - calculated_price_summary: available_contract_types: - rent is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 sublines: - available_contract_types: - rent is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summary: Rent with topi for €24.32/month summary: Rent with topi for €24.32/month input_quantity: 1 product: archived: false available_contract_terms: can_pay_now: false can_rent: false rent: duration: 1 base_rental_price: currency: EUR gross: 119000 net: 100000 description: abc123 ean: abc123 list_price: currency: EUR gross: 119000 net: 100000 manufacturer: abc123 mpn: abc123 origin: abc123 pretty_id: abc123 pricing_category: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 reference: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 offer_reference: type: string description: >- the seller-facing offer reference, most likely coming from the ERP system example: abc123 unprocessed_items: type: array items: $ref: '#/components/schemas/OfferParsingUnproccesedItem' description: The line items that could not be processed. example: - CategorisationIdentifiers: category: macbook device: macbook_pro_13 manufacturer: apple price: currency: EUR gross: 119000 net: 100000 input_description: abc123 input_price: currency: EUR gross: 119000 net: 100000 input_quantity: 1 input_reference: abc123 input_title: abc123 manufacturer: abc123 example: line_items: - calculated_price_summary: available_contract_types: - rent is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 sublines: - available_contract_types: - rent is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summary: Rent with topi for €24.32/month summary: Rent with topi for €24.32/month input_quantity: 1 product: archived: false available_contract_terms: can_pay_now: false can_rent: false rent: duration: 1 base_rental_price: currency: EUR gross: 119000 net: 100000 description: abc123 ean: abc123 list_price: currency: EUR gross: 119000 net: 100000 manufacturer: abc123 mpn: abc123 origin: abc123 pretty_id: abc123 pricing_category: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 reference: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 offer_reference: abc123 unprocessed_items: - CategorisationIdentifiers: category: macbook device: macbook_pro_13 manufacturer: apple price: currency: EUR gross: 119000 net: 100000 input_description: abc123 input_price: currency: EUR gross: 119000 net: 100000 input_quantity: 1 input_reference: abc123 input_title: abc123 manufacturer: abc123 OfferParsingUnproccesedItem: type: object properties: CategorisationIdentifiers: $ref: '#/components/schemas/CategorisationIdentifiers' input_description: type: string description: Description of the product provided in the offer. example: abc123 input_price: $ref: '#/components/schemas/MoneyAmountWithOptionalGross' input_quantity: type: integer example: 1 format: int64 input_reference: type: string description: The product reference number provided in the offer. example: abc123 input_title: type: string description: Title of the product provided in the offer. example: abc123 manufacturer: type: string example: abc123 example: CategorisationIdentifiers: category: macbook device: macbook_pro_13 manufacturer: apple price: currency: EUR gross: 119000 net: 100000 input_description: abc123 input_price: currency: EUR gross: 119000 net: 100000 input_quantity: 1 input_reference: abc123 input_title: abc123 manufacturer: abc123 OfferParsinglineItem: type: object properties: calculated_price_summary: $ref: '#/components/schemas/CalculatePriceSummary' input_quantity: type: integer example: 1 format: int64 product: $ref: '#/components/schemas/SearchProductResult' example: calculated_price_summary: available_contract_types: - rent is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 sublines: - available_contract_types: - rent is_supported: true pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: - duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 summary: Rent with topi for €24.32/month summary: Rent with topi for €24.32/month input_quantity: 1 product: archived: false available_contract_terms: can_pay_now: false can_rent: false rent: duration: 1 base_rental_price: currency: EUR gross: 119000 net: 100000 description: abc123 ean: abc123 list_price: currency: EUR gross: 119000 net: 100000 manufacturer: abc123 mpn: abc123 origin: abc123 pretty_id: abc123 pricing_category: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 reference: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 required: - product - input_quantity - calculated_price_summary OfferResult: type: object properties: checkout_redirect_url: type: string example: https://example.com/foo format: uri created_at: type: string example: '1970-01-01T00:00:01Z' format: date-time customer: $ref: '#/components/schemas/CustomerInfo' expires_at: type: string example: '1970-01-01T00:00:01Z' format: date-time id: type: string description: topi offer ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ lines: type: array items: $ref: '#/components/schemas/OfferLineResult' description: List of product lines example: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap sublines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: type: object description: >- Metadata you can attach to and offer. You can store here any JSON information example: affiliate_code: '123456' additionalProperties: type: string example: aaa maxLength: 400 pricing_overview: $ref: '#/components/schemas/PricingOverview' sales_agent: $ref: '#/components/schemas/SalesAgent' sales_channel: type: string example: ecommerce enum: - telesales - ecommerce - in_store_pos seller_offer_redirect_url: type: string example: https://example.com/foo format: uri seller_offer_reference: type: string description: Seller's own reference for the offer example: ref-1234 shipping: $ref: '#/components/schemas/ShippingInfo' shipping_address: $ref: '#/components/schemas/ShippingAddress' status: type: string example: voided enum: - created - voided - accepted - expired - rejected - pending_review - declined description: Basic information about an offer example: checkout_redirect_url: >- http://www.topi-sandbox.eu/offer/739b63c2-9e58-4964-b38d-4ebb424de242%2Fv1?token=abcd created_at: '1970-01-01T00:00:01Z' customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 expires_at: '1970-01-01T00:00:01Z' id: 739b63c2-9e58-4964-b38d-4ebb424de242 lines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap sublines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' pricing_overview: breakdown: - amount: currency: EUR gross: 119000 net: 100000 title: Monthly (x36) tooltip: >- The first rent fee is included in the first payment. More details later, in topi checkout. instead_of_amount: currency: EUR gross: 119000 net: 100000 items_summaries: - identifier: abc123 pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 pay_now_excluding_sublines: pay_now_amount: currency: EUR gross: 119000 net: 100000 rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 rent_excluding_sublines: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 total_pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 total_rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 shipping_amount: currency: EUR gross: 119000 net: 100000 total_amount: currency: EUR gross: 119000 net: 100000 sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_redirect_url: >- http://www.seller.topi.eu/offer/739b63c2-9e58-4964-b38d-4ebb424de242%2Fv1 seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria status: voided required: - id - created_at - expires_at - checkout_redirect_url - seller_offer_redirect_url - status - customer - seller_offer_reference - shipping_address - lines - sales_channel OfferWithReferenceResult: type: object properties: checkout_redirect_url: type: string example: https://example.com/foo format: uri created_at: type: string example: '1970-01-01T00:00:01Z' format: date-time customer: $ref: '#/components/schemas/CustomerInfo' expires_at: type: string example: '1970-01-01T00:00:01Z' format: date-time id: type: string description: topi offer ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ lines: type: array items: $ref: '#/components/schemas/OfferLineResult' description: List of product lines example: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap sublines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: type: object description: >- Metadata you can attach to and offer. You can store here any JSON information example: affiliate_code: '123456' additionalProperties: type: string example: aaa maxLength: 400 pricing_overview: $ref: '#/components/schemas/PricingOverview' sales_agent: $ref: '#/components/schemas/SalesAgent' sales_channel: type: string example: ecommerce enum: - telesales - ecommerce - in_store_pos seller_offer_redirect_url: type: string example: https://example.com/foo format: uri seller_offer_reference: type: string description: Seller's own reference for the offer example: ref-1234 shipping: $ref: '#/components/schemas/ShippingInfo' shipping_address: $ref: '#/components/schemas/ShippingAddress' status: type: string example: voided enum: - created - voided - accepted - expired - rejected - pending_review - declined example: checkout_redirect_url: >- http://www.topi-sandbox.eu/offer/739b63c2-9e58-4964-b38d-4ebb424de242%2Fv1?token=abcd created_at: '1970-01-01T00:00:01Z' customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 expires_at: '1970-01-01T00:00:01Z' id: 739b63c2-9e58-4964-b38d-4ebb424de242 lines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap sublines: - applied_discount_id: abc123 available_contract_terms: pay_now: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 rent: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_id: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 origin: abc123 pretty_id: abc123 price: currency: EUR gross: 119000 net: 100000 pricing_category: abc123 product_id: abc123 quantity: 2 selected_contract_type: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' pricing_overview: breakdown: - amount: currency: EUR gross: 119000 net: 100000 title: Monthly (x36) tooltip: >- The first rent fee is included in the first payment. More details later, in topi checkout. instead_of_amount: currency: EUR gross: 119000 net: 100000 items_summaries: - identifier: abc123 pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 pay_now_excluding_sublines: pay_now_amount: currency: EUR gross: 119000 net: 100000 rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 rent_excluding_sublines: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 total_pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 total_rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 shipping_amount: currency: EUR gross: 119000 net: 100000 total_amount: currency: EUR gross: 119000 net: 100000 sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_redirect_url: >- http://www.seller.topi.eu/offer/739b63c2-9e58-4964-b38d-4ebb424de242%2Fv1 seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria status: voided required: - seller_offer_reference - id - created_at - expires_at - checkout_redirect_url - seller_offer_redirect_url - status - customer - shipping_address - lines - sales_channel OrderLineItem: type: object properties: base_rental_price: $ref: '#/components/schemas/MoneyAmount' contract_type: type: string description: Different contracts type example: rent enum: - pay_now - rent duration: type: integer description: The duration in months example: 6 enum: - 0 - 6 - 12 - 24 - 30 - 36 - 48 format: int64 monthly_price: $ref: '#/components/schemas/MoneyAmount' pretty_id: type: string description: The pretty ID of the product example: abc123 product_id: type: string description: Product ID inside Topi catalog example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ quantity: type: integer description: Amount of products example: 1 format: int64 selected_first_party_services: type: array items: $ref: '#/components/schemas/FirstPartyService' description: Available first party services for the product example: - additional_values: accessory_type: experiment_charger id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_price: currency: EUR gross: 119000 net: 100000 type: topi_replace seller_product_references: type: array items: $ref: '#/components/schemas/SellerProductReference' description: Partner's own reference for this product example: - reference: 123ab-5343 source: sap sublines: type: array items: $ref: '#/components/schemas/BaseOrderLineItem' description: "Service items that were confirmed as part of this order line.\n\t\tSublines represent the services or components that were selected during the offer phase and are now part of the confirmed order, maintaining the same relationship structure as the original offer.\n\t\t\n\t\tBusiness Rules:\n\t\t- Sublines are created from offer sublines when the offer is accepted\n\t\t- Each subline maintains the same contract terms and quantity as the parent order line\n\t\t- Sublines preserve their service-category classification and pricing\n\t\t- Parent-child relationships are maintained throughout the order lifecycle\n\t\t- Sublines can be individually tracked for fulfillment and billing purposes\n\t\t\n\t\tExample: A confirmed order for a smartphone with screen protection, and setup service as sublines" example: - base_rental_price: currency: EUR gross: 119000 net: 100000 contract_type: rent duration: 6 monthly_price: currency: EUR gross: 119000 net: 100000 pretty_id: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 quantity: 1 selected_first_party_services: - additional_values: accessory_type: experiment_charger id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_price: currency: EUR gross: 119000 net: 100000 type: topi_replace seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 unit_price: currency: EUR gross: 119000 net: 100000 subtitle: type: string description: The product subtitle example: abc123 title: type: string description: The product name example: abc123 unit_price: $ref: '#/components/schemas/MoneyAmount' example: base_rental_price: currency: EUR gross: 119000 net: 100000 contract_type: rent duration: 6 monthly_price: currency: EUR gross: 119000 net: 100000 pretty_id: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 quantity: 1 selected_first_party_services: - additional_values: accessory_type: experiment_charger id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_price: currency: EUR gross: 119000 net: 100000 type: topi_replace seller_product_references: - reference: 123ab-5343 source: sap sublines: - base_rental_price: currency: EUR gross: 119000 net: 100000 contract_type: rent duration: 6 monthly_price: currency: EUR gross: 119000 net: 100000 pretty_id: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 quantity: 1 selected_first_party_services: - additional_values: accessory_type: experiment_charger id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_price: currency: EUR gross: 119000 net: 100000 type: topi_replace seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 unit_price: currency: EUR gross: 119000 net: 100000 subtitle: abc123 title: abc123 unit_price: currency: EUR gross: 119000 net: 100000 required: - quantity - title - subtitle - seller_product_references - monthly_price - contract_type - duration - selected_first_party_services OrderResult: type: object properties: assets: type: array items: $ref: '#/components/schemas/Asset' description: A list of assets in an offer example: - id: 739b63c2-9e58-4964-b38d-4ebb424de242 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_product_references: - reference: 123ab-5343 source: sap serial_number: BA-3456786-334-9 status: shipped title: Pro Laptop 64GB tracking_url: abc123 id: type: string description: topi order ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ metadata: type: object description: >- Metadata you can attach to and order. You can store here any JSON information example: tracking_number: '123456' additionalProperties: type: string example: aaa maxLength: 400 offer_id: type: string description: Reference to the topi offer ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ seller_offer_reference: type: string description: Seller's own reference for this order example: abc123 status: type: string example: confirmed enum: - created - confirmed - acknowledged - accepted - partially_fulfilled - completed - canceled - rejected description: Basic information about an order example: assets: - id: 739b63c2-9e58-4964-b38d-4ebb424de242 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_product_references: - reference: 123ab-5343 source: sap serial_number: BA-3456786-334-9 status: shipped title: Pro Laptop 64GB tracking_url: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 metadata: tracking_number: '123456' offer_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_offer_reference: abc123 status: confirmed required: - id - offer_id - seller_offer_reference - status - assets OrderSummary: type: object properties: agent_name: type: string description: Agent owner of the order example: abc123 company_name: type: string description: name of the customer company example: abc123 created_at: type: string example: '1970-01-01T00:00:01Z' format: date-time full_name: type: string description: Full name of the customer example: abc123 id: type: string description: topi order ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ offer_id: type: string description: Reference to the topi offer ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ seller_offer_reference: type: string description: Agent owner of the order example: abc123 status: type: string example: confirmed enum: - created - confirmed - acknowledged - accepted - partially_fulfilled - completed - canceled - rejected description: Summary info about an order example: agent_name: abc123 company_name: abc123 created_at: '1970-01-01T00:00:01Z' full_name: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 offer_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_offer_reference: abc123 status: confirmed required: - id - offer_id - created_at - agent_name - seller_offer_reference - status - company_name - full_name OrdersSummary: type: object properties: orders: type: array items: $ref: '#/components/schemas/OrderSummary' description: an array with the orders requested example: - agent_name: abc123 company_name: abc123 created_at: '1970-01-01T00:00:01Z' full_name: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 offer_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_offer_reference: abc123 status: confirmed example: orders: - agent_name: abc123 company_name: abc123 created_at: '1970-01-01T00:00:01Z' full_name: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 offer_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_offer_reference: abc123 status: confirmed OrdersSummaryPaginated: type: object properties: orders: type: array items: $ref: '#/components/schemas/OrderSummary' description: an array with the orders requested example: - agent_name: abc123 company_name: abc123 created_at: '1970-01-01T00:00:01Z' full_name: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 offer_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_offer_reference: abc123 status: confirmed pagination: $ref: '#/components/schemas/PaginationMetadata' description: Orders list with pagination metadata example: orders: - agent_name: abc123 company_name: abc123 created_at: '1970-01-01T00:00:01Z' full_name: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 offer_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_offer_reference: abc123 status: confirmed pagination: page: 1 page_size: 1 total_count: 1 total_pages: 1 required: - orders - pagination PageMetadata: type: object properties: has_more: type: boolean description: Whether there are more pages default: false example: false page: type: integer description: Current page number (zero-indexed) default: 0 example: 0 format: int64 description: Metadata about the returned page example: has_more: false page: 0 required: - page - has_more PagePayload: type: object properties: page: type: integer description: Which page number to fetch (zero-indexed) default: 0 example: 0 format: int64 example: page: 0 PaginatedShippingMethodResult: type: object properties: data: type: array items: $ref: '#/components/schemas/ShippingMethodResult' description: Array of ShippingMethodResult example: - id: 739b63c2-9e58-4964-b38d-4ebb424de242 is_in_store_pickup: true name: United Parcel Service seller_shipping_method_reference: Sandbox Shipping Service supported: true pagination: $ref: '#/components/schemas/PageMetadata' example: data: - id: 739b63c2-9e58-4964-b38d-4ebb424de242 is_in_store_pickup: true name: United Parcel Service seller_shipping_method_reference: Sandbox Shipping Service supported: true pagination: has_more: false page: 0 required: - data - pagination Pagination: type: object properties: limit: type: integer description: the size of the page example: 1 format: int64 page: type: integer description: the index of the page example: 1 format: int64 example: limit: 1 page: 1 PaginationMetadata: type: object properties: page: type: integer description: Current page number example: 1 format: int64 page_size: type: integer description: Number of items per page example: 1 format: int64 total_count: type: integer description: Total number of items example: 1 format: int64 total_pages: type: integer description: Total number of pages example: 1 format: int64 example: page: 1 page_size: 1 total_count: 1 total_pages: 1 PaginationResult: type: object properties: limit: type: integer description: the size of the page example: 1 format: int64 page: type: integer description: the index of the page example: 1 format: int64 totalPages: type: integer description: Total amount of pages available example: 1 format: int64 totalRows: type: integer description: The total amount of rows example: 1 format: int64 example: limit: 1 page: 1 totalPages: 1 totalRows: 1 ParseOfferTextRequestBody: type: object properties: source_text: type: string example: abc123 example: source_text: abc123 required: - source_text PayNow: type: object properties: pay_now_amount: $ref: '#/components/schemas/MoneyAmount' example: pay_now_amount: currency: EUR gross: 119000 net: 100000 required: - pay_now_amount PayNowContractTerm: type: object properties: amount: $ref: '#/components/schemas/MoneyAmountWithRequiredTax' id: type: string description: The internal Id for the contract term example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ example: amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 id: 739b63c2-9e58-4964-b38d-4ebb424de242 required: - amount PortalBulkSummary: type: object properties: count_new_agents: type: integer description: Number of new agents added example: 1 format: int64 failed_agents: type: array items: type: string example: abc123 description: List of agents that failed to be added example: - abc123 example: count_new_agents: 1 failed_agents: - abc123 required: - count_new_agents PortalSalesAgent: type: object properties: email: type: string description: E-mail example: alice@example.com format: email external_agent_id: type: string description: >- Id number used to identify the sales agent in the seller's internal system example: abc123 id: type: string description: Auth0 Sales Agent ID example: auth0|63881a171828b3997ad1b3fc language: type: string description: User language example: abc123 last_login: type: string example: '1970-01-01T00:00:01Z' format: date-time name: type: string description: Name of the agent example: abc123 phone: type: string description: Phone number example: abc123 seller_id: type: string description: Seller ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ seller_store_id: type: string description: Id number used to identify the store a PoS agent is operating from example: abc123 status: type: string description: User status example: abc123 topi_relevant: type: boolean description: >- Whether the user is relevant for driving topi GMV, this allows us to opt out users that are managers or are not expected to do much sales from reporting. example: false example: email: alice@example.com external_agent_id: abc123 id: auth0|63881a171828b3997ad1b3fc language: abc123 last_login: '1970-01-01T00:00:01Z' name: abc123 phone: abc123 seller_id: 739b63c2-9e58-4964-b38d-4ebb424de242 seller_store_id: abc123 status: abc123 topi_relevant: false required: - id - name - phone - email PostalAddress: type: object properties: city: type: string description: City example: Munich country_code: type: string description: Country code (ISO 3166-1 alpha-2) example: DE line1: type: string description: First line (street, number, etc.) example: 10 Downing Street line2: type: string description: Second line (flat number, etc.) example: Flat 42 maxLength: 40 postal_code: type: string description: Postal code example: '10243' region: type: string description: Region, county, province, etc. example: Bavaria example: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria required: - line1 - postal_code - city - country_code PricingOverview: type: object properties: breakdown: type: array items: $ref: '#/components/schemas/BreakdownLine' description: >- Different lines with the different items that are important for the payment. example: - amount: currency: EUR gross: 119000 net: 100000 title: Monthly (x36) tooltip: >- The first rent fee is included in the first payment. More details later, in topi checkout. instead_of_amount: $ref: '#/components/schemas/MoneyAmount' items_summaries: type: array items: $ref: '#/components/schemas/ItemSummary' description: 'Price summary for each item: main line and sublines.' example: - identifier: abc123 pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 pay_now_excluding_sublines: pay_now_amount: currency: EUR gross: 119000 net: 100000 rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 rent_excluding_sublines: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 total_pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 total_rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 shipping_amount: $ref: '#/components/schemas/MoneyAmount' total_amount: $ref: '#/components/schemas/MoneyAmount' description: An Overview of the total price to pay by the user using topi. example: breakdown: - amount: currency: EUR gross: 119000 net: 100000 title: Monthly (x36) tooltip: >- The first rent fee is included in the first payment. More details later, in topi checkout. instead_of_amount: currency: EUR gross: 119000 net: 100000 items_summaries: - identifier: abc123 pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 pay_now_excluding_sublines: pay_now_amount: currency: EUR gross: 119000 net: 100000 rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 rent_excluding_sublines: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 total_pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 total_rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 shipping_amount: currency: EUR gross: 119000 net: 100000 total_amount: currency: EUR gross: 119000 net: 100000 required: - instead_of_amount - total_amount - breakdown PricingRequest: type: object properties: base_rental_price: $ref: '#/components/schemas/MoneyAmountWithOptionalTax' price: $ref: '#/components/schemas/MoneyAmountWithOptionalTax' seller_product_reference: $ref: '#/components/schemas/SellerProductReference' example: base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 seller_product_reference: reference: 123ab-5343 source: sap required: - seller_product_reference ProductDetails: type: object properties: archived: type: boolean description: Whether or not the product has been archived by the seller. example: false available_contract_terms: $ref: '#/components/schemas/ContractTermsSummary' base_rental_price: $ref: '#/components/schemas/MoneyAmount' categorisation_identifiers: $ref: '#/components/schemas/CategorisationIdentifiers' description: type: string description: Detailed description of the product. example: abc123 ean: type: string description: The EAN code of the product. example: abc123 list_price: $ref: '#/components/schemas/MoneyAmount' manufacturer: type: string description: The manufacturer of the product. example: abc123 mpn: type: string description: The MPN code of the product. example: abc123 origin: type: string description: >- The origin of the product, 'manual','automatic' or 'central_catalog'. example: abc123 pretty_id: type: string description: >- The pretty id/reference that the seller filled. Can be a non-unique dummy id. example: abc123 pricing_category: type: string description: The pricing category of the product. example: abc123 product_id: type: string description: Product ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ reference: type: string description: The product reference number that matches a search term. example: abc123 seller_product_references: type: array items: $ref: '#/components/schemas/SellerProductReference' description: An array of the seller's unique references for this product. example: - reference: 123ab-5343 source: sap subtitle: type: string description: Subtitle of the product. example: abc123 title: type: string description: Title of the product. example: abc123 example: archived: false available_contract_terms: can_pay_now: false can_rent: false rent: duration: 1 base_rental_price: currency: EUR gross: 119000 net: 100000 categorisation_identifiers: category: macbook device: macbook_pro_13 manufacturer: apple price: currency: EUR gross: 119000 net: 100000 description: abc123 ean: abc123 list_price: currency: EUR gross: 119000 net: 100000 manufacturer: abc123 mpn: abc123 origin: abc123 pretty_id: abc123 pricing_category: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 reference: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 required: - product_id - list_price - title - seller_product_references - available_contract_terms - reference - origin - manufacturer ProductImage: type: object properties: url: type: string description: URL to the hosted image. example: https://example.com/foo format: uri example: url: https://example.com/foo ProductPaginationResult: type: object properties: limit: type: integer description: the size of the page example: 1 format: int64 page: type: integer description: the index of the page example: 1 format: int64 rows: type: array items: $ref: '#/components/schemas/SearchProductResult' description: The products returned. example: - archived: false available_contract_terms: can_pay_now: false can_rent: false rent: duration: 1 base_rental_price: currency: EUR gross: 119000 net: 100000 description: abc123 ean: abc123 list_price: currency: EUR gross: 119000 net: 100000 manufacturer: abc123 mpn: abc123 origin: abc123 pretty_id: abc123 pricing_category: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 reference: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 totalPages: type: integer description: Total amount of pages available example: 1 format: int64 totalRows: type: integer description: The total amount of rows example: 1 format: int64 example: limit: 1 page: 1 rows: - archived: false available_contract_terms: can_pay_now: false can_rent: false rent: duration: 1 base_rental_price: currency: EUR gross: 119000 net: 100000 description: abc123 ean: abc123 list_price: currency: EUR gross: 119000 net: 100000 manufacturer: abc123 mpn: abc123 origin: abc123 pretty_id: abc123 pricing_category: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 reference: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 totalPages: 1 totalRows: 1 ProductRentContract: type: object properties: duration: type: integer description: Duration of the rental contract in months. example: 1 format: int64 example: duration: 1 required: - duration ProductRentalPricingDetails: type: object properties: currency: type: string description: >- Currency code, see ISO 4127 (https://www.iso.org/iso-4217-currency-codes.html) (supported: EUR, GBP, USD) example: EUR has_rental_terms: type: boolean description: Does the product have rental terms. example: false monthly_rental_amount: type: integer description: >- The Net monthly rental amount, in cents. This amount is exclusive of tax. example: 100000 format: int64 monthly_rental_terms: $ref: '#/components/schemas/RentContractTerm' seller_product_reference: $ref: '#/components/schemas/SellerProductReference' summary: type: string description: >- A string that can be directly rendered in the page about whether topi is available. example: Rent with topi from €23.45/month example: currency: EUR has_rental_terms: false monthly_rental_amount: 100000 monthly_rental_terms: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 seller_product_reference: reference: 123ab-5343 source: sap summary: Rent with topi from €23.45/month required: - seller_product_reference - has_rental_terms ProductSellerCategory: type: object properties: id: type: string description: The id of the category in the seller's system example: abc123 name: type: string description: The name of the category example: abc123 parent_category_id: type: string description: The ID of the parent category, if it exists. example: abc123 example: id: abc123 name: abc123 parent_category_id: abc123 required: - name - id ProductStandardIdentifier: type: object properties: id: type: string description: The product identifier value example: 123ab-4567 identifier_type: type: string description: The kind of identifier standard example: EAN example: id: 123ab-4567 identifier_type: EAN ProductSummary: type: object properties: available_contract_terms: $ref: '#/components/schemas/ContractTermsSummary' id: type: string description: topi product's ID. example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ is_supported: type: boolean description: Indicates whether the product is supported to be in a topi basket. example: false seller_product_reference: $ref: '#/components/schemas/SellerProductReference' example: available_contract_terms: can_pay_now: false can_rent: false rent: duration: 1 id: 739b63c2-9e58-4964-b38d-4ebb424de242 is_supported: false seller_product_reference: reference: 123ab-5343 source: sap required: - seller_product_reference - id - is_supported - available_contract_terms ProductsSummary: type: object properties: products: type: array items: $ref: '#/components/schemas/ProductSummary' description: >- Array of product summaries, detailing each product's specifications and available contract terms. example: - available_contract_terms: can_pay_now: false can_rent: false rent: duration: 1 id: 739b63c2-9e58-4964-b38d-4ebb424de242 is_supported: false seller_product_reference: reference: 123ab-5343 source: sap example: products: - available_contract_terms: can_pay_now: false can_rent: false rent: duration: 1 id: 739b63c2-9e58-4964-b38d-4ebb424de242 is_supported: false seller_product_reference: reference: 123ab-5343 source: sap required: - products PubSubPayload: type: object properties: authToken: type: string description: JWT token used to perform authorization example: abc123 deliveryAttempt: type: integer description: The number of times the service has attempted to deliver a message. example: 1 format: int64 message: $ref: '#/components/schemas/MessagePayload' subscription: type: string description: The subscription name. example: abc123 verificationToken: type: string description: Verification token sent as a query string example: abc123 description: data sent when the request is initiated by Google example: authToken: abc123 deliveryAttempt: 1 message: attributes: abc123: abc123 data: abc123 messageId: abc123 orderingKey: abc123 publishTime: abc123 subscription: abc123 verificationToken: abc123 required: - verificationToken Reference: type: object properties: reference: type: string description: >- The ID related with the source. This value should be unique for that source. example: 123ab-5343 pattern: '[a-zA-Z0-9._-]' minLength: 1 example: reference: 123ab-5343 Rent: type: object properties: duration: type: integer description: Duration of the rental term in months. example: 12 enum: - 6 - 12 - 24 - 36 format: int64 monthly_amount: $ref: '#/components/schemas/MoneyAmount' example: duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 required: - monthly_amount - duration RentContractTerm: type: object properties: duration: type: integer description: Duration of the rental term in months. example: 12 enum: - 6 - 12 - 24 - 36 format: int64 id: type: string description: The internal Id for the contract term example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ monthly_amount: $ref: '#/components/schemas/MoneyAmountWithRequiredTax' example: duration: 12 id: 739b63c2-9e58-4964-b38d-4ebb424de242 monthly_amount: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 required: - monthly_amount - duration RentTenure: type: object properties: duration: type: integer description: The duration in months example: 6 enum: - 0 - 6 - 12 - 24 - 30 - 36 - 48 format: int64 example: duration: 6 RentTenures: type: object properties: durations: type: array items: type: integer example: 12 enum: - 6 - 12 - 24 - 30 - 36 - 48 format: int64 description: The durations in months example: - 12 example: durations: - 12 RentalOverviewRequest: type: object properties: base_rental_price: $ref: '#/components/schemas/MoneyAmountWithOptionalTax' price: $ref: '#/components/schemas/MoneyAmountWithOptionalTax' quantity: type: integer description: Quantity of this product. example: 1 format: int64 seller_product_reference: $ref: '#/components/schemas/SellerProductReference' example: base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 quantity: 1 seller_product_reference: reference: 123ab-5343 source: sap required: - quantity - seller_product_reference SalesAgent: type: object properties: email: type: string description: E-mail example: alice@example.com format: email external_agent_id: type: string description: >- Id number used to identify the sales agent in the seller's internal system example: abc123 name: type: string description: Name of the agent example: abc123 phone: type: string description: Phone number example: abc123 description: Sales agent related to an offer example: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 required: - name - phone - email SearchAndFilterProductsPaginatedRequestBody: type: object properties: filtering_logic: type: string description: The logic to use for filtering the products. Can be 'and' or 'or'. example: OR enum: - AND - OR filtering_options: type: array items: $ref: '#/components/schemas/FilteringOption' description: Filtering options for the search example: - operation: '>' property: abc123 value: abc123 example: filtering_logic: OR filtering_options: - operation: '>' property: abc123 value: abc123 SearchProductResult: type: object properties: archived: type: boolean description: Whether or not the product has been archived by the seller. example: false available_contract_terms: $ref: '#/components/schemas/ContractTermsSummary' base_rental_price: $ref: '#/components/schemas/MoneyAmount' description: type: string description: Detailed description of the product. example: abc123 ean: type: string description: The EAN code of the product. example: abc123 list_price: $ref: '#/components/schemas/MoneyAmount' manufacturer: type: string description: The manufacturer of the product. example: abc123 mpn: type: string description: The MPN code of the product. example: abc123 origin: type: string description: >- The origin of the product, 'manual','automatic' or 'central_catalog'. example: abc123 pretty_id: type: string description: >- The pretty id/reference that the seller filled. Can be a non-unique dummy id. example: abc123 pricing_category: type: string description: The pricing category of the product. example: abc123 product_id: type: string description: Product ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ reference: type: string description: The product reference number that matches a search term. example: abc123 seller_product_references: type: array items: $ref: '#/components/schemas/SellerProductReference' description: An array of the seller's unique references for this product. example: - reference: 123ab-5343 source: sap subtitle: type: string description: Subtitle of the product. example: abc123 title: type: string description: Title of the product. example: abc123 example: archived: false available_contract_terms: can_pay_now: false can_rent: false rent: duration: 1 base_rental_price: currency: EUR gross: 119000 net: 100000 description: abc123 ean: abc123 list_price: currency: EUR gross: 119000 net: 100000 manufacturer: abc123 mpn: abc123 origin: abc123 pretty_id: abc123 pricing_category: abc123 product_id: 739b63c2-9e58-4964-b38d-4ebb424de242 reference: abc123 seller_product_references: - reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 required: - product_id - list_price - title - seller_product_references - available_contract_terms - reference - origin - manufacturer SellerInfo: type: object properties: address: $ref: '#/components/schemas/Address' capability_add_custom_products: type: boolean description: If the seller can add custom products example: false capability_anonymized_pricing: type: boolean description: If the seller wishes to anonymize catalog prices example: false capability_anonymous_ecom_offer_creation: type: boolean description: Ability to skip required shipping address for ecom offers. example: false capability_bundles: type: boolean description: If the seller has bundles enabled example: false capability_chatbot_id: type: string description: >- Chatbot id for the seller. This enables a chatbase chatbot for the seller example: abc123 capability_dual_pricing: type: boolean description: If true, the seller has the Dual Pricing system enabled example: false capability_hide_buy_now: type: boolean description: If the seller should hide purchase only as option. example: false capability_international_shipment: type: boolean description: If the seller has international shipment enabled example: false currency: type: string description: The currency of the seller example: abc123 email: type: string description: The seller email example: abc123 id: type: string description: The seller id example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ logo_url: type: string description: The seller logo example: abc123 name: type: string description: The name of the seller example: abc123 parent_seller_id: type: string description: the ID of the parent seller, we use this for multipliers example: abc123 pdf_reader_assistant_id: type: string description: >- The assistant ID to use for PDF reader, use null to disable PDF reader example: abc123 pretty_name: type: string description: The pretty, customer-facing name of the seller example: abc123 product_reference_source: type: string description: The seller product reference source example: abc123 example: address: city: abc123 country_code: DE line1: abc123 line2: aaa postal_code: abc123 region: abc123 capability_add_custom_products: false capability_anonymized_pricing: false capability_anonymous_ecom_offer_creation: false capability_bundles: false capability_chatbot_id: abc123 capability_dual_pricing: false capability_hide_buy_now: false capability_international_shipment: false currency: abc123 email: abc123 id: 739b63c2-9e58-4964-b38d-4ebb424de242 logo_url: abc123 name: abc123 parent_seller_id: abc123 pdf_reader_assistant_id: abc123 pretty_name: abc123 product_reference_source: abc123 required: - id - name - address - email - product_reference_source - capability_dual_pricing - capability_hide_buy_now - capability_anonymized_pricing - capability_bundles - capability_anonymous_ecom_offer_creation - capability_international_shipment - capability_add_custom_products - currency SellerPayload: type: object properties: seller_id: type: string description: Seller ID example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ example: seller_id: 739b63c2-9e58-4964-b38d-4ebb424de242 required: - seller_id SellerProductReference: type: object properties: reference: type: string description: >- The ID related with the source. This value should be unique for that source. example: 123ab-5343 pattern: '[a-zA-Z0-9._-]' minLength: 1 source: type: string description: The seller internal source name for this reference type. example: sap minLength: 1 example: reference: 123ab-5343 source: sap required: - source - reference SerialNumberByAsset: type: object properties: seller_product_reference: $ref: '#/components/schemas/SellerProductReference' serial_number: type: string description: >- The serial number given by the device manufacturer, usually found on the packaging example: BA-3456786-334-9 example: seller_product_reference: reference: 123ab-5343 source: sap serial_number: BA-3456786-334-9 required: - seller_product_reference - serial_number SetMetadataRequestBody: type: object properties: metadata: type: object description: Metadata to attach. You can store any JSON information. example: tracking_number: '123456' additionalProperties: type: string example: aaa maxLength: 400 example: metadata: tracking_number: '123456' required: - metadata Shipment: type: object properties: metadata: type: object description: >- Metadata that you can attach to an order. You can store any JSON information. example: tracking_number: '123456' additionalProperties: type: string example: aaa maxLength: 400 serial_numbers: type: array items: $ref: '#/components/schemas/SerialNumberByAsset' description: The products' serial numbers to register example: - seller_product_reference: reference: 123ab-5343 source: sap serial_number: BA-3456786-334-9 tracking_url: type: string description: The tracking URL of the asset example: https://example.com/foo format: uri example: metadata: tracking_number: '123456' serial_numbers: - seller_product_reference: reference: 123ab-5343 source: sap serial_number: BA-3456786-334-9 tracking_url: https://example.com/foo required: - serial_numbers ShippingAddress: type: object properties: city: type: string description: City example: Munich country_code: type: string description: Country code (ISO 3166-1 alpha-2) example: DE line1: type: string description: First line (street, number, etc.) example: 10 Downing Street line2: type: string description: Second line (flat number, etc.) example: Flat 42 maxLength: 40 postal_code: type: string description: Postal code example: '10243' recipient_name: type: string description: Name of the recipient example: Felix Wolf region: type: string description: Region, county, province, etc. example: Bavaria description: >- Shipping Address. If the sales_channel is ecommerce, this field will be required example: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria required: - line1 - postal_code - city - country_code ShippingInfo: type: object properties: is_in_store_pickup: type: boolean description: If the shipping info is in store pickup example: false price: $ref: '#/components/schemas/MoneyAmount' seller_shipping_reference: type: string description: Seller's own reference for shipping method example: Sandbox Shipping Service description: Shipping information example: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service required: - seller_shipping_reference - price ShippingMethodResult: type: object properties: id: type: string description: topi shipping method ID. example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ is_in_store_pickup: type: boolean description: Is this shipping method in store pickup example: true name: type: string description: Name for the shipping method. example: United Parcel Service seller_shipping_method_reference: type: string description: Seller's own reference for this shipping method. example: Sandbox Shipping Service supported: type: boolean description: Supported shipping method. example: true description: Basic information about a shipping method. example: id: 739b63c2-9e58-4964-b38d-4ebb424de242 is_in_store_pickup: true name: United Parcel Service seller_shipping_method_reference: Sandbox Shipping Service supported: true required: - id - seller_shipping_method_reference - supported SimulateScenarioRequestBody: type: object properties: scenario_input: example: abc123 example: scenario_input: abc123 required: - scenario_input SubLinePayload: type: object properties: base_rental_price: $ref: '#/components/schemas/MoneyAmountWithOptionalGross' bundle_index: type: string description: the bundle_index to group the product lines to example: abc123 price: $ref: '#/components/schemas/MoneyAmountWithOptionalGross' product_id: type: string description: the topi id of the product example: abc123 quantity: type: integer description: How many units of the product example: 2 format: int64 minimum: 1 maximum: 10000 seller_product_reference: $ref: '#/components/schemas/SellerProductReference' subtitle: type: string description: The product subtitle example: abc123 title: type: string description: The product name example: abc123 description: A service line that is attached to a hardware or accessory example: base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 required: - quantity - price - seller_product_reference - title SummaryInfo: type: object properties: sample_products_rejected: type: array items: $ref: '#/components/schemas/SummaryProductRejected' description: 'Deprecated: unused' example: - error_code: unsupported_product error_description: the product type is not supported seller_product_reference: reference: 123ab-5343 source: sap total_products: type: integer description: Total number of products processed up to the current request. example: 1 format: int64 total_products_imported: type: integer description: Number of products successfully processed and imported. example: 1 format: int64 total_products_rejected: type: integer description: 'Deprecated: unused' example: 1 format: int64 example: sample_products_rejected: - error_code: unsupported_product error_description: the product type is not supported seller_product_reference: reference: 123ab-5343 source: sap total_products: 1 total_products_imported: 1 total_products_rejected: 1 required: - total_products - total_products_imported - total_products_rejected - sample_products_rejected SummaryProductRejected: type: object properties: error_code: type: string description: The error code example: unsupported_product error_description: type: string description: The error description example: the product type is not supported seller_product_reference: $ref: '#/components/schemas/SellerProductReference' example: error_code: unsupported_product error_description: the product type is not supported seller_product_reference: reference: 123ab-5343 source: sap required: - error_code - seller_product_reference TermsAndConditions: type: object properties: id: type: string description: Unique identifier for the document example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ type: type: string description: >- One of the following categories (purchase, rent , topi_care , topi_care_plus , services , data_deletion_certificate) example: abc123 url: type: string description: Link to the document example: abc123 example: id: 739b63c2-9e58-4964-b38d-4ebb424de242 type: abc123 url: abc123 required: - id - url - type TermsAndConditionsResult: type: object properties: applicable_terms_and_conditions: type: array items: $ref: '#/components/schemas/TermsAndConditions' description: >- Links to the documents in the applicable language for the end customer country code example: - id: 739b63c2-9e58-4964-b38d-4ebb424de242 type: abc123 url: abc123 de: type: array items: $ref: '#/components/schemas/TermsAndConditions' description: Links to the documents in German example: - id: 739b63c2-9e58-4964-b38d-4ebb424de242 type: abc123 url: abc123 en: type: array items: $ref: '#/components/schemas/TermsAndConditions' description: Links to the documents in English example: - id: 739b63c2-9e58-4964-b38d-4ebb424de242 type: abc123 url: abc123 nl: type: array items: $ref: '#/components/schemas/TermsAndConditions' description: Links to the documents in Dutch example: - id: 739b63c2-9e58-4964-b38d-4ebb424de242 type: abc123 url: abc123 example: applicable_terms_and_conditions: - id: 739b63c2-9e58-4964-b38d-4ebb424de242 type: abc123 url: abc123 de: - id: 739b63c2-9e58-4964-b38d-4ebb424de242 type: abc123 url: abc123 en: - id: 739b63c2-9e58-4964-b38d-4ebb424de242 type: abc123 url: abc123 nl: - id: 739b63c2-9e58-4964-b38d-4ebb424de242 type: abc123 url: abc123 required: - de - nl - applicable_terms_and_conditions UnprocessableOffer: type: object properties: message: type: string description: One or more product reference are not supported. example: abc123 name: type: string description: Name of the error example: abc123 references: type: array items: $ref: '#/components/schemas/SellerProductReference' description: Product references that are not supported example: - reference: 123ab-5343 source: sap description: >- UnprocessableOffer is the error returned when one or more product reference is unsupported. example: message: Offer already checked out by the customer name: AlreadyCheckedOut required: - message - name ValidateRequestBody: type: object properties: Accept-Language: type: string example: abc123 customer: $ref: '#/components/schemas/CustomerInfo' draft_offer_id: type: string description: The ID of the draft offer from which an offer is being created example: abc123 exit_redirect: type: string description: >- 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` example: https://example.com/foo format: uri expires_at: type: string description: Expiration date and time for the offer (UTC) example: '1970-01-01T00:00:01Z' format: date-time lines: type: array items: $ref: '#/components/schemas/OfferLinePayload' description: List of product lines example: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 minItems: 1 metadata: type: object description: >- Metadata you can attach to and offer. You can store here any JSON information example: affiliate_code: '123456' additionalProperties: type: string example: aaa maxLength: 400 sales_agent: $ref: '#/components/schemas/SalesAgent' sales_channel: type: string description: Channel from where the offer is created example: ecommerce enum: - telesales - ecommerce - in_store_pos seller_offer_reference: type: string description: Seller's own reference for the offer example: ref-1234 shipping: $ref: '#/components/schemas/ShippingInfo' shipping_address: $ref: '#/components/schemas/ShippingAddress' success_redirect: type: string description: >- 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` example: https://example.com/foo format: uri example: Accept-Language: abc123 customer: company: billing_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' region: Bavaria name: Unicorn Corp tax_number: '123456789' vat_number: DE123456789 customer_group: education email: alice@example.com full_name: John Butler phone_number: abc123 draft_offer_id: abc123 exit_redirect: https://example.com/foo expires_at: '1970-01-01T00:00:01Z' lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap sub_lines: - base_rental_price: currency: EUR gross: 119000 net: 100000 bundle_index: abc123 price: currency: EUR gross: 119000 net: 100000 product_id: abc123 quantity: 2 seller_product_reference: reference: 123ab-5343 source: sap subtitle: abc123 title: abc123 subtitle: abc123 title: abc123 metadata: affiliate_code: '123456' sales_agent: email: alice@example.com external_agent_id: abc123 name: abc123 phone: abc123 sales_channel: ecommerce seller_offer_reference: ref-1234 shipping: is_in_store_pickup: false price: currency: EUR gross: 119000 net: 100000 seller_shipping_reference: Sandbox Shipping Service shipping_address: city: Munich country_code: DE line1: 10 Downing Street line2: Flat 42 postal_code: '10243' recipient_name: Felix Wolf region: Bavaria success_redirect: https://example.com/foo required: - seller_offer_reference - expires_at - lines - sales_channel ValidateResult: type: object properties: pricing_overview: $ref: '#/components/schemas/PricingOverview' description: Purchase overview of the validated offer example: pricing_overview: breakdown: - amount: currency: EUR gross: 119000 net: 100000 title: Monthly (x36) tooltip: >- The first rent fee is included in the first payment. More details later, in topi checkout. instead_of_amount: currency: EUR gross: 119000 net: 100000 items_summaries: - identifier: abc123 pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 pay_now_excluding_sublines: pay_now_amount: currency: EUR gross: 119000 net: 100000 rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 rent_excluding_sublines: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 total_pay_now: pay_now_amount: currency: EUR gross: 119000 net: 100000 total_rent: - duration: 12 monthly_amount: currency: EUR gross: 119000 net: 100000 shipping_amount: currency: EUR gross: 119000 net: 100000 total_amount: currency: EUR gross: 119000 net: 100000 required: - pricing_overview ValidationError: type: object properties: code: type: string description: Error code example: abc123 field: type: string description: Field name example: abc123 message: type: string description: Error message example: abc123 example: code: abc123 field: abc123 message: abc123 required: - field - code - message ValidationErrorList: type: object properties: errors: type: array items: $ref: '#/components/schemas/ValidationError' description: List of errors example: - code: abc123 field: abc123 message: abc123 message: type: string description: Error message example: abc123 example: errors: - code: abc123 field: abc123 message: abc123 message: abc123 required: - errors - message VoidRequestBody: type: object properties: superseded_by_id: type: string description: The topi offer ID of the offer that supersedes this voided one example: 739b63c2-9e58-4964-b38d-4ebb424de242 format: regexp pattern: ^[0-9A-Za-z\-]+$ example: superseded_by_id: 739b63c2-9e58-4964-b38d-4ebb424de242 WidgetsCartRentalOverviewRequestBody: type: object properties: products: type: array items: $ref: '#/components/schemas/RentalOverviewRequest' example: - base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 quantity: 1 seller_product_reference: reference: 123ab-5343 source: sap widget_id: type: string example: abc123 example: products: - base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 quantity: 1 seller_product_reference: reference: 123ab-5343 source: sap widget_id: abc123 required: - products - widget_id WidgetsListRecommendedRentalPricesRequestBody: type: object properties: pricing_requests: type: array items: $ref: '#/components/schemas/PricingRequest' description: List of product pricing to request. example: - base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 seller_product_reference: reference: 123ab-5343 source: sap widget_id: type: string example: abc123 example: pricing_requests: - base_rental_price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 price: currency: EUR gross: 119000 net: 100000 tax_rate: 1900 seller_product_reference: reference: 123ab-5343 source: sap widget_id: abc123 required: - pricing_requests - widget_id securitySchemes: OAuth2Seller_header_Authorization: type: oauth2 description: > Read our [Integration Guide](https://docs.topi.eu/docs/integration-guide/authentication) for detailed instructions on how to authenticate. flows: clientCredentials: tokenUrl: https://identity.topi.eu/oauth2/token refreshUrl: https://identity.topi.eu/oauth2/token scopes: seller-branding:read: read seller branding config seller-catalog:edit: add product to catalog seller-catalog:read: view and search catalog seller-metrics:read: read metrics urls seller-offer:edit: edit offer details seller-offer:read: read offer details seller-order:edit: edit order details seller-order:read: read order details seller-scenario-simulations:run: run scenario simulations seller-shipment:edit: edit shipment details seller-shipping-method:edit: edit seller shipping method details seller-shipping-method:read: read seller shipping method details user-info:read: read user info tags: - name: catalog description: Topi catalog for sellers - name: offer description: > 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](#tag/offer/operation/offer#show) - `id`: `string` - `created_at`: `string ` - `status`: `string enum: "accepted" | "declined" | "pending_review" | "voided" | "expired"` - `checkout_redirect_url`: `string ` - name: order description: > Provides operations to handle orders for end-customers. ## Webhooks We will ping the URL provided whenever an order has changed its status to: `"created"`, `"completed"`, or `"canceled"`. **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` - name: shipment description: >- #### 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. - name: shippingMethod description: | Provides operations to handle shipping-related tasks.