API and Integrations — Help Center viva

Help Center › Technical Support › API and Integrations

API and Integrations

REST API, webhooks, OAuth authorization, SDK for developers, and ready integrations with popularpopular platforms

Getting Started with API

viva provides a powerful REST API for automating operations, integrations with your systemsaters and creation custom apps.

ℹ️ Basic information:

Base URL: https://api.shookout.com/v1
Protocol: HTTPS only (TLS 1.2+)
Format: JSON (application/json)
authorization: API Keys or OAuth 2.0
Rate Limits: 100 requests/minute (Free), up to 10,000/minute (Enterprise)
Documentation: docs.shookout.com/api

Receiving API key

Log into your account

Go to on shookout → Log into your account → Open Dashboard.
Open settings API

Settings → Developer → API Keys → Click "Create New API Key".
Configure access permissions

Select scope (resolution of): read:products, write:products, read:orders, write:orders, read:analytics, webhooks. Principle minimum privileges — only required rights.
Save key

Copy API Key and Secret — they are shown ONLY ONCE. Store them securely (for example in the .env file, NOT in the code). If lost — delete key and create new.

First request

cURL

curl -X GET "https://api.shookout.com/v1/products" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

JavaScript

const response = await fetch('https://api.shookout.com/v1/products', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

Python

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.get('https://api.shookout.com/v1/products', headers=headers)
data = response.json()
print(data)

Main endpoints

Product management

GET /v1/products

Get a list of all your products. Supports pagination, filters by categories, status, date.

GET /v1/products/{id}

Get detailed information about a specific product by its ID.

POST /v1/products

Create a new product. Required: title, description, price, category, files.

PUT /v1/products/{id}

Update an existing product. You can update any fields partially (PATCH-like behavior).

DELETE /v1/products/{id}

Delete the product. WARNING: Irreversible action. The product will be deleted together with all associated statistics.

Order payments

GET /v1/orders

get list all orders (how seller) or purchases (how buyer).

GET /v1/orders/{id}

Get details of a specific order, including payment information and download links.

POST /v1/orders/{id}/refund

Create a refund for an order. Required reason and optional partial amountunt.

Analytics

GET /v1/analytics/sales

Get sales statistics: revenue, number of sales, average order value by period (day/week/month/year)ear).

GET /v1/analytics/products

Analytics by products: views, conversion, popularity, rating.

GET /v1/analytics/customers

Statistics by buyers: new vs returning, LTV, geography, demographics.

Account management

GET /v1/account

Get information about the current account: profile, balance, plan, statistics.

PUT /v1/account

Update account settings: name, email, avatar, biography, social networks.

Webhooks (Webhooks)

Webhooks allow you to receive real-time notifications about events on the platform without constant polling of the API.

Setup webhooks

Create an endpoint on your server

Configure a URL that will receive POST requests from our system. Must respond with 200 OK within the period of 5 seconds. Example: https://yoursite.com/webhooks/v-marketplace
Register the webhook

Settings → Developer → Webhooks → Create Webhook → Enter URL → Select events you want to receiveeceive → Save.
Check signature

Each request is signed with HMAC-SHA256. Check the X-Webhook-Signature header for security. The secret for signing is shown when creating webwebhook.

Available events

order.created

New order created. Sent immediately after successful payment by the buyer.

order.completed

Order completed and funds credited to your balance after the refund period ends.

↩️

order.refunded

Refund created. Funds are returned to the buyer, commission is not refunded.

product.published

your product published and accessible for purchases after moderation.

⭐

review.created

Buyer left a review on your product. Includes rating and review text.

message.received

New message received from buyer or support.

payout.processed

Payout processed and sent to your bank account or PayPal.

product.rejected

Product rejected by moderation. Includes rejection reason and recommendations.

Webhook processing example

Node.js (Express)

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

