Simulating Scenarios

Simulating Scenarios in the Sandbox

In addition to the live APIs, the sandbox environment provides an API for running scenario simulations. These scenario simulations allow you to trigger certain cases via the API so you can:

test how your integration behaves in response to such cases (e.g when a customer accepts/declines an offer)
set up the topi seller API to respond in a certain manner (e.g what happens when I try to create an offer with an unsupported product)

Scenario simulations can be triggered by making a POST request to the v1/scenario_simulations/{scenario_name} endpoint and providing input as a JSON payload in the body of the request. These inputs are specific to the scenario, for example:

the ID of an offer to mark as accepted/declined or
a collection of product IDs to mark as unsupported.

⚠️ Important: Required Offer & Order Status for Scenario Simulation

Before simulating scenarios, it's essential to ensure that the offer or order is in the correct status. Simulations are designed to mimic transitions and require specific initial states to proceed successfully. Attempting to skip statuses or simulate actions in the wrong state will result in an error.

For example, trying to decline an offer that's still in the created state will return:

Error when simulating scenario mark_offer_declined: offers with status=created cannot be declined

In this case, the offer must first be moved to the pending_review status before it can be declined.

Refer to the Core Resources: Offer Status Updates documentation to understand the valid status transitions.

✅ Valid Flow Example

If you want to simulate declining an offer:

Start by creating an offer (status: created).
Simulate mark_offer_for_review.
Then simulate mark_offer_declined.

Following the correct status flow ensures your simulations work as expected and reflect realistic behavior.

You can see the list below for a comprehensive list of scenarios as well as example inputs:

How to trigger a scenario simulation?

All scenarios use the same endpoint, so in order to trigger a specific scenario you need to make a POST request to the v1/scenario_simulations/{scenario_name} endpoint.

Replace scenario_name with the name of the scenario you want to trigger
Include relevant scenario inputs as a JSON body to the request.
See curl example below, to trigger the “Accept Offer” scenario:

PAYLOAD='{
 "scenario_input": {
   "id" : "c14bba4f-5388-4680-b6ea-27a77ca20444"
 }
}'

curl -X POST \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -d "$PAYLOAD" \
'https://seller-api-sandbox.topi-sandbox-staging.eu/v1/scenario_simulations/mark_offer_accepted'

Responses

When a scenario simulation is triggered:

a 200 OK response indicates that the simulation was successfully executed.
a 400 Bad Request response indicates that the supplied scenario_input field has been incorrectly formatted (see Supported Scenarios below for valid examples)
a 422 Unprocessable response indicates that there was an error running the simulation.

Supported Scenarios

Accept Offer

Scenario Name: mark_offer_accepted

Input Schema: id (string): The ID of the offer to mark as accepted.

Sample Payload:

PAYLOAD='{
  "scenario_input": {
    "id" : "c14bba4f-5388-4680-b6ea-27a77ca20444", // an offer ID
  }
}'

Decline Offer

Scenario Name: mark_offer_declined

Input Schema: id (string): The ID of the offer to mark as declined.

Sample Payload:

PAYLOAD='{
  "scenario_input": {
    "id" : "c14bba4f-5388-4680-b6ea-27a77ca20444", // an offer ID
  }
}'

Mark Offer For Review

Scenario Name: mark_offer_for_review

Input Schema: id (string): The ID of the order to mark as pending_review.

Sample Payload:

PAYLOAD='{
  "scenario_input": {
    "id" : "c14bba4f-5388-4680-b6ea-27a77ca20444", // an offer ID
  }
}'

Void Offer

Scenario Name: mark_offer_voided

Input Schema: id (string): The ID of the offer to mark as void.

Sample Payload:

PAYLOAD='{
  "scenario_input": {
    "id" : "c14bba4f-5388-4680-b6ea-27a77ca20444", // an offer ID
  }
}'

Mark Product Unsupported

Scenario Name: mark_product_unsupported

Input Schema: ids (array): A collection of product IDs to mark as unsupported.

Sample Payload:

PAYLOAD='{
  "scenario_input": {
    "ids" : [
      // A list of Product IDs
      "c14bba4f-5388-4680-b6ea-27a77ca20444",
      "4827b7a6-d65c-42a6-9492-8bba2d0ae0e3"
    ]
  }
}'

Mark Shipping Method Unsupported

Scenario Name: mark_shipping_method_unsupported

Input Schema: ids (array): A collection of shipping method IDs to mark as unsupported.

Sample Payload:

PAYLOAD='{
  "scenario_input": {
    "ids" : [
      // A list of Shipping Method IDs
      "c14bba4f-5388-4680-b6ea-27a77ca20444",
      "4827b7a6-d65c-42a6-9492-8bba2d0ae0e3"
    ]
  }
}'

Cancel Order

Scenario Name: mark_order_cancelled

Input Schema: id (string): The ID of the order to mark as cancelled.

Sample Payload:

PAYLOAD='{
  "scenario_input": {
    "id" : "c14bba4f-5388-4680-b6ea-27a77ca20444", // an order ID
  }
}'

Simulating Scenarios