// guide

Quickstart

From signing in to a completed order with reviews, in test mode. Every call here runs from a terminal.

1. Sign in and copy a test key

Go to marketsdk.com/app and enter your email. We send a code and a link; either signs you in. No password.
Your workspace is made for you, with a test marketplace and a live one. You start in test mode, with no card and no time limit.
Under api keys, create a secret key and copy it. It starts msk_test_sk_ and is shown once.

$ shellkeep it out of your code

export MARKETSDK_KEY=msk_test_sk_...

2. Turn payments off, for now

A new marketplace takes payments through your Stripe account and asks sellers to verify their identity. To see the whole flow before you connect Stripe, open marketplace in test mode and switch off payments and seller verification. Switch them back on when you follow payments and payouts.

3. Create a seller and a buyer

Your users are not our users. Each exists here as a seller or a buyer record, with your own id for them as external_id.

POST /v1/sellersrequest

curl https://api.marketsdk.com/v1/sellers \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "user_1001", "display_name": "Ada Cycles"}'

POST /v1/buyersrequest

curl https://api.marketsdk.com/v1/buyers \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "user_2002", "display_name": "Grace"}'

Each answers with an id: sel_... and buy_.... The next steps use them.

4. List something and publish it

Money is always an integer in minor units with the marketplace currency. 45000 in USD is $450.00.

POST /v1/listingsrequest

curl https://api.marketsdk.com/v1/listings \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seller": "sel_...", "title": "Steel road bike, 56 cm",
       "price": {"amount": 45000, "currency": "USD"}}'

POST /v1/listings/{id}/publishrequest

curl -X POST https://api.marketsdk.com/v1/listings/lst_.../publish \
  -H "Authorization: Bearer $MARKETSDK_KEY"

A published listing appears in GET /v1/search/listings, which a publishable key may call from your web page.

5. Order it, and finish the deal

Your server says which user is acting, as actor. We check that they are a party to the order and may make the change. With payments off, a new order is committed at once.

POST /v1/ordersthe buyer commits

curl https://api.marketsdk.com/v1/orders \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-user_2002-1" \
  -d '{"listing": "lst_...", "buyer": "buy_..."}'

POST /v1/orders/{id}/claimthe seller says it is done

curl https://api.marketsdk.com/v1/orders/ord_.../claim \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"actor": "sel_..."}'

POST /v1/orders/{id}/confirmthe buyer agrees

curl https://api.marketsdk.com/v1/orders/ord_.../confirm \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"actor": "buy_..."}'

The order is completed. Both parties get an order_completed reputation event.

6. Review each other

POST /v1/orders/{id}/reviewsrequest

curl https://api.marketsdk.com/v1/orders/ord_.../reviews \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"actor": "buy_...", "rating": 5, "body": "As described."}'

A review stays hidden until the other party reviews too, or the review window closes, so neither can retaliate. Then read the seller's reputation from GET /v1/sellers/sel_....

7. Watch it happen

Every call you made is under logs in the dashboard, with its status and request_id. Every change made an event; add an endpoint under webhooks to receive them.

next: authentication