app.post('/webhooks/v-marketplace', (req, res) => {
  // Verify signature
  const signature = req.headers['x-webhook-signature'];
  const body = JSON.stringify(req.body);
  const hash = crypto.createHmac('sha256', WEBHOOK_SECRET)
    .update(body).digest('hex');
  
  if (signature !== hash) {
    return res.status(401).send('Invalid signature');
  }

  // Process event
  const { event, data } = req.body;
  
  switch (event) {
    case 'order.created':
      console.log('New order:', data.order_id);
      // Send email, update inventory, etc
      break;
    
    case 'order.refunded':
      console.log('Refund processed:', data.order_id);
      break;
    
    default:
      console.log('Unknown event:', event);
  }

  res.status(200).send('OK');
});

Important for webhooks:

Always verify the request signature — this protects against fake requests
Respond 200 OK quickly (<5 sec) — long processing should be done asynchronously
Implement idempotency — one webhook may arrive multiple times
Store webhook_secret securely (use environment variables)
Log all incoming webhooks for debugging

OAuth 2.0 authorization

for apps which work from name users use OAuth 2.0 for up to API keys.

OAuth Flow (Authorization Code)

Register app

Settings → Developer → OAuth Apps → Create App → Specify name, redirect URI, scope → Get Client ID and Client Secret.
Redirect user

Send user on: https://shookout.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT&scope=read:products,write:orders&response_type=code
Get authorization code

After granting access, the user will be redirected to your redirect_uri?code=AUTHORIZATION_CODEION_CODE
Exchange code on token

POST https://api.shookout.com/v1/oauth/token with client_id, client_secret, code, redirect_uri → Get access_token and refresh_token.
Use access token

Make API requests with the header: Authorization: Bearer ACCESS_TOKEN. Token is valid for 1 hour.
Update token

When access_token expires — use refresh_token to get a new one: POST /oauth/token with grant_type=refresh_token.

SDK and libraries

Official SDKs simplify integration with our API:

JavaScript / TypeScript

Official

Full-featured SDK for Node.js and browser. Supports async/await, TypeScript types, automatic retry, rate limiting.

Documentation

Python

Official

Pythonic SDK with support sync/async, type hints, dataclasses. works with Python 3.8+. Includes CLI utilities for quick testing.

Documentation

Ruby

Official

Elegant gem for Ruby and Rails apps. Includes ActiveRecord/ActiveModel integration, generators for Rails.

Documentation

PHP

Official

Composer package for PHP 7.4+. PSR compatible, works with Laravel, Symfony, WordPress. Includes Eloquent models for Laravel.

Documentation

Official

Idiomatic Go SDK with generics (Go 1.18+), context support, structured logging. Optimized for high-performance apps.

Documentation

Java

Official

Maven/Gradle library for Java 11+. Full support CompletableFuture, reactive streams (Project Reactor).

Documentation

Installation SDK (examples)

npm (JavaScript)

npm install @v-marketplace/sdk

pip (Python)

pip install v-marketplace-sdk

Composer (PHP)

composer require v-marketplace/sdk

Rate Limits

Restrictions frequent requests depend from your pricing plan:

Pricing plan	Requests/minute	Requests/hour	Burst
Free	100	2,000	150
Basic	500	10,000	750
Pro	2,000	50,000	3,000
Business	5,000	150,000	7,500
Enterprise	10,000	500,000	15,000

ℹ️ Rate Limit Headers: Each API response includes headers:

X-RateLimit-Limit — maximum requests in minute
X-RateLimit-Remaining — remaining requests
X-RateLimit-Reset — rate limit reset time (Unix timestamp)

When the limit is exceeded you receive 429 Too Many Requests with the header Retry-After.

Ready-made integrations

Integrate shookout with popular platforms without programming:

Zapier

Available

Connect shookout to 5000+ apps via Zapier. No-code automation: new sale → send to Google Sheetse Sheets, create task in Asana, etc.

Connect

Make (Integromat)

Available

Visual automation with Make. Create complex scenarios: new order → check in CRM → send notificationpersonalizationized email.

Connect

Mailchimp

Available

Synchronization of buyers with Mailchimp. Automated email campaigns: welcome new buyersyers, follow-up after purchases, re-engagement.

