Skip to content

ClickBank API

The ClickBank REST API is vendored as OpenAPI JSON schemas under clickbank-api/ schemas and consumed from @brandvelia/integrations. This page maps the vendored API to how Brandvelia uses it. Read the raw schemas first, then the usage below.

Files

File API Version
products-v2.json Products & funnels v2 /v2/sellers/{accountName}
orders-v2.json Orders & refunds v2 /v2/orders
analytics-v1.json Analytics & subscriptions v1 /rest/1.3/analytics

Products API (products-v2)

Base path: GET /v2/sellers/{accountName} (accountName pattern [a-zA-Z\d]{5,10}).

Read

  • GET /products → searchProducts — list products with title, urlAlias, status (DRAFT, PENDING_APPROVAL, UNDER_REVIEW, ACTION_REQUIRED, APPROVED, DISAPPROVED, INACTIVE), skus[], versions[], active (boolean).
  • GET /categories → getSkuCategories.
  • GET /products/{productId} → getProduct; GET /products/{productId}/offerSplit → getProductOfferSplit.
  • GET /funnels, /funnels/{funnelId}/upsellFlows, /orderBumps, /itemSets, /customTexts, /images, /compliance/documents.
  • GET /shipping/regions → getShippingRegions.

Create / update / delete

  • POST /products, POST /products/{productId}/sku → createProduct / createSku.
  • POST /funnels, /upsellFlows, /orderBumps, /itemSets, /customTexts, /images.
  • PUT /status (action: SUBMIT_FOR_APPROVAL, REVERT_TO_DRAFT) → updateProductStatus.
  • All resources support update* and DELETE.

Key types

  • MonetaryAmount — { amount: number, currency: string } (ISO 4217, e.g. USD).
  • Subscription — frequencyType/offsetType (YEAR, MONTH, WEEK, DAY), recurrences, offset, notificationOffset.

Orders API (orders-v2)

Base path: GET /v2/orders.

Read

  • GET /orders (getOrders) — filters: seller, startDate (required), transactionType (enum), funnelId, skuId, customerEmail, customerLastName, page, size, sort.
  • GET /orders/{receipt} → getOrder.

Refunds & updates

  • POST /orders/{receipt}/transactions/refund → processRefund (RefundRequest: amount, refundType (FULL, PARTIAL_AMOUNT), reason).
  • PUT /orders/{receipt}/customer/shippingCustomer → updateOrderCustomerInfo.

Key types

  • Transaction — type (SALE, BILL, RFND, CGBK, TEST*), amount, taxAmount, details, itemSets[].
  • Receipt — the path key across all receipt operations (e.g. ABCD1234).
  • Payment → Card (payment method), with marketingConsent.
  • Order view — billed, shipping, tax, fee, payouts per item.

Analytics API (analytics-v1)

Base path: GET /rest/1.3/analytics/{role}/{dimension} (role: vendor, affiliate; account pattern ^[a-z0-9]{5,10}$).

Summary vs. detail

  • GET .../summary → getAnalyticsData.
  • GET .../{dimension} → getAnalyticsData_1.

Dimensions

affiliate, vendor, vendor_category, customer_currency, customer_country, customer_province, customer_language, product_sku, tracking_id, vendor_product_sku.

Subscription detail rollups

/subscription/details/* — nextpmtdate, canceldate, startdate, cancelthirty, compsixty, trends, details/status, details. status enum: active, completed, canceled, retry_payment, request_new_card.

Subscription row fields

affNickName, chargebackAmount, chargebackCount, countryCode, currencyCode, customerDisplayName, email, frequency, ftxnId, futurePaymentsCount, initialSaleAmount, initialSaleCount, receipt, refundAmount, refundCount, returnCount, status, subCancelDate, subEndDate, subValue.

31 orderable metric dimensions

DIMENSION_VALUE · CHARGEBACK_AMOUNT · CHARGEBACK_COUNT · CHARGEBACK_RATE ·
EARNINGS_PER_CLICK · EARNINGS_PER_HOP · GROSS_SALE_AMOUNT · GROSS_SALE_COUNT ·
HOP_COUNT · HOPS_PER_SALE · INITIAL_ORDER_IMPRESSION · NET_SALE_AMOUNT · NET_SALE_COUNT ·
ORDER_FORM_SALE_CONVERSION · ORDER_IMPRESSION · ORDER_SUBMISSION · REBILL_AMOUNT ·
REBILL_COUNT · REFUND_AMOUNT · REFUND_COUNT · REFUND_RATE · SALE_AMOUNT · SALE_COUNT ·
TOTAL_ORDER_IMPRESSION · UPSELL_AMOUNT · UPSELL_COUNT · UPSELL_ORDER_IMPRESSION

How Brandvelia uses the API

  • Marketplace feed (getProductsCSV / getMarketplaceFeedEntryId) seeds offers_src → marketplaces → snapshots.
  • LinkBuilder builds tracked landing URLs (createLinkBuilder, getLinkBuilderUrl).
  • INS webhooks decode campaign/order events and attribute them to visits.
  • QuickStats normalizes order payloads.
  • Opportunity Score (createBVProductScore) scores products for the Radar.

The API schemas here are read-only reference; Brandvelia's own metric definitions (net revenue, profit, ROAS) remain its own deterministic SQL — never derived from ClickBank's raw numbers.