Skip to main content

Testing end-to-end flow

This is the final step of the integration guide. By now you have authenticated, synced your catalog, set up shipping methods, registered a webhook endpoint, and learned how to get rental prices, create offers, receive orders, and create shipments. This page shows you how to validate the whole integration before going live.

An end-to-end test proves that the individual pieces of your integration work together as one flow: an offer you create progresses through review and acceptance, the resulting order reaches your webhook endpoint, and you can fulfil that order with a shipment. It runs entirely in the topi sandbox, so no real customers, contracts, or payments are involved.

The sandbox behaves like production, with two conveniences that make testing fast. First, every product you import is automatically marked as supported, up to a limit of 10,000 items, so you do not have to wait for catalog review. Second, the sandbox exposes a Scenario Simulation API that lets you drive an offer or order through its lifecycle on demand, without a real customer going through checkout. See Introduction to the sandbox and Simulating scenarios for the full reference.

All requests on this page use the sandbox hosts:

  • Seller API: https://seller-api-sandbox.topi-sandbox.eu/
  • Identity (token): https://identity.topi-sandbox.eu/oauth2/token

Before you start​

Confirm the following before running an end-to-end test:

  • You have sandbox API credentials (a sandbox client_id and client_secret). See Authentication.
  • Your catalog is synced to the sandbox. See Syncing your catalog. In the sandbox, imported products are marked as supported automatically.
  • At least one shipping method exists in the sandbox. See Setting up shipping methods.
  • Your webhook endpoint is reachable and registered for the sandbox. See Setting up webhooks. If your endpoint is not publicly reachable yet, use a tunnelling tool so the sandbox can deliver events to it.

Happy path​

The steps below take an offer from creation through to a shipped order. Run them in order.

1. Get a sandbox access token​

Exchange your sandbox credentials for an access token against the sandbox identity host.

curl -u $CLIENT_ID:$CLIENT_SECRET \
  -d 'grant_type=client_credentials&scope=client' \
  'https://identity.topi-sandbox.eu/oauth2/token'

Use the returned access_token as a bearer token for every request that follows.

2. Create an offer​

Create an offer exactly as you would in production. See Creating an offer for the full request shape.

curl -X POST https://seller-api-sandbox.topi-sandbox.eu/v1/offers \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @offer.json

A newly created offer starts in status created. Note the offer id from the response, you will use it to drive the simulation.

3. Simulate the offer moving to review​

In production, an offer moves through review based on a customer completing checkout and topi running its risk assessment. In the sandbox you drive this yourself with the Scenario Simulation API.

Simulations require the correct starting status. An offer in status created cannot be accepted or declined directly, so first move it to pending_review.

curl -X POST https://seller-api-sandbox.topi-sandbox.eu/v1/scenario_simulations/mark_offer_for_review \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scenario_input": {"id": "YOUR_OFFER_ID"}}'

A 200 response means the scenario ran and the offer is now in pending_review. This also triggers an offer.pending_review webhook. A 400 means the scenario_input was malformed, and a 422 means the simulation could not run against the offer in its current state.

4. Simulate the offer being accepted​

With the offer in pending_review, simulate acceptance.

curl -X POST https://seller-api-sandbox.topi-sandbox.eu/v1/scenario_simulations/mark_offer_accepted \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scenario_input": {"id": "YOUR_OFFER_ID"}}'

The offer moves to accepted, and topi creates an order from it.

5. Verify your webhooks​

Check that your endpoint received both events from the steps above:

  • offer.accepted when the offer reached accepted.
  • order.created when topi created the order from the accepted offer.

If these did not arrive, your integration will not learn about real orders in production. Confirm your endpoint is reachable and your subscription is correct before continuing. See Setting up webhooks.

6. Acknowledge and accept the order​

Fulfil the order the same way you would in production. See Receiving and fulfilling orders. Acknowledge that you received the order, then accept it to confirm you will fulfil it.

curl -X POST https://seller-api-sandbox.topi-sandbox.eu/v1/orders/YOUR_ORDER_ID/acknowledge \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
curl -X POST https://seller-api-sandbox.topi-sandbox.eu/v1/orders/YOUR_ORDER_ID/accept \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Accepting moves the order to confirmed. If you instead need to test rejecting an order, call POST /v1/orders/{id}/reject.

7. Create a shipment​

Ship the items on the order. See Creating a shipment for serial number handling and partial shipments.

curl -X POST https://seller-api-sandbox.topi-sandbox.eu/v1/shipment \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @shipment.json

Once all items on an order have been shipped, the order can complete and your endpoint receives an order.completed webhook.

At this point you have exercised the full happy path: offer created, reviewed, accepted, turned into an order, confirmed, and shipped.

Test the unhappy paths too​

A complete integration handles outcomes other than acceptance. Use the Scenario Simulation API to exercise each one and confirm your system reacts correctly.

Declined offer​

Create an offer, move it to review, then decline it. As with acceptance, the offer must be in pending_review before it can be declined, so run mark_offer_for_review first.

curl -X POST https://seller-api-sandbox.topi-sandbox.eu/v1/scenario_simulations/mark_offer_for_review \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scenario_input": {"id": "YOUR_OFFER_ID"}}'
curl -X POST https://seller-api-sandbox.topi-sandbox.eu/v1/scenario_simulations/mark_offer_declined \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scenario_input": {"id": "YOUR_OFFER_ID"}}'

Your endpoint receives an offer.declined webhook. No order is created. You can also simulate mark_offer_voided to test the offer.voided event.

Unsupported product​

Mark one or more products as unsupported to confirm your integration stops offering topi for items topi cannot finance.

curl -X POST https://seller-api-sandbox.topi-sandbox.eu/v1/scenario_simulations/mark_product_unsupported \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scenario_input": {"ids": ["YOUR_PRODUCT_ID"]}}'

After this, the product reports can_checkout and has_rental_terms as false, and attempting to create an offer that includes it fails. You can run the equivalent mark_shipping_method_unsupported scenario, passing an array of shipping method ids, to test that path.

Order cancellation​

Take an order through to created, then cancel it.

curl -X POST https://seller-api-sandbox.topi-sandbox.eu/v1/scenario_simulations/mark_order_cancelled \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scenario_input": {"id": "YOUR_ORDER_ID"}}'

Your endpoint receives an order.canceled webhook. Confirm your system releases any reserved stock and updates the order state accordingly.

For reference, the webhook events that can fire across these flows are: offer.pending_review, offer.accepted, offer.declined, offer.voided, offer.expired, order.created, order.canceled, and order.completed.

Going live​

Once the happy path and the unhappy paths behave as expected in the sandbox, you are ready for production. The only changes are the base URLs and credentials:

  • Seller API: switch from https://seller-api-sandbox.topi-sandbox.eu/ to the production host.
  • Identity (token): switch from https://identity.topi-sandbox.eu/oauth2/token to the production token endpoint.
  • Credentials: replace your sandbox client_id and client_secret with your production credentials.

Nothing else about the integration changes. The Scenario Simulation API is a sandbox-only tool, so production offers and orders progress through real customer checkout and topi's risk review instead.