Connect

Google Analytics

Available

Sending sales events and conversions to Google Analytics. Track marketing effectiveness, ROIOI, customer journey.

Connect

Slack

Available

Notifications about sales directly in Slack. Configure channel for your team: new orders, refundsreviews — everything in real time.

Connect

Discord

Available

Discord webhooks for notifications. Send messages about new sales to your Discord server and community.

Connect

HubSpot

Coming soon

Synchronization with HubSpot CRM. Automatic creation of contacts, deals, interaction trackingractions with buyer.

⏳ In development

Notion

Coming soon

Synchronization of data with Notion. Automatic creation of databases with sales, buyers, statistics for analysis in Notion.

⏳ In development

Frequently asked questions

How many worth use API?

API is free on all plans. You pay only for platform use (commission on sales). Rate limits depend from plan, but Basic Free plan (100 req/min) enough for most integrations. for high-load apps recommend Business or Enterprise.

Is it necessary to resolution for use API?

No, API is available to all registered users. Simply create an API key in settings. If you're building an app for other users(not only for yourself) — use OAuth 2.0 and register OAuth App in Developer Settings.

Which API version is current?

Current version: v1 (stable). We guarantee backward compatibility within major versions (breaking changes only when transition to v2). Old versions is supported minimum 12 months after releasefor new versions. Follow for anonyourself API changes in Developer Newsletter.

How to test the API without affecting production?

Use Test Mode: Settings → Developer → Test Mode → Enable. In test mode: payments are not processedrocessed (use Stripe test cards), all data is isolated from production, webhooks are on test endpoints. A break between test/live ers in dashboard.

Is it supported GraphQL?

Currently only REST API. GraphQL API is planned for Q3 2025. It will be available alongside REST REST (not replaces its). If you needed GraphQL — write to us, we added you in list early tracker GraphQL beta.

how process errors API?

API returns standard HTTP codes: 200 OK (success), 400 Bad Request (validation), 401 Unauthorizedhorized Unauthorized (no/incorrect token), 403 Forbidden (not enough rights), 404 Not Found, 429 Too Many Requests (rate limit), 500 Server Error. All errors always JSON: {"error": {"code": "...", "message": "...", "details": {...}}}. Retry for 429 and 5xx, not retry for 4xx.

Can I upload files in API?

Yes! Use POST /v1/uploads with multipart/form-data. Maximum file size: 500 MB via API (for large files use resumable upload)uploads — documentation in API docs). after uploads get file_id which you can with to the product in POST /v1/products.

Is pagination supported?

Yes, all list endpoints support cursor-based pagination. Parameters: limit (default 20, max 100), cursor (for next page). Response includes: data[], has_more (boolean), next_cursor (string). Example: GET /v1/products?limit=50&cursor=abc123.

Which scope (resolution of) available for OAuth?

Available scopes: read:products, write:products, read:orders, write:orders (refunds), read:analytics, read:account, write:account, webhooks (webhook management). Use minimum necessary permissions. User sees the list of permissions of when authorization your app.

Where get help by API?

Resources for developers: (1) Full documentation API, (2) GitHub examples and SDK, (3) Developer Community forum, (4) Email support (response within 24h), (5) Discord #developers channel for quick questions.

Need help with integration?

Our developer team will help with API setup and integrations

Contact dev support

API and Integrations

Getting Started with API

Receiving API key

First request

Main endpoints

Product management

Order payments

Analytics

Account management

Webhooks (Webhooks)

Setup webhooks

Available events

Webhook processing example

OAuth 2.0 authorization

OAuth Flow (Authorization Code)

SDK and libraries

Installation SDK (examples)

Rate Limits

Ready-made integrations

Frequently asked questions

Need help with integration?

Configure browser push notifications

Chrome (Android)

Chrome (Desktop)

Safari (iOS 16.4+)

Safari (macOS)

Edge (Android)

Edge (Desktop)

Firefox (Android)

Firefox (Desktop)