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 `
openapi: 3.0.3
info:
title: topi Seller catalog offer 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
tags:
- name: offer
description: "Provides operations to handle offers for end-customers.\n\n## Webhooks\n\n### OfferUpdates\n\nWe will ping the URL provided whenever an offer has changed its status to: `\"accepted\"`, `\"declined\"`, `\"voided\"`, `\"pending_review\"` or `\"expired\"`.\n\n**Payload**:\n\n- same as [show offer](#tag/offer/operation/offer#show)\n - `id`: `string`\n - `created_at`: `string <date-time>`\n - `status`: `string enum: \"accepted\" | \"declined\" | \"pending_review\" | \"voided\" | \"expired\"`\n - `checkout_redirect_url`: `string <uri>`\n"
paths:
/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 \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\"\n"
- lang: javascript
label: JavaScript (fetch)
source: "const response = await fetch('https://seller-api.topi.eu/v1/offers', {\n method: 'GET',\n headers: {\n 'Authorization': `Bearer ${ACCESS_TOKEN}`\n }\n});\n\nconst data = await response.json();\nconsole.log(data);\n"
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 n
# --- truncated at 32 KB (244 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/topi/refs/heads/main/openapi/topi-offer-api-openapi.yml